IDirect3DDevice9Ex::ComposeRects method (d3d9.h)

Copy a text string to one surface using an alphabet of glyphs on another surface. Composition is done by the GPU using bitwise operations.

Syntax

HRESULT ComposeRects(
  [in] IDirect3DSurface9      *pSrc,
  [in] IDirect3DSurface9      *pDst,
  [in] IDirect3DVertexBuffer9 *pSrcRectDescs,
  [in] UINT                   NumRects,
  [in] IDirect3DVertexBuffer9 *pDstRectDescs,
  [in] D3DCOMPOSERECTSOP      Operation,
  [in] int                    Xoffset,
  [in] int                    Yoffset
);

Parameters

[in] pSrc

Type: IDirect3DSurface9*

A pointer to a source surface (prepared by IDirect3DSurface9) that supplies the alphabet glyphs. This surface must be created with the D3DUSAGE_TEXTAPI flag.

[in] pDst

Type: IDirect3DSurface9*

A pointer to the destination surface (prepared by IDirect3DSurface9) that receives the glyph data. The surface must be part of a texture.

[in] pSrcRectDescs

Type: IDirect3DVertexBuffer9*

A pointer to a vertex buffer (see IDirect3DVertexBuffer9) containing rectangles (see D3DCOMPOSERECTDESC) that enclose the desired glyphs in the source surface.

[in] NumRects

Type: UINT

The number of rectangles or glyphs that are used in the operation. The number applies to both the source and destination surfaces. The range is 0 to D3DCOMPOSERECTS_MAXNUMRECTS.

[in] pDstRectDescs

Type: IDirect3DVertexBuffer9*

A pointer to a vertex buffer (see IDirect3DVertexBuffer9) containing rectangles (see D3DCOMPOSERECTDESTINATION) that describe the destination to which the indicated glyph from the source surface will be copied.

[in] Operation

Type: D3DCOMPOSERECTSOP

Specifies how to combine the source and destination surfaces. See D3DCOMPOSERECTSOP.

[in] Xoffset

Type: INT

A value added to the x coordinates of all destination rectangles. This value can be negative, which may cause the glyph to be rejected or clipped if the result is beyond the bounds of the surface.

[in] Yoffset

Type: INT

A value added to the y coordinates of all destination rectangles. This value can be negative, which may cause the glyph to be rejected or clipped if the result is beyond the bounds of the surface.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK.

Remarks

Glyphs from a one-bit source surface are put together into another one-bit texture surface with this method. The destination surface can then be used as the source for a normal texturing operation that will filter and scale the strings of text onto some other non-monochrome surface.

This method has several constraints (which are similar to StretchRect):

• Surfaces cannot be locked.
• The source and destination surfaces cannot be the same surface.
• The source and destination surfaces must be created with the D3DFMT_A1 format.
• The source surface and both vertex buffers must be created with the D3DPOOL_DEFAULT flag.
• The destination surface must be created with either the D3DPOOL_DEFAULT or D3DPOOL_SYSTEMMEM flags.
• The source rectangles must be within the source surface.

Requirements

See also

IDirect3DDevice9Ex