D3DXDrawSprite3D

Given four points, the D3DXDrawSprite3D function will draw the sprite filling those points. The points are expected to be in screen coordinates. This function must be called in between calls to IDirect3DDevice7::BeginScene and IDirect3DDevice7::EndScene.

HRESULT D3DXDrawSprite3D(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXVECTOR4 quad[4],
  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.

quad

An array of D3DXVECTOR4 structures representing an array of 4 points in screen coordinates in the following order: upper-left, upper-right, lower-right, lower-left. If these vectors contain a w value, then this function will take the reciprocal of that value to pass as the rhw value (reciprocal homogenous). The z- and w-coordinates are used to fill in the z and rhw coordinates in a D3DTLVERTEX that is passed to the IDirect3DDevice7::DrawPrimitive method.

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.

The D3DXDrawSprite3D function is not recommended for non-convex triangles.

This function renders a texture onto a 3-D quadrilateral. The quadrilateral ABCD is broken into two triangles ABC and ACD which are rendered through a call to the IDirect3DDevice7::DrawPrimitive method.

For sophisticated applications that seek greater control, look at the IDirect3DDevice7::DrawPrimitive method.

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.