D3DXPrepareDeviceForSprite

The D3DXPrepareDeviceForSprite function sets a number of render-states to prepare the device for use by the other sprite helper functions. In particular, it sets up alpha-blending and bilinear filtering. A parameter controls whether the z buffer is enabled.

HRESULT D3DXPrepareDeviceForSprite(
  LPDIRECT3DDEVICE7 pd3dDevice,
  BOOL ZEnable = FALSE
);

Parameters

pd3dDevice

A pointer to the Direct3D device, an IDirect3DDevice7 interface, to be prepared for use with Direct3DX sprite services.

ZEnable

A flag indicating whether the sprites should check and update the z buffer surface as part of rendering. Since, in typical applications, sprites are rendered from back-to-front, the default value is FALSE. Sophisticated applications that want to mix 2-D and 3-D may want to set this value to TRUE. If ZEnable is FALSE, or you are using alpha-blending, then it is necessary to render your sprites from back-to-front.

Return Values

If the function succeeds, the return value is S_OK; otherwise the function returns D3DXERR_NULLPOINTER.

Remarks

C programmers will not be able to take advantage of the default value for the ZEnable parameter.

Call this function to set up all the render states necessary for the D3DXDrawSpriteSimple and D3DXDrawSprite3D functions to work correctly. Note that advanced users may decide not to call this function; in which case the D3DXDrawSpriteSimple and D3DXDrawSprite3D functions will use whatever render and texture states are set up on the device.

Note  The D3DXPrepareDeviceForSprite function modifies render states and may impact performance negatively on some 3-D hardware if it is called too often per frame. If the render state changes (other than through calls to D3DXDrawSpriteSimple or D3DXDrawSprite3D), you will need to call this function again before calling D3DXDrawSpriteSimple or D3DXDrawSprite3D.

The D3DXPrepareDeviceForSprite function modifies the rendering first texture stage and it modifies some render states for the entire device. Here is the exact list:

    SetTextureStageState(0, D3DTSS_COLORARG1,         D3DTA_TEXTURE);
    SetTextureStageState(0, D3DTSS_COLOROP,           D3DTOP_SELECTARG1);
    SetTextureStageState(0, D3DTSS_ALPHAARG1,         D3DTA_TEXTURE);
    SetTextureStageState(0, D3DTSS_ALPHAARG2,         D3DTA_DIFFUSE);
    SetTextureStageState(0, D3DTSS_ALPHAOP,           D3DTOP_MODULATE);
    SetTextureStageState(0, D3DTSS_MINFILTER,         D3DTFN_LINEAR);
    SetTextureStageState(0, D3DTSS_MAGFILTER,         D3DTFG_LINEAR);
 
    SetRenderState(D3DRENDERSTATE_SRCBLEND,           D3DBLEND_SRCALPHA);
    SetRenderState(D3DRENDERSTATE_DESTBLEND,          D3DBLEND_INVSRCALPHA);
    SetRenderState(D3DRENDERSTATE_ALPHABLENDENABLE,   TRUE);

Depending on the value of the ZEnable parameter, this function will either call

    SetRenderState(D3DRENDERSTATE_ZENABLE,            FALSE);

or

    SetRenderState(D3DRENDERSTATE_ZENABLE,            TRUE);

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.