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

Crea una superficie rellenada dispersamente que se puede asociar a uno o varios objetos visuales para la composición.

Sintaxis

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

Ancho de la superficie, en píxeles. El ancho máximo es de 16 777 216 píxeles.

[in] initialHeight

Tipo: UINT

Alto de la superficie, en píxeles. El alto máximo es de 16 777 216 píxeles.

[in] pixelFormat

Tipo: DXGI_FORMAT

Formato de píxel de la superficie.

[in] alphaMode

Tipo: DXGI_ALPHA_MODE

Significado del canal alfa, si el formato de píxel contiene un canal alfa. Puede ser uno de los siguientes valores:

Valor	Significado
DXGI_ALPHA_MODE_UNSPECIFIED	No se especifica el canal alfa. Este valor tiene el mismo efecto que DXGI_ALPHA_MODE_IGNORE.
DXGI_ALPHA_MODE_PREMULTIPLIED	Los canales de color contienen valores que se premultiplican con el canal alfa.
DXGI_ALPHA_MODE_IGNORE	El canal alfa debe omitirse y el mapa de bits debe representarse opacamente.

[out] virtualSurface

Tipo: IDCompositionVirtualSurface**

Objeto de superficie recién creado. 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

Una superficie dispersa de Microsoft DirectComposition es un objeto lógico que se comporta como una matriz rectangular de píxeles que se puede asociar a un objeto visual para la composición. La superficie no está necesariamente respaldada por ningún vídeo físico o memoria del sistema para cada uno de sus píxeles. La aplicación puede realizar o virtualizar partes de la superficie lógica en momentos diferentes.

Un objeto de superficie recién creado está en un estado no inicializado. Aunque no se inicializa, la superficie no tiene ningún efecto en la composición del árbol visual. Se comporta exactamente como una superficie que se inicializa con píxeles transparentes del 100 %.

Para inicializar la superficie con datos de píxeles, use el método IDCompositionSurface::BeginDraw . Este método no solo proporciona píxeles para la superficie, sino que también asigna espacio de almacenamiento real para esos píxeles. La asignación de memoria persiste hasta que la aplicación devuelve parte de la memoria al sistema. La aplicación puede liberar parte o toda la memoria asignada llamando al método IDComposition::VirtualSurfaceTrim .

Las superficies directComposition admiten los siguientes formatos de píxel:

• DXGI_FORMAT_B8G8R8A8_UNORM
• DXGI_FORMAT_R8G8B8A8_UNORM
• DXGI_FORMAT_R16G16B16A16_FLOAT

Este método produce un error si initialWidth o initialHeight supera los 16 777 216 píxeles.

Ejemplos

En el ejemplo siguiente se muestra cómo crear una superficie virtual y asociarla a un objeto 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	Value
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

Consulte también

IDCompositionDevice

IDCompositionDevice::CreateSurface