IDCompositionDevice::CreateTargetForHwnd-Methode (dcomp.h)

Artikel
08/23/2023

Erstellt ein Kompositionszielobjekt, das an das Fenster gebunden ist, das durch das angegebene Fensterhandle (HWND) dargestellt wird.

Syntax

HRESULT CreateTargetForHwnd(
  [in]  HWND                hwnd,
  [in]  BOOL                topmost,
  [out] IDCompositionTarget **target
);

Parameter

[in] hwnd

Typ: HWND

Das Fenster, an das das Kompositionszielobjekt gebunden werden soll. Dieser Parameter darf nicht NULL sein.

[in] topmost

Typ: BOOL

TRUE, wenn die visuelle Struktur über den untergeordneten Elementen des durch den hwnd-Parameter angegebenen Fensters angezeigt werden soll; Andernfalls wird die visuelle Struktur hinter den untergeordneten Elementen angezeigt.

[out] target

Typ: IDCompositionTarget**

Das neue Kompositionszielobjekt. Dieser Parameter darf nicht NULL sein.

Rückgabewert

Typ: HRESULT

Wenn die Funktion erfolgreich ist, gibt sie S_OK zurück. Andernfalls wird ein Fehlercode HRESULT zurückgegeben. Eine Liste der Fehlercodes finden Sie unter DirectComposition-Fehlercodes .

Hinweise

Eine visuelle Microsoft DirectComposition-Struktur muss an ein Fenster gebunden sein, bevor alles auf dem Bildschirm angezeigt werden kann. Das Fenster kann ein Fenster auf oberster Ebene oder ein untergeordnetes Fenster sein. In beiden Fällen kann das Fenster ein mehrschichtiges Fenster sein, aber in allen Fällen muss das Fenster zum aufrufenden Prozess gehören. Wenn das Fenster zu einem anderen Prozess gehört, gibt diese Methode DCOMPOSITION_ERROR_ACCESS_DENIED zurück.

Wenn DirectComposition-Inhalte für das Fenster erstellt werden, besteht der Inhalt immer über dem, was direkt über den Gerätekontext (HDC), der von der GetDC-Funktion zurückgegeben wird, oder durch Aufrufe von Microsoft DirectX Present-Methoden direkt in dieses Fenster gezeichnet wird. Da Jedoch Fensterausschnittsregeln für DirectComposition-Inhalte gelten, können diese untergeordneten Fenster die visuelle Struktur abschneiden, wenn das Fenster über untergeordnete Fenster verfügt. Der oberste Parameter bestimmt, ob untergeordnete Fenster die visuelle Struktur ausschneiden.

Konzeptionell besteht jedes Fenster aus vier Ebenen:

Der Inhalt, der direkt in das Fensterhandle gezeichnet wird (dies ist die unterste Ebene).
Eine optionale visuelle DirectComposition-Struktur.
Der Inhalt aller untergeordneten Fenster, falls vorhanden.
Eine weitere optionale visuelle DirectComposition-Struktur (dies ist die oberste Ebene).

Alle vier Ebenen werden in den sichtbaren Bereich des Fensters gekappt.

Höchstens können für jedes Fenster im System nur zwei Kompositionsziele erstellt werden, eins ganz oben und eins nicht ganz oben. Wenn ein Kompositionsziel bereits an das angegebene Fenster auf der angegebenen Ebene gebunden ist, schlägt diese Methode fehl. Wenn ein Kompositionszielobjekt zerstört wird, steht die zusammengestellte Ebene für die Verwendung durch ein neues Kompositionszielobjekt zur Verfügung.

Beispiele

Im folgenden Beispiel wird ein Geräteobjekt erstellt und initialisiert und anschließend das Geräteobjekt an ein Kompositionszielfenster gebunden.

#include <dcomp.h>
#include <d3d11.h>

HRESULT InitializeDirectCompositionDevice(HWND hwndTarget, 
        ID3D11Device **ppD3D11Device, IDCompositionDevice **ppDevice,
        IDCompositionTarget **ppCompTarget)
{
    HRESULT hr = S_OK;
    D3D_FEATURE_LEVEL featureLevelSupported;
    IDXGIDevice *pDXGIDevice = nullptr;

    // Verify that the arguments are valid.
    if (hwndTarget == NULL || ppD3D11Device == nullptr || ppDevice == nullptr || 
                            ppCompTarget == nullptr)
    {
        return E_INVALIDARG;
    }

    // Create the D3D device object. Note that the 
    // D3D11_CREATE_DEVICE_BGRA_SUPPORT flag is needed for rendering 
    // on surfaces using Direct2D. 
    hr = D3D11CreateDevice(
        nullptr,
        D3D_DRIVER_TYPE_HARDWARE,
        NULL,
        D3D11_CREATE_DEVICE_BGRA_SUPPORT, // needed for rendering on surfaces using Direct2D
        NULL,
        0,
        D3D11_SDK_VERSION,
        ppD3D11Device,
        &featureLevelSupported,
        NULL);

    if (SUCCEEDED(hr))
    {
        // Create the DXGI device used to create bitmap surfaces.
        hr = (*ppD3D11Device)->QueryInterface(&pDXGIDevice);
    }

    if (SUCCEEDED(hr))
    {
        // Create the DirectComposition device object.
        hr = DCompositionCreateDevice(pDXGIDevice, __uuidof(IDCompositionDevice), 
                reinterpret_cast<void **>(ppDevice));
    }

    if (SUCCEEDED(hr))
    {
        // Bind the DirectComposition device to the target window.
        hr = (*ppDevice)->CreateTargetForHwnd(hwndTarget, TRUE, ppCompTarget);   
    }

    return hr;
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	dcomp.h
Bibliothek	Dcomp.lib
DLL	Dcomp.dll