IDCompositionDevice ::CreateVirtualSurface, méthode (dcomp.h)

Crée une surface partiellement remplie qui peut être associée à un ou plusieurs visuels pour la composition.

Syntaxe

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

Paramètres

[in] initialWidth

Type : UINT

Largeur de la surface, en pixels. La largeur maximale est de 16 777 216 pixels.

[in] initialHeight

Type : UINT

Hauteur de la surface, en pixels. La hauteur maximale est de 16 777 216 pixels.

[in] pixelFormat

Type : DXGI_FORMAT

Format de pixels de la surface.

[in] alphaMode

Type : DXGI_ALPHA_MODE

Signification du canal alpha, si le format de pixels contient un canal alpha. Ce peut être l’une des valeurs suivantes :

Valeur	Signification
DXGI_ALPHA_MODE_UNSPECIFIED	Le canal alpha n’est pas spécifié. Cette valeur a le même effet que DXGI_ALPHA_MODE_IGNORE.
DXGI_ALPHA_MODE_PREMULTIPLIED	Les canaux de couleurs contiennent des valeurs qui sont prémultipliées avec le canal alpha.
DXGI_ALPHA_MODE_IGNORE	Le canal alpha doit être ignoré et l’image bitmap doit être rendue de manière opaque.

[out] virtualSurface

Type : IDCompositionVirtualSurface**

Objet surface nouvellement créé. Ce paramètre ne doit pas avoir la valeur NULL.

Valeur retournée

Type : HRESULT

Si la fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT. Pour obtenir la liste des codes d’erreur, consultez Codes d’erreur DirectComposition .

Remarques

Une surface éparse Microsoft DirectComposition est un objet logique qui se comporte comme un tableau rectangulaire de pixels qui peut être associé à un visuel pour la composition. La surface n’est pas nécessairement soutenue par une vidéo physique ou une mémoire système pour chacun de ses pixels. L’application peut réaliser ou virtualiser des parties de la surface logique à différents moments.

Un objet surface nouvellement créé est dans un état non initialisé. Bien qu’elle soit non initialisée, la surface n’a aucun effet sur la composition de l’arborescence visuelle. Il se comporte exactement comme une surface initialisée avec des pixels 100 % transparents.

Pour initialiser la surface avec des données de pixels, utilisez la méthode IDCompositionSurface ::BeginDraw . Cette méthode fournit non seulement des pixels pour la surface, mais elle alloue également de l’espace de stockage réel pour ces pixels. L’allocation de mémoire persiste jusqu’à ce que l’application retourne une partie de la mémoire au système. L’application peut libérer une partie ou la totalité de la mémoire allouée en appelant la méthode IDComposition ::VirtualSurfaceTrim .

Les surfaces DirectComposition prennent en charge les formats de pixels suivants :

• DXGI_FORMAT_B8G8R8A8_UNORM
• DXGI_FORMAT_R8G8B8A8_UNORM
• DXGI_FORMAT_R16G16B16A16_FLOAT

Cette méthode échoue si initialWidth ou initialHeight dépasse 16 777 216 pixels.

Exemples

L’exemple suivant montre comment créer une surface virtuelle et l’associer à un visuel.

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;

}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	dcomp.h
Bibliothèque	Dcomp.lib
DLL	Dcomp.dll

Voir aussi

IDCompositionDevice

IDCompositionDevice ::CreateSurface