IDirect3DDevice9Ex

アプリケーションは IDirect3DDevice9Ex インターフェイスのメソッドを使用して、プリミティブの描画、リソースの作成、システムレベルの変数の操作、ガンマランプレベルの調整、パレットの操作、シェーダーの作成を行います。

IDirect3DDevice9Ex インターフェイスは、IDirect3D9Ex::CreateDeviceEx を呼び出すことで取得します。

LPDIRECT3DDEVICE9EX 型および PDIRECT3DDEVICE9EX 型は、IDirect3DDevice9Ex インターフェイスへのポインターとして定義されています。

typedef struct IDirect3DDevice9Ex *LPDIRECT3DDEVICE9EX, *PDIRECT3DDEVICE9EX;

デバイスの作成

1. Direct3DCreate9Ex を呼び出して Direct3D オブジェクトを作成します。
2. CreateDeviceEx を呼び出して Direct3D デバイスを作成します。

IDirect3D9Ex *pDirect3DEx;
LPDIRECT3DDEVICE9EX pDeviceEx;
DWORD behaviorFlags = D3DCREATE_HARDWARE_VERTEXPROCESSING;

Direct3DCreate9Ex(D3D_SDK_VERSION, &pDirect3DEx);
pDirect3DEx->CreateDeviceEx(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd, behaviorFlags, &d3dpp, NULL, &pDeviceEx);

単色テクスチャーに対するモノクロコンボリューションフィルタリング用にテクスチャーサンプラーを準備します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。

このメソッドは単色テクスチャーをフィルタリングするために設計されています。モノクロコンボリューションフィルターは、すべての重みが 1.0 に設定された 2D ボックスフィルターです。フィルターカーネルの解像度は 1 x 1 から 7 x 7 までの範囲です。テクスチャーサンプラーにモノクロテクスチャーフィルタリングが設定され、ある位置でテクスチャーサンプリングが実行されると、Direct3D はコンボリューションを実行します。

制限事項は次のとおりです。

• このメソッドで指定されたフィルターは、D3DSBT_PIXELSTATE の一部としてステートブロックに記録されます。
• サポートされるテクスチャーアドレスモードは D3DPTADDRESSCAPS_BORDER のみです。境界色は常に 0 です。
• このメソッドはミップマップではサポートされません。
• モノクロ以外のテクスチャーをコンボリューションフィルタリングで使用すると、ドライバーエラーが発生します。

一方のサーフェス上にあるグリフのアルファベットを使用して、もう一方のサーフェスにテキスト文字列をコピーします。合成はビット演算を用いて GPU で行われます。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。

このメソッドにより、1 ビットのソースサーフェスのグリフが、別の 1 ビットのテクスチャーサーフェスにまとめて配置されます。その出力先サーフェスは、通常のテクスチャリング処理のソースとして使用でき、テキスト文字列をフィルタリングおよびスケーリングして、モノクロ以外の別のサーフェスに描画できます。

このメソッドにはいくつかの制約があります (StretchRect と同様です)。

• サーフェスをロックすることはできません。
• ソースサーフェスと出力先サーフェスを同一のサーフェスにすることはできません。
• ソースサーフェスと出力先サーフェスは D3DFMT_A1 形式で作成する必要があります。
• ソースサーフェスと 2 つの頂点バッファーは D3DPOOL_DEFAULT フラグを指定して作成する必要があります。
• 出力先サーフェスは D3DPOOL_DEFAULT または D3DPOOL_SYSTEMMEM のいずれかのフラグを指定して作成する必要があります。
• ソース矩形はソースサーフェスの内部になければなりません。

スワップチェーンの次のバッファーをフロントバッファーと入れ替えます。

型: HRESULT

返される可能性のある値: S_OK、D3DERR_DEVICELOST、D3DERR_DEVICEHUNG、D3DERR_DEVICEREMOVED、D3DERR_OUTOFVIDEOMEMORY (D3DERR を参照)、または S_PRESENT_OCCLUDED、S_PRESENT_MODE_CHANGED (S_PRESENT を参照)。ロスト状態、ハング状態、削除されたデバイスの詳細については、Lost Device Behavior Changes を参照してください。

