IDCompositionDevice2::CreateVirtualSurface method (dcomp.h)

Article
07/27/2022

Creates a sparsely populated surface that can be associated with one or more visuals for composition.

Syntax

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

Parameters

[in] initialWidth

Type: UINT

The width of the surface, in pixels. The maximum width is 16,777,216 pixels.

[in] initialHeight

Type: UINT

The height of the surface, in pixels. The maximum height is 16,777,216 pixels.

[in] pixelFormat

Type: DXGI_FORMAT

The pixel format of the surface.

[in] alphaMode

Type: DXGI_ALPHA_MODE

The meaning of the alpha channel, if the pixel format contains an alpha channel. It can be one of the following values:

Value	Meaning
DXGI_ALPHA_MODE_UNSPECIFIED	The alpha channel is not specified. This value has the same effect as DXGI_ALPHA_MODE_IGNORE.
DXGI_ALPHA_MODE_PREMULTIPLIED	The color channels contain values that are premultiplied with the alpha channel.
DXGI_ALPHA_MODE_IGNORE	The alpha channel should be ignored and the bitmap should be rendered opaquely.

[out] virtualSurface

Type: IDCompositionVirtualSurface**

The newly created surface object. This parameter must not be NULL.

Return value

Type: HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. See DirectComposition Error Codes for a list of error codes.

Remarks

A Microsoft DirectComposition sparse surface is a logical object that behaves like a rectangular array of pixels that can be associated with a visual for composition. The surface is not necessarily backed by any physical video or system memory for every one of its pixels. The application can realize or virtualize parts of the logical surface at different times.

A newly created surface object is in an uninitialized state. While it is uninitialized, the surface has no effect on the composition of the visual tree. It behaves exactly like a surface that is initialized with 100% transparent pixels.

To initialize the surface with pixel data, use the IDCompositionSurface::BeginDraw and IDCompositionSurface::EndDraw methods. This method not only provides pixels for the surface, but it also allocates actual storage space for those pixels. The memory allocation persists until the application returns some of the memory to the system. The application can free part or all of the allocated memory by calling the IDCompositionVirtualSurface::Trim method.

DirectComposition surfaces support the following pixel formats:

DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT

This method fails if initialWidth or initialHeight exceeds 16,777,216 pixels.

Requirements

Requirement	Value
Minimum supported client	Windows 8.1 [desktop apps only]
Minimum supported server	Windows Server 2012 R2 [desktop apps only]
Target Platform	Windows
Header	dcomp.h
Library	Dcomp.lib
DLL	Dcomp.dll