Метод IDCompositionDevice::CreateVirtualSurface (dcomp.h)

Статья
08/23/2023

Создает разреженную поверхность, которая может быть связана с одним или несколькими визуальными элементами для композиции.

Синтаксис

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

Параметры

[in] initialWidth

Тип: UINT

Ширина поверхности в пикселях. Максимальная ширина составляет 16 777 216 пикселей.

[in] initialHeight

Тип: UINT

Высота поверхности в пикселях. Максимальная высота составляет 16 777 216 пикселей.

[in] pixelFormat

Тип: DXGI_FORMAT

Формат пикселей поверхности.

[in] alphaMode

Тип: DXGI_ALPHA_MODE

Значение альфа-канала, если формат пикселя содержит альфа-канал. Может иметь одно из следующих значений.

Значение	Значение
DXGI_ALPHA_MODE_UNSPECIFIED	Альфа-канал не указан. Это значение имеет тот же эффект, что и DXGI_ALPHA_MODE_IGNORE.
DXGI_ALPHA_MODE_PREMULTIPLIED	Цветовые каналы содержат значения, предварительно заданные альфа-каналом.
DXGI_ALPHA_MODE_IGNORE	Альфа-канал следует игнорировать, а растровое изображение должно отображаться непрозрачно.

[out] virtualSurface

Тип: IDCompositionVirtualSurface**

Только что созданный объект surface. Этот параметр не должен иметь значение NULL.

Возвращаемое значение

Тип: HRESULT

Если функция выполняется успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT . Список кодов ошибок см. в разделе Коды ошибок DirectComposition .

Разреженная поверхность Microsoft DirectComposition — это логический объект, который ведет себя как прямоугольный массив пикселей, который может быть связан с визуальным элементом для композиции. Поверхность не обязательно поддерживается каким-либо физическим видео или системной памятью для каждого пикселя. Приложение может реализовать или виртуализировать части логической поверхности в разное время.

Созданный объект surface находится в неинициализированном состоянии. Хотя она не инициализирована, поверхность не влияет на состав визуального дерева. Он ведет себя точно так же, как поверхность, инициализированная со 100 % прозрачными пикселями.

Чтобы инициализировать поверхность с пиксельными данными, используйте метод IDCompositionSurface::BeginDraw . Этот метод не только предоставляет пиксели для поверхности, но и выделяет фактическое дисковое пространство для этих пикселей. Выделение памяти сохраняется до тех пор, пока приложение не вернет часть памяти в систему. Приложение может освободить часть или всю выделенную память, вызвав метод IDComposition::VirtualSurfaceTrim .

Поверхности DirectComposition поддерживают следующие форматы пикселей:

DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT

Этот метод завершается ошибкой, если значение initialWidth или initialHeight превышает 16 777 216 пикселей.

Примеры

В следующем примере показано, как создать виртуальную поверхность и связать ее с визуальным элементом.

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;

}

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 [только классические приложения]
Целевая платформа	Windows
Header	dcomp.h
Библиотека	Dcomp.lib
DLL	Dcomp.dll

См. также раздел

IDCompositionDevice

IDCompositionDevice::CreateSurface

Поделиться через