D3DXDrawSpriteTransform

The D3DXDrawSpriteTransform function provides a mechanism for rendering a sprite that is transformed by a specified matrix. This function must be called in between calls to IDirect3DDevice7::BeginScene and IDirect3DDevice7::EndScene.

HRESULT D3DXDrawSpriteTransform(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXMATRIX* pMatrixTransform,
  float alpha = 1.0f,
  const RECT* pSourceRect = NULL
);

Parameters

pd3dTexture

A pointer to the surface containing the texture, an IDirectDrawSurface7 interface, indicating which surface should be used as the source image for the sprite. If this parameter is NULL, it is assumed that the application has already called IDirect3DDevice7::SetTexture for texture stage zero.

pd3dDevice

A pointer to the Direct3D rendering device, an IDirect3DDevice7 interface. It is assumed that render states are set up, for more information, see D3DXPrepareDeviceForSprite.

pMatrixTransform

A pointer to a 4x4 matrix, a D3DXMATRIX structure, that specifies the transformation that will be applied to the default -.5 to +.5 rectangle. This nmatrix will transform the sprite to screen space. By default, the sprite is located at (-0.5, -0.5) to (+0.5, +0.5). It is centered around the origin to ease rotations, and it has a width and height of one, to ease scaling.

alpha

The alpha value to apply to the sprite: 1.0 means totally opaque; and 0.0 means totally transparent. Note that if you are using alpha, then you should render from back to front in order to avoid rendering artifacts. Furthermore, you should avoid scenarios where semi-transparent objects intersect. This alpha is combined with the alpha (if any) present in texture image.

pSourceRect

A pointer to a RECT structure that indicates what portion of the source texture to use for the sprite. If this parameter is NULL, then the entire source image is used for the sprite; however, you can specify a sub-rectangle of the source image instead. If the source texture was created by using Direct3DX, then the RECT structure should be specified in the coordinates of the original image. So, you do not have to be concerned with any stretching or scaling that Direct3DX may have done to make the image work with your current Direct3D device. Additionally, X and Y mirroring can be specified easily by swapping the left and top and the right and bottom parameters of this RECT structure.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value may be one of the following values:

Remarks

C programmers will not be able to take advantage of the default values for the alpha and pSourceRect parameters.

This D3DXDrawSpriteTransform function supports effects that can be specified with a matrix, alpha blending, and choosing a sub-rectangle (a value of NULL for the source sub-rectangle means that the entire texture is used). For total control of the sprite, you should use the D3DXDrawSprite3D function.

This function takes a general 4x4 matrix, which is used to transform the points of a default RECT structure (left=-.5, top=-.5, right=+.5, bottom=+.5), and transforms source images onto a Direct3D rendering device. This default RECT structure was chosen so that it was centered around the origin to ease setting up rotations. In addition, these dimensions were chosen to produce a width and height of one to ease setting up scales.

This function only calls IDirect3DDevice7::SetTexture on the first render stage with the parameter pd3dTexture if that parameter is non-null. This function assumes that D3DXPrepareDeviceForSprite has been called on the device or that caller has in some other way correctly prepared the render states.

Note that if the transformed points have a value for w (the homogenous coordinate) that is not one, then this function will invert it and pass that value to Direct3D as the rhw field of a D3DTLVERTEX structure. If the value for w is zero, then it will use one as the rhw.

Once the matrix is applied to the unit square centered at the (0, 0, 0, 1) origin, these coordinates are assumed to be fully transformed to screen space. Advanced users are advised that the z and w elements will be passed to Direct3D Immediate Mode in a D3DTLVERTEX structure. The w element will be converted into an rhw element. A value for zero for w will result in an rhw value of one.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Version: Requires DirectX 7.0.
  Header: Declared in d3dxsprite.h.
  Library: Use d3dx.lib.

See Also

D3DXBuildSpriteTransform