IDCompositionSurfaceFactory::CreateVirtualSurface method (dcomp.h)

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

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

[in] initialHeight

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

[in] pixelFormat

The pixel format of the surface.

[in] alphaMode

The format of the alpha channel, if an alpha channel is included in the pixel format. This can be one of DXGI_ALPHA_MODE_PREMULTIPLIED or DXGI_ALPHA_MODE_IGNORE. It can also be DXGI_ALPHA_MODE_UNSPECIFIED, which is interpreted as DXGI_ALPHA_MODE_IGNORE.

[out] virtualSurface

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

Return value

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 newly created virtual 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 method. 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 or IDCompositionVirtualSurface::Resize method.

Microsoft DirectComposition surfaces support the following pixel formats:

  • DXGI_FORMAT_B8G8R8A8_UNORM
  • DXGI_FORMAT_R8G8B8A8_UNORM
  • DXGI_FORMAT_R16G16B16A16_FLOAT

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

See also

IDCompositionDevice2::CreateSurface

IDCompositionDevice2::CreateVirtualSurface

IDCompositionSurfaceFactory

IDCompositionSurfaceFactory::CreateVirtualSurface