Platform SDK: DirectX

D3DXDrawSpriteTransform

D3DXDrawSpriteTransform 関数は、指定行列により変換されたスプライトをレンダリングするためのメカニズムを提供している。この関数は、IDirect3DDevice7::BeginScene 関数を呼び出した後で、IDirect3DDevice7::EndScene 関数を呼び出す前に呼び出す必要がある。

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

パラメータ

pd3dTexture
スプライトのソース イメージとして使用するサーフェスを示し、テクスチャが格納されているサーフェスの IDirectDrawSurface7 インターフェイスへのポインタ。これが NULL の場合、アプリケーションがテクスチャ ステージ 0 に対して IDirect3DDevice7::SetTexture を既に呼び出していると見なされる。
pd3dDevice
Direct3D レンダリング デバイスの IDirect3DDevice7 インターフェイスへのポインタ。レンダリング状態がセットアップされていると見なされる。詳細については、「D3DXPrepareDeviceForSprite」を参照すること。
pMatrixTransform
デフォルトの -.5 から +.5 までの矩形に適用される変換を指定した 4 x 4 行列の D3DXMATRIX 構造体へのポインタ。この行列は、スプライトをスクリーン空間に変換する。デフォルトで、スプライトは (-0.5, -0.5) から (+0.5, +0.5) までに置かれている。簡単に回転できるように中心は原点に合わせられ、またスケーリングしやすいように幅と高さは 1 とされている。
alpha
スプライトに適用されるアルファ値。1.0 は全体的に不透明であり、0.0 は全体的に透明であることを意味する。ただし、アルファを使用する場合は、アーティファクト (人工物) がレンダリングされないようにするために、背景から前景へレンダリングすること。また、半透明のオブジェクトが交差しないようにすること。このアルファ値は、テクスチャ イメージ内に存在するアルファ (存在する場合) と組み合わせられる。
pSourceRect
ソース テクスチャの中でスプライトに使用する部分を示す RECT 構造体へのポインタ。このパラメータが NULL の場合、ソース イメージ全体がスプライトで使用される。一方、代わりにソース イメージの小矩形を指定できる。ソース テクスチャが Direct3DX を使用して作成されている場合、RECT 構造体はオリジナル イメージの座標で指定する。そのため、Direct3D カレント デバイスでイメージが機能するように Direct3DX により行われた伸張やスケーリングは必要ない。また、X と Y のミラーリングについては、この RECT 構造体の left、top パラメータと right、bottom パラメータを入れ替えるだけで簡単に指定できる。

戻り値

成功すれば、S_OK を返す。

失敗すれば、次いずれかの値を返す。

D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

注意

C プログラマは、alpha パラメータと pSourceRect パラメータでデフォルト値を使用できない。

この D3DXDrawSpriteTransform 関数は、行列で指定可能なエフェクト、アルファ ブレンディング、小矩形の選択機能 (ソースの小矩形の値が NULL のときは、テクスチャ全体が使用されることを意味する) をサポートしている。スプライトを総合的に制御するには、D3DXDrawSprite3D 関数を使用する。

この関数は、4 x 4 行列を指定して、デフォルトの RECT 構造体の点を変換し (left=-.5、top=-.5、right=+.5、bottom=+.5)、ソース イメージを Direct3D レンダリング デバイスに変換する。このデフォルトの RECT 構造体は、簡単に回転できるように中心が原点に合わせられている。また、これらのディメンジョンは、スケーリングしやすいように幅と高さを 1 にして作成されている。

この関数は、pd3dTexture パラメータが NULL 以外の場合、最初のレンダリング ステージでそのパラメータを指定して IDirect3DDevice7::SetTexture を呼び出すだけである。この関数は、D3DXPrepareDeviceForSprite がデバイスで呼び出された、または呼び出し元のアプリケーションが別の方法でレンダリング状態を適切に準備したと仮定している。

この関数は、変換された点の w 値 (同次座標) が 1 以外の場合、それを逆変換し、その値を Direct3D に D3DTLVERTEX 構造体の rhw フィールドとして渡すので注意すること。w 値が 0 の場合、rhw として 1 を使用する。

行列が (0, 0, 0, 1) 原点を中心とする単位正方形に適用されると、これらの座標はスクリーン空間に完全に変換されているものと見なされる。上級ユーザーには、z 要素と w 要素を D3DTLVERTEX 構造体で Direct3D 直接モードに渡すことをお勧めする。w 要素は、rhw 要素に変換される。w 値が 0 のとき、rhw 値は 1 となる。

動作環境

  Windows NT/2000 : Windows 2000 が必要。
  Windows 95/98 : Windows 95 以上が必要。Windows 95 用に再配布可能な形で使用可能。
  バージョン : DirectX 7.0 が必要。
  ヘッダー : d3dxsprite.h で宣言。
  ライブラリ : d3dx.lib を使用。

参照

D3DXBuildSpriteTransform