IDirect3DDevice9::Present メソッドと同様ですが、PresentEx には dwflags パラメーターが追加されています。

スワップチェーンが D3DSWAPEFFECT_FLIPEX フラグで作成されている場合、pSourceRect、pDestRect、pDirtyRegion の値は NULL に設定する必要があります。

GPU スレッドの優先度を取得します。

型: HRESULT

返される可能性のある値: D3D_OK または D3DERR_DEVICEREMOVED (D3DERR を参照)。

スレッドの優先度を設定するには IDirect3DDevice9Ex::SetGPUThreadPriority を使用します。

このメソッドは、Direct3D デバイスが D3DCREATE_PUREDEVICE フラグを指定して作成されていた場合でも、デバイスに格納されているスレッドの優先度を取得します。

GPU スレッドの優先度を設定します。

型: HRESULT

返される可能性のある値: D3D_OK、D3DERR_INVALIDCALL、または D3DERR_DEVICEREMOVED (D3DERR を参照)。

GPU スレッドの優先度は、デバイスがロストしてもリセットされません。このメソッドの呼び出しによる効果はステートブロックには記録されません。

次の垂直帰線信号が発生するまで、呼び出し元スレッドの実行を中断します。

型: HRESULT

このメソッドは常に D3D_OK を返します。

このメソッドにより、アプリケーションはフレームレートをデバイスに関連付けられたモニターのリフレッシュレートに効率的に合わせることができます。垂直帰線の後、スレッドが起床するまでに要する時間は通常きわめて短くなります。

状況によっては、モニターに何も表示されていないときにハードウェアが垂直帰線信号の生成を停止することがあります。この場合、このメソッドは約 100ms 待機してから D3D_OK を返します。

リソースの配列を調べ、システムがそれらのリソースを GPU からアクセス可能にする必要があるために、Draw 実行時に大きなストールが発生する可能性が高いかどうかを判定します。

型: HRESULT

すべてのリソースが GPU からアクセス可能なメモリ上にある場合、このメソッドは S_OK を返します。システムはリソースを昇格させるために再マッピング操作を実行する必要がある場合がありますが、データのコピーは不要です。

リソースを構成するアロケーションがいずれもディスク上になく、少なくとも 1 つのアロケーションが GPU からアクセス可能なメモリ上にない場合、このメソッドは S_RESIDENT_IN_SHARED_MEMORY を返します。システムはリソースを昇格させるためにコピーを実行する必要がある場合があります。

リソースを構成するアロケーションのうち少なくとも 1 つがディスク上にある場合、このメソッドは S_NOT_RESIDENT を返します。システムはリソースを昇格させるためにコピーを実行する必要がある場合があります。

この API は常駐状態についての妥当な推測にすぎません。アプリケーションがリソースを使用する時点では、すでに降格されている可能性があるためです。

想定される使用パターンは次のとおりです。アプリケーションが一連のリソースが常駐していないと判断した場合、より低い LOD のリソースで代用して描画を継続します。ビデオメモリマネージャー API には、これらの低 LOD リソースを GPU からアクセス可能なメモリに常駐したままにしやすくするようアプリケーションが要求できる機能があります。これらの低 LOD 版の作成、内容の設定、破棄はアプリケーションの責任です。

また、常駐チェックによりリソースが GPU からアクセス可能なメモリに常駐していないことが示された場合、アプリケーションは高 LOD 版の昇格を開始する必要もあります。カーネルモードにはプロセスごとのロックが存在するため、性能の高い実装ではリソースの昇格のみを担当する別プロセスを起動します。アプリケーションは Sharing Resources の共有サーフェス API によって 2 つのプロセス間でリソースの同一性を伝達し、SetPriority によってそれらを昇格させます。

