Metodo IDCompositionDevice::CreateVirtualSurface (dcomp.h)

Articolo
08/23/2023

Crea una superficie popolata sparse che può essere associata a uno o più oggetti visivi per la composizione.

Sintassi

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

Parametri

[in] initialWidth

Tipo: UINT

Larghezza della superficie, in pixel. La larghezza massima è 16,777,216 pixel.

[in] initialHeight

Tipo: UINT

Altezza della superficie, in pixel. L'altezza massima è 16,777,216 pixel.

[in] pixelFormat

Tipo: DXGI_FORMAT

Formato pixel della superficie.

[in] alphaMode

Tipo: DXGI_ALPHA_MODE

Il significato del canale alfa, se il formato pixel contiene un canale alfa. Può essere uno dei valori seguenti:

Valore	Significato
DXGI_ALPHA_MODE_UNSPECIFIED	Il canale alfa non è specificato. Questo valore ha lo stesso effetto dell'DXGI_ALPHA_MODE_IGNORE.
DXGI_ALPHA_MODE_PREMULTIPLIED	I canali di colore contengono valori premultiplied con il canale alfa.
DXGI_ALPHA_MODE_IGNORE	Il canale alfa deve essere ignorato e la bitmap deve essere eseguito il rendering opaco.

[out] virtualSurface

Tipo: IDCompositionVirtualSurface**

Oggetto surface appena creato. Questo parametro non deve essere NULL.

Valore restituito

Tipo: HRESULT

Se la funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT . Per un elenco di codici di errore, vedere Codici di errore DirectComposition .

Commenti

Una superficie sparse Di Microsoft DirectComposition è un oggetto logico che si comporta come una matrice rettangolare di pixel che può essere associata a un oggetto visivo per la composizione. La superficie non è necessariamente supportata da qualsiasi video fisico o memoria di sistema per ognuno dei suoi pixel. L'applicazione può realizzare o virtualizzare parti della superficie logica in momenti diversi.

Un oggetto surface appena creato è in uno stato non inizializzato. Sebbene non sia inizializzato, la superficie non ha alcun effetto sulla composizione dell'albero visivo. Si comporta esattamente come una superficie inizializzata con pixel trasparenti al 100%.

Per inizializzare la superficie con i dati pixel, usare il metodo IDCompositionSurface::BeginDraw . Questo metodo non solo fornisce pixel per la superficie, ma alloca anche lo spazio di archiviazione effettivo per tali pixel. L'allocazione di memoria persiste fino a quando l'applicazione restituisce una parte della memoria al sistema. L'applicazione può liberare parte o tutta la memoria allocata chiamando il metodo IDComposition::VirtualSurfaceTrim .

Le superfici DirectComposition supportano i formati pixel seguenti:

DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT

Questo metodo ha esito negativo se initialWidth o initialHeight supera 16,777,216 pixel.

Esempio

Nell'esempio seguente viene illustrato come creare una superficie virtuale e associarla a un oggetto visivo.

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;

}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	dcomp.h
Libreria	Dcomp.lib
DLL	Dcomp.dll

Vedi anche

IDCompositionDevice

IDCompositionDevice::CreateSurface

Condividi tramite