D3DXDrawSpriteSimple

The D3DXDrawSpriteSimple function renders a sprite onto a Direct3D device. This function must be called in between calls to IDirect3DDevice7::BeginScene and IDirect3DDevice7::EndScene.

HRESULT D3DXDrawSpriteSimple(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXVECTOR3* ppointDest,
  float alpha = 1.0f,
  float scale = 1.0f,
  float angleRad = 0.0f,
  const D3DXVECTOR2* pOffset = NULL,
  const RECT *pSourceRect = NULL
);

Parameters

pd3dTexture

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

pd3dDevice

A pointer to an IDirect3DDevice7 interface. The sprite will be rendered to this device. It is assumed that render states are set up for this device (see D3DXPrepareDeviceForSprite).

ppointDest

A pointer to a D3DXVECTOR3 structure. The target point for the sprite. The vector indicates in screen coordinates where the center of the sprite should be rendered. The components of the vector must be in screen space. Typically, the z-component of the vector will be set to zero; but can be set to any value for applications that are using a z-buffer instead of rendering back-to-front.

alpha

The alpha value to apply to sprite, indicating the opacity of 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. This alpha value is combined with the alpha (if any) present in texture image.

scale

A uniform scale that is applied to the source RECT to specify the size of the image rendered. By default, the value is 1.0, which means that the sprite will be rendered at the same width and height as the source.

angleRad

Angle of rotation around the center of the RECT, indicating what angle to rotate the sprite. The rotation is applied around the center of the sprite. It is counter-clockwise and must be specified in radians. See D3DXToRadian to convert degrees to radians.

pOffset

A pointer to a D3DXVECTOR2 structure, defining the offset from the center of the source RECT to use as the center of rotation. This parameter indicates the offset from the center-point of the sprite that should be treated as the sprite center for the purposes of the ppointDest and angleRad parameters.

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, 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, scale, angleRad, pOffset, and pSourceRect parameters.

The D3DXDrawSpriteSimple function performs blitting of source images onto a 3-D rendering device. This function only calls IDirect3DDevice7::SetTexture on the first render stage with the parameter pd3dTexture, if that parameter is non-NULL.

This function supports scaling, rotation, alpha blending, mirroring, and placement. For a broader range of effects such as shearing and perspective, use the D3DXDrawSpriteTransform function.

This function assumes that D3DXPrepareDeviceForSprite has been called on the device or that caller has in some other way correctly prepared the render states.

The rotation angle is specified in radians. Both rotations and scales are applied around the center of the sprite; where the center of the sprite is half the width and height of the sprite, plus the offset parameter. Use the offset parameter if you want the sprite's center to be something other than the image center.

The destination point indicates where you would like to place the center of the sprite. Advanced users who are mixing 2-D and 3-D rendering should remember that these coordinates are assumed to be fully transformed (i.e. in screen space and should set the z-component of the ppointDest parameter accordingly). In general, advanced users may want to use the D3DXDrawSprite3D function instead for greater control.

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

D3DXDrawSpriteTransform, D3DXDrawSprite3D, D3DXPrepareDeviceForSprite