Método IDCompositionDevice::CreateTargetForHwnd (dcomp.h)

Artículo
08/23/2023

Crea un objeto de destino de composición enlazado a la ventana representada por el identificador de ventana especificado (HWND).

Sintaxis

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

Parámetros

[in] hwnd

Tipo: HWND

Ventana a la que se debe enlazar el objeto de destino de composición. Este parámetro no debe ser null.

[in] topmost

Tipo: BOOL

TRUE si el árbol visual debe mostrarse encima de los elementos secundarios de la ventana especificada por el parámetro hwnd ; de lo contrario, el árbol visual se muestra detrás de los elementos secundarios.

[out] target

Tipo: IDCompositionTarget**

Nuevo objeto de destino de composición. Este parámetro no debe ser null.

Valor devuelto

Tipo: HRESULT

Si la función se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT. Consulte Códigos de error de DirectComposition para obtener una lista de códigos de error.

Comentarios

Un árbol visual de Microsoft DirectComposition debe enlazarse a una ventana antes de que se pueda mostrar algo en pantalla. La ventana puede ser una ventana de nivel superior o una ventana secundaria. En cualquier caso, la ventana puede ser una ventana superpuesta, pero en todos los casos la ventana debe pertenecer al proceso de llamada. Si la ventana pertenece a un proceso diferente, este método devuelve DCOMPOSITION_ERROR_ACCESS_DENIED.

Cuando el contenido de DirectComposition se compone en la ventana, el contenido siempre se compone sobre todo lo que se dibuja directamente en esa ventana a través del contexto del dispositivo (HDC) devuelto por la función GetDC o por llamadas a los métodos Microsoft DirectX Present . Sin embargo, dado que las reglas de recorte de ventana se aplican al contenido de DirectComposition, si la ventana tiene ventanas secundarias, esas ventanas secundarias pueden recortar el árbol visual. El parámetro superior determina si las ventanas secundarias recortan el árbol visual.

Conceptualmente, cada ventana consta de cuatro capas:

El contenido dibujado directamente en el identificador de ventana (es la capa más baja).
Un árbol visual DirectComposition opcional.
El contenido de todas las ventanas secundarias, si las hay.
Otro árbol visual DirectComposition opcional (es la capa superior).

Las cuatro capas se recortan en la región visible de la ventana.

Como máximo, solo se pueden crear dos destinos de composición para cada ventana del sistema, uno más arriba y uno no superior. Si un destino de composición ya está enlazado a la ventana especificada en la capa especificada, se produce un error en este método. Cuando se destruye un objeto de destino de composición, la capa compuesta está disponible para su uso por un nuevo objeto de destino de composición.

Ejemplos

En el ejemplo siguiente se crea e inicializa un objeto de dispositivo y, a continuación, se enlaza el objeto de dispositivo a una ventana de destino de composición.

#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;
}

Requisitos


Cliente mínimo compatible	Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	dcomp.h
Library	Dcomp.lib
Archivo DLL	Dcomp.dll