IDirect3DDevice9::StretchRect メソッド

[アーティクル]
04/22/2010

IDirect3DDevice9::StretchRect メソッド

転送元矩形の内容を転送先矩形にコピーする。コピーにより、転送元矩形を拡大およびフィルタリングできる。この関数は、ビデオストリームのアスペクト比の変更によく使われる。

構文

HRESULT StretchRect(      
    IDirect3DSurface9 *pSourceSurface,
    CONST RECT *pSourceRect,
    IDirect3DSurface9 *pDestSurface,
    CONST RECT *pDestRect,
    D3DTEXTUREFILTERTYPE Filter
);

パラメータ

pSourceSurface
[in] 転送元サーフェイスへのポインタ。「IDirect3DSurface9」を参照すること。
pSourceRect
[in] 転送元矩形へのポインタ。このパラメータに NULL を指定すると、転送元サーフェイス全体が使われる。
pDestSurface
[in] 転送先サーフェイスへのポインタ。「IDirect3DSurface9」を参照すること。
pDestRect
[in] 転送先矩形へのポインタ。このパラメータに NULL を指定すると、転送先サーフェイス全体が使われる。
Filter
[in] フィルタタイプ。指定可能な値は、D3DTEXF_NONE、D3DTEXF_POINT、または D3DTEXF_LINEAR である。詳細については、「D3DTEXTUREFILTERTYPE」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合の戻り値は次のとおり。

D3DERR_INVALIDCALL

メソッドの呼び出しが無効である。たとえば、メソッドのパラメータに無効な値が設定されている場合などである。

注意

一般的な制限

IDirect3DDevice9::StretchRect で有効なサーフェイスの組み合わせには、さまざまな制限がある。制限の要因には、ドライバが Microsoft® DirectX® 9.0 ドライバかまたはそれ以前のものであるか、また操作によって拡大/縮小のどちらが発生するかなどが含まれる。アプリケーション側ではドライバが DirectX 9.0 であるかどうかは認識しないため、DirectX 9.0 レベル以上のドライバについては、Microsoft Direct3D® は自動的に新しい D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES 能力を D3DDEVCAPS2 構造体内で設定する。

DirectX 8.x ドライバ (拡大なし)

		転送先フォーマット
		テクスチャ	RT テクスチャ	RT	単純なオフスクリーン
転送元フォーマット	テクスチャ	いいえ	いいえ	いいえ	いいえ
	RT テクスチャ	いいえ	はい	はい	いいえ
	RT	いいえはいはいいいえ
	単純なオフスクリーン	はい	はい	はい	はい

DirectX 8.x ドライバ (拡大あり)

		転送先フォーマット
		テクスチャ	RT テクスチャ	RT	単純なオフスクリーン
転送元フォーマット	テクスチャ	いいえ	いいえ	いいえ	いいえ
	RT テクスチャ	いいえ	いいえ	いいえ	いいえ
	RT	いいえはいはいいいえ
	単純なオフスクリーン	いいえ	はい	はい	いいえ

DirectX 9.0 ドライバ (拡大なし)

		転送先フォーマット
		テクスチャ	RT テクスチャ	RT	単純なオフスクリーン
転送元フォーマット	テクスチャ	いいえ	はい	はい	いいえ
	RT テクスチャ	いいえ	はい	はい	いいえ
	RT	いいえはいはいいいえ
	単純なオフスクリーン	いいえ	はい	はい	はい

DirectX 9.0 ドライバ (拡大あり)

		転送先フォーマット
		テクスチャ	RT テクスチャ	RT	単純なオフスクリーン
転送元フォーマット	テクスチャ	いいえ	はい	はい	いいえ
	RT テクスチャ	いいえ	はい	はい	いいえ
	RT	いいえはいはいいいえ
	単純なオフスクリーン	いいえ	はい	はい	いいえ

IDirect3DDevice9::StretchRect では、転送元サーフェイスと転送先サーフェイスの両方が D3DPOOL_DEFAULT サーフェイスでなければならない。

フィルタリングを指定した場合、IDirect3DDevice9::StretchRect は、ドライバが D3DCAPS9 で適切な StretchRectFilterCaps を設定しないかぎり失敗する。D3DTEXF_NONE を指定した場合、ドライバはフィルタリングアルゴリズムを選択する。

拡大操作は、YUV から高精度 RGBA の色空間の変換のみをサポートしている。同じサーフェイス上の矩形間での拡大はサポートされない。変換のソフトウェアエミュレーションはサポートされないため、IDirect3D9::CheckDeviceFormatConversion を使ってハードウェアの色変換サポートをテストする必要がある。

テクスチャの制限

IDirect3DDevice9::StretchRect は、DirectX 9.0 ドライバ (D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES を設定するドライバ) でのテクスチャサーフェイス (またはキューブテクスチャサーフェイス) でのみ動作する。

深度およびステンシルの制限

深度およびステンシルサーフェイス は、IDirect3DDevice9::StretchRect を使ってコピーできるが、次の制限がある。

転送元および転送先の両方のサーフェイスを、IDirect3DDevice9::CreateDepthStencilSurface で作成する必要がある。これは、どちらもテクスチャではなく平面深度ステンシルサーフェイスでなければならないためである。
どちらのサーフェイスも同じフォーマットでなければならない (フォーマット変換なし)。
拡大も縮小もできない。
サブ矩形のコピーは許可されない。サーフェイス全体をコピーする必要がある。つまり、pSourceRect と pDestRect が NULL またはサーフェイス全体をカバーする矩形のポイントでなければならない。
IDirect3DDevice9::BeginScene/IDirect3DDevice9::EndScene ペアの内部では StretchRect を呼び出せない。
転送元または転送先サーフェイスが、D3DUSAGE_DEPTHSTENCIL で作成したテクスチャのミップレベル (キューブテクスチャ) であってはならない。
どちらのサーフェイスも、"破棄可能" として作成してはならない。
ドライバは、D3DDEVCAPS2_CAN_STRETCHRECT_FROM_TEXTURES を設定する必要がある。「D3DDEVCAPS2」を参照すること。

次のいずれかの場合、IDirect3DDevice9::StretchRect は失敗する。

pSourceSurface と pDestSurface が同じである場合。
拡大または縮小のどちらかが行われ、どちらかのサーフェイスが DXTn 圧縮フォーマットである場合。
転送元サーフェイスがマルチサンプリングされている場合 (MultiSampleType != D3DMULTISAMPLE_NONE で作成した場合)。
転送先サーフェイスが単純なオフスクリーンでありながら、転送元サーフェイスがそうでない場合。転送先サーフェイスが単純なオフスクリーンであり、拡大が行われている場合。

IDirect3DDevice9::StretchRect メソッド

IDirect3DDevice9::StretchRect メソッド

その他のリソース