IDisplayInformationStaticsInterop::GetForWindow method (windows.graphics.display.interop.h)

Article
02/22/2024

Retrieves a DisplayInformation object for the specified window. GetForWindow always allocates and returns a new DisplayInformation.

Syntax

HRESULT GetForWindow(
  HWND   window,
  REFIID riid,
  void   **displayInfo
);

Parameters

window

Type: [in] HWND

The window's handle.

riid

Type: [in] REFIID

The GUID of the DisplayInformation class.

displayInfo

Type: [iid_is][retval][out] void**

A pointer to a memory block that receives a pointer to the returned DisplayInformation object.

Return value

Type: HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

So that DisplayInformation can process window movements and DPI change messages, it hooks the message loop of your HWND. In order to ensure that that happens smoothly, GetForWindow has the following requirements:

The argument of window must be the HWND of a top-level window that's owned by the current thread.
The current thread must have a Windows.System.DispatcherQueue running, in order to receive events.
The current thread can be MTA or STA.

You're responsible for: caching the created DisplayInformation for as long as the argument of window is relevant; de-registering event handlers; and dropping the last reference in order to destroy the DisplayInformation instance.

Examples

It's vital for an app that renders wide-color gamut and high-dynamic range content to adjust dynamically to changing conditions of the monitor; or when moving between monitors. On a laptop, the user might adjust the brightness of the screen, and that can adjust the tone-mapping parameters provided to apps.

// It's safe, and recommended, to cache the DisplayInformation created from an HWND,
// since it safely provides the latest information and event handlers for when
// changes take place.

#include <Windows.Graphics.Display.Interop.h>
#include <winrt/Windows.Graphics.Display.h>
using namespace winrt::Windows::Graphics::Display;
...
void ReadHdrParametersFromDisplayInformation(HWND myWindow)
{
    auto factory{ winrt::get_activation_factory<DisplayInformation,
        IDisplayInformationStaticsInterop>() };

    DisplayInformation displayInfo{ nullptr };

    winrt::check_hresult(
        factory->GetForWindow(
            myWindow,
            winrt::guid_of<DisplayInformation>(),
            winrt::put_abi(displayInfo)
        )
    );

    auto colorInfo{ displayInfo.GetAdvancedColorInfo() };
    // Here you can read colorInfo properties such as:
    // * CurrentAdvancedColorKind
    // * RedPrimary, BluePrimary, GreenPrimary, WhitePoint
    // * MinLuminanceInNits, MaxLuminanceInNits
    // * MaxAverageFullFrameLuminanceInNits, SdrWhiteLevelInNits
    // ... and adapt your rendering.

    // You can also subscribe event handlers to listen for changes:
    displayInfo.AdvancedColorInfoChanged(
        [&](auto sender, auto args)
        {
            // Handle the event.
        }
    );

    // Cache the DisplayInformation object for as long as your window
    // is alive: it always provides fresh data for your window.
}

Requirements

Requirement	Value
Minimum supported client	Windows 11 Build 22621
Header	windows.graphics.display.interop.h

Share via