システムが描画のためにキューに入れることを許可されるフレーム数を設定します。

型: HRESULT

返される可能性のある値: D3D_OK または D3DERR_DEVICEREMOVED (D3DERR を参照)。

フレームレイテンシとは、描画のために送信される前にキューに格納しておくことが許可されるフレーム数のことです。レイテンシは、CPU がユーザー入力への応答と描画キュー内のフレームのどちらを優先するかを制御するためによく使用されます。

ユーザー入力のないアプリケーション (たとえば動画再生) では、3 フレームを超えるデータをキューに入れることが有益な場合がよくあります。

システムがキューに入れることを許可されるデータのフレーム数を取得します。

型: HRESULT

返される可能性のある値: D3D_OK、D3DERR_DEVICELOST、D3DERR_DEVICEREMOVED、D3DERR_DRIVERINTERNALERROR、D3DERR_INVALIDCALL、または D3DERR_OUTOFVIDEOMEMORY (D3DERR を参照)。

フレームレイテンシとは、描画のために送信される前にキューに格納しておくことが許可されるフレーム数のことです。レイテンシは、CPU がユーザー入力への応答と描画キュー内のフレームのどちらを優先するかを制御するためによく使用されます。

ユーザー入力のないアプリケーション (たとえば動画再生) では、3 フレームを超えるデータをキューに入れることが有益な場合がよくあります。

ウィンドウモードまたはフルスクリーンモードのアプリケーションに対して、Direct3D デバイスの現在の協調レベルの状態を報告します。(IDirect3DDevice9Ex.CheckDeviceState)

型: HRESULT

返される可能性のある値: D3D_OK、D3DERR_DEVICELOST、D3DERR_DEVICEHUNG、D3DERR_DEVICEREMOVED、D3DERR_OUTOFVIDEOMEMORY (D3DERR を参照)、または S_PRESENT_MODE_CHANGED、S_PRESENT_OCCLUDED (S_PRESENT を参照)。

このメソッドは IDirect3DDevice9::TestCooperativeLevel を置き換えるものです。TestCooperativeLevel は Direct3D 9Ex アプリケーションでは常に S_OK を返します。

CheckDeviceState をフレームごとに呼び出すことは推奨されません。代わりに、IDirect3DDevice9Ex::PresentEx メソッドが失敗コードを返した場合にのみ CheckDeviceState を呼び出してください。

ロスト状態、ハング状態、削除されたデバイスの詳細については、Lost Device Behavior Changes を参照してください。

レンダーターゲットサーフェスを作成します。(IDirect3DDevice9Ex.CreateRenderTargetEx)

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。メソッドが失敗した場合、戻り値は次のいずれかになります: D3DERR_NOTAVAILABLE、D3DERR_INVALIDCALL、D3DERR_OUTOFVIDEOMEMORY、E_OUTOFMEMORY。

レンダーターゲットサーフェスは D3DPOOL_DEFAULT メモリクラスに配置されます。

ロック可能なマルチサンプルレンダーターゲットの作成はサポートされていません。

オフスクリーンサーフェスを作成します。(IDirect3DDevice9Ex.CreateOffscreenPlainSurfaceEx)

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。メソッドが失敗した場合、戻り値は次のとおりです: D3DERR_INVALIDCALL。

D3DPOOL_SCRATCH を指定すると、DirectX 8.x のメソッド CreateImageSurface で作成されるサーフェスと同一の特性を持つサーフェスが返されます。

D3DPOOL_DEFAULT は、IDirect3DDevice9::StretchRect および IDirect3DDevice9::ColorFill と併用するのに適したプールです。

オフスクリーンプレーンサーフェスの作成時に D3DPOOL_MANAGED を指定することはできません。メモリプールの詳細については、D3DPOOL を参照してください。

オフスクリーンプレーンサーフェスは、プールの種類にかかわらず常にロック可能です。

深度ステンシルサーフェスを作成します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。メソッドが失敗した場合、戻り値は次のいずれかになります: D3DERR_NOTAVAILABLE、D3DERR_INVALIDCALL、D3DERR_OUTOFVIDEOMEMORY、E_OUTOFMEMORY。

深度ステンシルバッファーのメモリクラスは常に D3DPOOL_DEFAULT です。

他のすべてのサーフェスを保持したまま、スワップチェーンの種類、サイズ、形式をリセットします。

型: HRESULT

このメソッドは次を返す可能性があります: D3D_OK、D3DERR_DEVICELOST、D3DERR_DEVICEHUNG (D3DERR を参照)。

このメソッドが D3DERR_DEVICELOST または D3DERR_DEVICEHUNG を返した場合、アプリケーションは IDirect3DDevice9Ex::ResetEx、IDirect3DDevice9Ex::CheckDeviceState の呼び出し、またはインターフェイスポインターの解放しか行えません。それ以外の API 呼び出しは例外を引き起こします。

IDirect3DDevice9Ex::ResetEx の呼び出しが失敗すると、デバイスはロスト状態になります (IDirect3DDevice9Ex::CheckDeviceState の呼び出しが D3DERR_DEVICELOST を返すことで示されます)。ロストしたデバイスにおける IDirect3DDevice9Ex::ResetEx の使用については、IDirect3DDevice9Ex::CheckDeviceState および Lost Device Behavior Changes を参照してください。

DirectX の以前のバージョンとは異なり、IDirect3DDevice9Ex::ResetEx を呼び出してもサーフェス、テクスチャー、ステート情報が失われることはありません。

Direct3D 9 では、ピクセルシェーダーおよび頂点シェーダーは IDirect3DDevice9Ex::ResetEx の呼び出し後も保持されます。アプリケーションが明示的に再作成する必要はありません。

スワップチェーンにはフルスクリーンとウィンドウの 2 種類があります。新しいスワップチェーンがフルスクリーンの場合、アダプターは新しいサイズに一致するディスプレイモードに設定されます。

この呼び出しの間 (たとえば、この呼び出しが戻る前) にアプリケーションへメッセージが送信されることがあります。アプリケーションはこの時点で Direct3D を呼び出さないよう注意する必要があります。

リセット対象のデバイスを作成したスレッドとは異なるスレッドで IDirect3DDevice9Ex::ResetEx を呼び出すと、呼び出しは失敗します。

IDirect3D9Ex::CreateDeviceEx、IDirect3DDevice9Ex::ResetEx、IDirect3DDevice9::CreateAdditionalSwapChain を呼び出す際、ウィンドウモードのバックバッファー形式には D3DFMT_UNKNOWN を指定できます。つまり、ウィンドウモードで IDirect3D9Ex::CreateDeviceEx を呼び出す前に、アプリケーションが現在のデスクトップ形式を照会する必要はありません。フルスクリーンモードの場合は、バックバッファー形式を指定する必要があります。BackBufferCount を 0 に設定すると (BackBufferCount = 0)、バックバッファーは 1 つになります。

グループ内の複数のディスプレイアダプターをリセットする場合は、pPresentationParameters がアダプターグループ内のディスプレイごとに 1 つの D3DPRESENT_PARAMETERS 構造体を持つ配列を指すように設定します。

マルチヘッドデバイスが D3DCREATE_ADAPTERGROUP_DEVICE で作成された場合、IDirect3DDevice9Ex::ResetEx には D3DPRESENT_PARAMETERS 構造体の配列が必要であり、各構造体はフルスクリーンディスプレイを指定する必要があります。ウィンドウモードに戻すには、アプリケーションはデバイスを破棄し、ウィンドウモードでマルチヘッドでないデバイスを再作成する必要があります。

ディスプレイモードの空間解像度、色解像度、リフレッシュレート、回転設定を取得します。(IDirect3DDevice9Ex.GetDisplayModeEx)

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。メソッドが失敗した場合、戻り値は D3DERR_INVALIDCALL になることがあります。