PFND3DDDI_COMPOSERECTS callback function (d3dumddi.h)

The ComposeRects function composes two-dimensional areas from a source surface to a destination surface.

Syntax

PFND3DDDI_COMPOSERECTS Pfnd3dddiComposerects;

HRESULT Pfnd3dddiComposerects(
  HANDLE hDevice,
  const D3DDDIARG_COMPOSERECTS *unnamedParam2
)
{...}

Parameters

hDevice

A handle to the display device (graphics context).

unnamedParam2

pData [in]

A pointer to a D3DDDIARG_COMPOSERECTS structure that specifies the parameters that are used to compose rectangular areas.

Return value

ComposeRects returns one of the following values:

Return code	Description
S_OK	The rectangular areas were successfully composed.
E_OUTOFMEMORY	ComposeRects could not allocate the required memory for it to complete.

Remarks

The following constraints and validations apply to the ComposeRects function:

• The driver should ignore the source rectangular areas that are not completely inside the source surface.
• The destination rectangular areas--after applying offsets--can be partially or completely outside the destination surface. The destination rectangular areas are clipped if partially outside and rejected or completely clipped if completely outside.
• The same surface cannot be specified for the source and the destination.
• Surfaces and vertex buffers that are used with ComposeRects should not be locked.
• The source and destination surfaces are formatted as one bit per pixel (D3DDDIFMT_A1) when they are created.
• In the debug build, the Microsoft Direct3D runtime validates that a source rectangular area description exists for each index in the destination rectangular area description. In the retail build, ComposeRects returns an error if an invalid index exists.
• The number of rectangular areas should be less than 0xFFFF to prevent internal overflow during math operations.
• Surfaces and vertex buffers should be created by using the same display device (graphics context).
• Local display memory should be specified for the destination surface.

The following example code shows an operation that ComposeRects performs:

for (UINT i=0; i < COMPOSERECTS.NumDstRects; i++) {
   if (i >= Size(VertexBuffer(hDstRectDescsVB)) / sizeof(D3DCOMPOSERECTDSTDESC))
      Ignore the rectangle;
   if (VertexBuffer(hDstRectDescsVB)[i].RectDescIndex >= Size(VertexBuffer(hSrcRectDescsVB)) / sizeof(D3DCOMPOSERECTSRCDESC))
      Ignore the rectangle;
   SourceRectangle = VertexBuffer(hSrcResource)[VertexBuffer(hDstRectDescsVB)[i].RectDescIndex];
   DestinationRectangle.X = {VertexBuffer(hDstRectDescsVB)[i].X + COMPOSERECTS.Xoffset;
   DestinationRectangle.Y = {VertexBuffer(hDstRectDescsVB)[i].Y + COMPOSERECTS.Yoffset;
   DestinationRectangle.Width = SourceRectangle.Width;
   DestinationRectangle.Height = SourceRectangle.Height;
   Perform COMPOSERECTS.Operation for each pixel;
}

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of the Windows operating systems.
Target Platform	Desktop
Header	d3dumddi.h (include D3dumddi.h)

See also

D3DDDIARG_COMPOSERECTS

D3DDDI_DEVICEFUNCS