ID3DXSprite::Draw Method

Draws a simple sprite in screen space.

Syntax

HRESULT Draw(      

    LPDIRECT3DTEXTURE9 pSrcTexture,
    CONST RECT *pSrcRect,
    CONST D3DXVECTOR2 *pScaling,
    CONST D3DXVECTOR2 *pRotationCenter,
    FLOAT Rotation,
    CONST D3DVECTOR2 *pTranslation,
    D3DCOLOR Color
);

Parameters

pSrcTexture

[in] Pointer to an IDirect3DTexture9 interface, representing the source image used for the sprite.

pSrcRect

[in] 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 subrectangle of the source image instead. Before transformation, the size of the sprite is defined by pSrcRect with the upper left corner at the origin (0,0).

pScaling

[in] Pointer to a D3DXVECTOR2 structure, containing the scaling vector. If this parameter is NULL, the value (1.0, 1.0) is used. Since pScaling is vector, a multiplier of 1.0 would preserve the source image size.

pRotationCenter

[in] Pointer to a D3DXVECTOR2 structure, containing the point in screen pixels that identifies the center of rotation. If this argument is NULL, the point (0,0) is used, which is the upper-left corner of the texture.

Rotation

[in] Value that specifies the rotation in radians, counterclockwise.

pTranslation

[in] Pointer to a D3DXVECTOR2 structure, containing the translation in screen pixels. If this argument is NULL, the point (0,0) is used.

Color

[in] D3DCOLOR type. The color and alpha channels are modulated by this value. A value of 0xFFFFFFFF maintains the original source color and alpha data.

Return Value

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be D3DERR_INVALIDCALL.

Remarks

The transformation order is specified by:

(Msc)^-1 * (Msr)^-1 * Ms * Msr * Msc * (Mrc)^-1 * Mr * Mrc * Mt

Where:

• Msc is the center scaling matrix.
• Msr is the scaling rotation matrix.
• Ms is the scaling matrix.
• Mrc is the center of rotation matrix.
• Mr is the rotation matrix.
• Mt is the translation matrix.

This method must be called between an IDirect3DDevice9::BeginScene and IDirect3DDevice9::EndScene pair.

If ID3DXSprite::Begin has not been called, this method will internally call ID3DXSprite::Begin and ID3DXSprite::End. When making successive calls to this method and/or ID3DXSprite::DrawTransform, be sure to call ID3DXSprite::Begin to avoid the extra overhead of ID3DXSprite::DrawTransform and this method internally calling ID3DXSprite::Begin and ID3DXSprite::End each time.

The image can be mirrored by specifying a negative vector in the appropriate direction (x, y, or both) for the pScaling parameter and adding the width and/or height of the source rectangle, specified in the pSrcRect parameter, to the values specified in the pTranslation parameter. Note that this will change the point of origin for rotations.