Skip to content

Latest commit

 

History

History
134 lines (105 loc) · 4.71 KB

nf-windows-graphics-display-interop-idisplayinformationstaticsinterop-getforwindow.md

File metadata and controls

134 lines (105 loc) · 4.71 KB
Raw
UID title description tech.root ms.date targetos req.assembly req.construct-type req.ddi-compliance req.dll req.header req.idl req.include-header req.irql req.kmdf-ver req.lib req.max-support req.namespace req.redist req.target-min-winverclnt req.target-min-winversvr req.target-type req.type-library req.umdf-ver req.unicode-ansi topic_type api_type api_location api_name f1_keywords dev_langs helpviewer_keywords prerelease
NF:windows.graphics.display.interop.IDisplayInformationStaticsInterop.GetForWindow
IDisplayInformationStaticsInterop::GetForWindow
Retrieves a [DisplayInformation](/uwp/api/windows.graphics.display.displayinformation) object for the specified window.
winrt
05/17/2022
Windows
function
windows.graphics.display.interop.h
Windows 11 Build 22621
apiref
COM
windows.graphics.display.interop.h
IDisplayInformationStaticsInterop::GetForWindow
IDisplayInformationStaticsInterop::GetForWindow
windows.graphics.display.interop/IDisplayInformationStaticsInterop::GetForWindow
c++
GetForWindow
false

-description

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

-parameters

-param window

Type: [in] HWND

The window's handle.

-param riid

Type: [in] REFIID

The GUID of the DisplayInformation class.

-param displayInfo

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

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

-returns

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.
}

-see-also