Edit

Share via

IDCompositionDevice2::CreateSurface method (dcomp.h)

  • Article

Creates an updateable surface object that can be associated with one or more visuals for composition.

Syntax

HRESULT CreateSurface(
  [in]  UINT                 width,
  [in]  UINT                 height,
  [in]  DXGI_FORMAT          pixelFormat,
  [in]  DXGI_ALPHA_MODE      alphaMode,
  [out] IDCompositionSurface **surface
);

Parameters

[in] width

Type: UINT

The width of the surface, in pixels. Constrained by the feature level of the rendering device that was passed in at the time the DirectComposition device was created.

[in] height

Type: UINT

The height of the surface, in pixels. Constrained by the feature level of the rendering device that was passed in at the time the DirectComposition device was created.

[in] pixelFormat

Type: DXGI_FORMAT

The pixel format of the surface.

[in] alphaMode

Type: DXGI_ALPHA_MODE

The format of the alpha channel, if an alpha channel is included in the pixel format. 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] surface

Type: IDCompositionSurface**

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 surface is a rectangular array of pixels that can be associated with a visual for composition.

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 has 100% transparent pixels.

To initialize the surface with pixel data, use the IDCompositionSurface::BeginDraw and IDCompositionSurface::EndDraw methods. The first call to this method must cover the entire surface area to provide an initial value for every pixel. Subsequent calls may specify smaller sub-rectangles of the surface to update.

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

IDCompositionDevice2::CreateVirtualSurface