IDCompositionDevice::CreateVirtualSurface-Methode (dcomp.h)

Artikel
03/01/2024

Erstellt eine dünn aufgefüllte Oberfläche, die einem oder mehreren Visuals für die Komposition zugeordnet werden kann.

Syntax

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

Parameter

[in] initialWidth

Typ: UINT

Die Breite der Oberfläche in Pixel. Die maximale Breite beträgt 16.777.216 Pixel.

[in] initialHeight

Typ: UINT

Die Höhe der Oberfläche in Pixel. Die maximale Höhe beträgt 16.777.216 Pixel.

[in] pixelFormat

Typ: DXGI_FORMAT

Das Pixelformat der Oberfläche.

[in] alphaMode

Typ: DXGI_ALPHA_MODE

Die Bedeutung des Alphakanals, wenn das Pixelformat einen Alphakanal enthält. Es kann sich um einen der folgenden Werte handeln:

Wert	Bedeutung
DXGI_ALPHA_MODE_UNSPECIFIED	Der Alphakanal ist nicht angegeben. Dieser Wert hat die gleiche Auswirkung wie DXGI_ALPHA_MODE_IGNORE.
DXGI_ALPHA_MODE_PREMULTIPLIED	Die Farbkanäle enthalten Werte, die mit dem Alphakanal vormultipliziert sind.
DXGI_ALPHA_MODE_IGNORE	Der Alphakanal sollte ignoriert werden, und die Bitmap sollte undurchsichtig gerendert werden.

[out] virtualSurface

Typ: IDCompositionVirtualSurface**

Das neu erstellte Surface-Objekt. Dieser Parameter darf nicht NULL sein.

Rückgabewert

Typ: HRESULT

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben. Eine Liste der Fehlercodes finden Sie unter DirectComposition-Fehlercodes .

Hinweise

Eine Microsoft DirectComposition-Sparseoberfläche ist ein logisches Objekt, das sich wie ein rechteckiges Array von Pixeln verhält, das einem Visual für die Komposition zugeordnet werden kann. Die Oberfläche wird nicht notwendigerweise durch physische Video- oder Systemspeicher für jeden ihrer Pixel unterstützt. Die Anwendung kann Teile der logischen Oberfläche zu unterschiedlichen Zeiten realisieren oder virtualisieren.

Ein neu erstelltes Oberflächenobjekt befindet sich in einem nicht initialisierten Zustand. Obwohl sie nicht initialisiert ist, hat die Oberfläche keine Auswirkungen auf die Zusammensetzung der visuellen Struktur. Es verhält sich genau wie eine Oberfläche, die mit 100 % transparenten Pixeln initialisiert wird.

Um die Oberfläche mit Pixeldaten zu initialisieren, verwenden Sie die IDCompositionSurface::BeginDraw-Methode . Diese Methode stellt nicht nur Pixel für die Oberfläche bereit, sondern belegt auch den tatsächlichen Speicherplatz für diese Pixel. Die Speicherbelegung wird beibehalten, bis die Anwendung einen Teil des Arbeitsspeichers an das System zurückgibt. Die Anwendung kann einen Teil oder den gesamten zugeordneten Arbeitsspeicher freigeben, indem sie die IDComposition::VirtualSurfaceTrim-Methode aufruft .

DirectComposition-Oberflächen unterstützen die folgenden Pixelformate:

DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT

Diese Methode schlägt fehl, wenn initialWidth oder initialHeight 16.777.216 Pixel überschreitet.

Beispiele

Das folgende Beispiel zeigt, wie Sie eine virtuelle Oberfläche erstellen und sie einem Visual zuordnen.

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;

}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	dcomp.h
Bibliothek	Dcomp.lib
DLL	Dcomp.dll

Weitere Informationen

IDCompositionDevice

IDCompositionDevice::CreateSurface

Freigeben über