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

Cria uma superfície pouco populada que pode ser associada a um ou mais visuais para composição.

Sintaxe

HRESULT CreateVirtualSurface(
  [in]  UINT                        initialWidth,
  [in]  UINT                        initialHeight,
  [in]  DXGI_FORMAT                 pixelFormat,
  [in]  DXGI_ALPHA_MODE             alphaMode,
  [out] IDCompositionVirtualSurface **virtualSurface
);

Parâmetros

[in] initialWidth

Tipo: UINT

A largura da superfície, em pixels. A largura máxima é de 16.777.216 pixels.

[in] initialHeight

Tipo: UINT

A altura da superfície, em pixels. A altura máxima é de 16.777.216 pixels.

[in] pixelFormat

Tipo: DXGI_FORMAT

O formato de pixel da superfície.

[in] alphaMode

Tipo: DXGI_ALPHA_MODE

O significado do canal alfa, se o formato de pixel contiver um canal alfa. Pode ser um dos seguintes valores:

Valor	Significado
DXGI_ALPHA_MODE_UNSPECIFIED	O canal alfa não é especificado. Esse valor tem o mesmo efeito que DXGI_ALPHA_MODE_IGNORE.
DXGI_ALPHA_MODE_PREMULTIPLIED	Os canais de cores contêm valores pré-multiplicados pelo canal alfa.
DXGI_ALPHA_MODE_IGNORE	O canal alfa deve ser ignorado e o bitmap deve ser renderizado opacamente.

[out] virtualSurface

Tipo: IDCompositionVirtualSurface**

O objeto surface recém-criado. Esse parâmetro não deve ser NULL.

Retornar valor

Tipo: HRESULT

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

Comentários

Uma superfície esparsa do Microsoft DirectComposition é um objeto lógico que se comporta como uma matriz retangular de pixels que pode ser associada a um visual para composição. A superfície não é necessariamente apoiada por qualquer vídeo físico ou memória do sistema para cada um de seus pixels. O aplicativo pode perceber ou virtualizar partes da superfície lógica em momentos diferentes.

Um objeto surface recém-criado está em um estado não inicializado. Embora não seja inicializada, a superfície não tem efeito na composição da árvore visual. Ele se comporta exatamente como uma superfície inicializada com pixels 100% transparentes.

Para inicializar a superfície com dados de pixel, use o método IDCompositionSurface::BeginDraw . Esse método não só fornece pixels para a superfície, mas também aloca espaço de armazenamento real para esses pixels. A alocação de memória persiste até que o aplicativo retorne parte da memória para o sistema. O aplicativo pode liberar parte ou toda a memória alocada chamando o método IDComposition::VirtualSurfaceTrim .

As superfícies DirectComposition dão suporte aos seguintes formatos de pixel:

• DXGI_FORMAT_B8G8R8A8_UNORM
• DXGI_FORMAT_R8G8B8A8_UNORM
• DXGI_FORMAT_R16G16B16A16_FLOAT

Esse método falhará se initialWidth ou initialHeight exceder 16.777.216 pixels.

Exemplos

O exemplo a seguir mostra como criar uma superfície virtual e associá-la a um visual.

HRESULT RenderAVisual(IDCompositionDevice *pDCompDevice, HWND hwndTarget,
                         UINT surfaceWidth, UINT surfaceHeight) 
{
    // Validate the input parameters.
    if (pDCompDevice == nullptr || hwndTarget == NULL)
        return E_INVALIDARG;
    
    HRESULT hr = S_OK;
    IDCompositionTarget *pTargetWindow = nullptr;
    IDCompositionVisual *pVisual = nullptr;
    IDCompositionVirtualSurface *pVirtualSurface = nullptr;
    ID3D10Texture2D *pTex2D = nullptr;
    POINT offset = {0};

    // Create the rendering target. 
    hr = pDCompDevice->CreateTargetForHwnd(hwndTarget, TRUE, &pTargetWindow);

    if (SUCCEEDED(hr))
    {
        // Create a visual.
        hr = pDCompDevice->CreateVisual(&pVisual);
    }

    if (SUCCEEDED(hr))
    {
        // Add the visual to the root of the composition tree.
        hr = pTargetWindow->SetRoot(pVisual);
    }

    if (SUCCEEDED(hr))
    {
        // Create a virtual surface.
        hr = pDCompDevice->CreateVirtualSurface(surfaceWidth, surfaceHeight, 
            DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_ALPHA_MODE_IGNORE, 
            &pVirtualSurface);
    }

    if (SUCCEEDED(hr))
    {
        // Set the virtual surface as the content of the visual.
        hr = pVisual->SetContent(pVirtualSurface);
    }
    
    if (SUCCEEDED(hr))
    {
        // Retrieve and interface pointer for draw on the surface.
        hr = pVirtualSurface->BeginDraw(NULL, __uuidof(ID3D10Texture2D), 
            (void **) &pTex2D, &offset);
    }

    //
    // TODO: Draw on the surface.
    //
    
    if (SUCCEEDED(hr))
    {
        // Complete the updates to the surface.
        hr = pVirtualSurface->EndDraw();
    }

    // Commit the composition for rendering.
    hr = pDCompDevice->Commit();

    // Clean up.
    SafeRelease(&pTargetWindow);
    SafeRelease(&pVisual);
    SafeRelease(&pVirtualSurface);
    SafeRelease(&pTex2D);

    return hr;

}

Requisitos

Requisito	Valor
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

Confira também

IDCompositionDevice

IDCompositionDevice::CreateSurface