Blt
Expand Minimize

ComposeRects routine

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

Syntax


PFND3DDDI_COMPOSERECTS ComposeRects;

__checkReturn HRESULT APIENTRY ComposeRects(
  _In_  HANDLE hDevice,
  _In_  const D3DDDIARG_COMPOSERECTS *pData
)
{ ... }

Parameters

hDevice [in]

A handle to the display device (graphics context).

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 codeDescription
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

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

D3dumddi.h (include D3dumddi.h)

See also

D3DDDIARG_COMPOSERECTS
D3DDDI_DEVICEFUNCS

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft