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

Artigo
08/23/2023

Cria um objeto de destino de composição associado à janela representada pelo identificador de janela especificado (HWND).

Sintaxe

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

Parâmetros

[in] hwnd

Tipo: HWND

A janela à qual o objeto de destino de composição deve ser associado. Esse parâmetro não deve ser NULL.

[in] topmost

Tipo: BOOL

TRUE se a árvore visual deve ser exibida sobre os filhos da janela especificada pelo parâmetro hwnd ; caso contrário, a árvore visual é exibida atrás dos filhos.

[out] target

Tipo: IDCompositionTarget**

O novo objeto de destino de composição. Esse parâmetro não deve ser NULL.

Valor retornado

Tipo: HRESULT

Se a função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT. Confira Códigos de erro do DirectComposition para obter uma lista de códigos de erro.

Comentários

Uma árvore visual do Microsoft DirectComposition deve ser associada a uma janela antes que qualquer coisa possa ser exibida na tela. A janela pode ser uma janela de nível superior ou uma janela filho. Em ambos os casos, a janela pode ser uma janela em camadas, mas em todos os casos a janela deve pertencer ao processo de chamada. Se a janela pertencer a um processo diferente, esse método retornará DCOMPOSITION_ERROR_ACCESS_DENIED.

Quando o conteúdo do DirectComposition é composto para a janela, o conteúdo é sempre composto sobre o que é desenhado diretamente para essa janela por meio do contexto do dispositivo (HDC) retornado pela função GetDC ou por chamadas aos métodos Microsoft DirectX Present . No entanto, como as regras de recorte de janela se aplicam ao conteúdo do DirectComposition, se a janela tiver janelas filho, essas janelas filho poderão recortar a árvore visual. O parâmetro mais alto determina se as janelas filho recortarão a árvore visual.

Conceitualmente, cada janela consiste em quatro camadas:

O conteúdo desenhado diretamente para o identificador de janela (essa é a camada mais inferior).
Uma árvore visual opcional do DirectComposition.
O conteúdo de todas as janelas filho, se houver.
Outra árvore visual opcional do DirectComposition (esta é a camada mais alta).

Todas as quatro camadas são recortadas na região visível da janela.

No máximo, apenas dois destinos de composição podem ser criados para cada janela no sistema, um mais alto e outro não superior. Se um destino de composição já estiver associado à janela especificada na camada especificada, esse método falhará. Quando um objeto de destino de composição é destruído, a camada composta por ele está disponível para uso por um novo objeto de destino de composição.

Exemplos

O exemplo a seguir cria e inicializa um objeto de dispositivo e associa o objeto de dispositivo a uma janela de destino de composição.

#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 com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	dcomp.h
Biblioteca	Dcomp.lib
DLL	Dcomp.dll