IDirect3DDevice9Ex::ComposeRect 

  • Article

IDirect3DDevice9Ex::ComposeRect

Compose a set of glyphs for blitting a text string.

  HRESULT 
  ComposeRect(
  IDirect3DSurface9* pSource,
  IDirect3DSurface9* pDestination,
  IDirect3DVertexBuffer9* pSrcRectDescriptors,
  UINT NumRects,
  IDirect3DVertexBuffer9* pDstRectDescriptors,
  D3DCOMPOSEOP Operation,
  INT XOffset,
  INT YOffset
);

Parameters

  • pSource
    [in] A pointer to a source surface (for a description of IDirect3DSurface9, see the DirectX SDK documentation).

  • pDestination
    [in] A pointer to the destination surface (for a description of IDirect3DSurface9, see the DirectX SDK documentation).

  • pSrcRectDescriptors
    [in] A vertex buffer containing an array of rectangles that describe the glyphs in the source surface (for a description of IDirect3DVertexBuffer9, see the DirectX SDK documentation). The array of rectangles is stored in a vertex buffer. Each glyph is described by a D3DCOMPOSERECTSRCDESC structure; which contains four members:

    Type Name Description
    USHORT X The top left corner (x value)
    USHORT Y The top left corner (y value)
    USHORT Width Rectangle width
    USHORT Height Rectangle height

  • NumRects
    [in] The number of rectangles that describes the source surface. The range is 0 to 0xFFFF.

  • pDstRectDescriptors
    [in] A vertex buffer containing an array of rectangles that describes the glyphs to be stored on the destination surface (for a description of IDirect3DVertexBuffer9, see the DirectX SDK documentation). Each glyph is described by a D3DCOMPOSERECTSRCDESC structure; which contains four members:

    Type Name Description
    USHORT RectDescIndex The zero-based source-rectangle index
    USHORT Reserved Reserved
    SHORT X The top left corner (x value)
    SHORT Y The top left corner (y value)

  • Operation
    [in] Describes how to write the source data to the destination. Choose one of these four mutually exclusive choices:

    • D3DCOMPOSE_COPY - Copy the source to the dest
    • D3DCOMPOSE_OR - bitwise OR the source and the dest
    • D3DCOMPOSE_AND - bitwise AND the source and the dest
    • D3DCOMPOSE_NEG - Copy the negated source to the dest

  • XOffset
    [in] The XOffset value which is added to the X value of all destination rectangles. This value can be negative which may cause the glyph to be rejected or clipped. See the section on constraints below.

  • YOffset
    [in] The YOffset value which is added to the Y value of all destination rectangles. This value can be negative which may cause the glyph to be rejected or clipped. See the section on constraints below.

Return Values

If the method succeeds, the return value is D3D_OK.

Remarks

This method has several constraints:

  • All resources (source surface, destination surface, and vertex buffer) must be created with the same device. None of the resources can be locked.
  • The source and destination surfaces must both have the same format (D3DFMT_A1), and they must be different surfaces.
  • In the debug build, Direct3D validates that a source rect description exists for each index in the destination rect description. In the retail build the call returns an error if an invalid index exists.

In addition, the source rectangles must be completely within the source surface. It is possible that the destination rectangles will not lie completely inside the destination surface after applying the offsets. If this happens, the destination rectangles will be clipped to the destination surface.

The ComposeRects call is not recorded in a state block.

See Also

IDirect3DDevice9Ex Interface