DXGKDDI_RENDERKM コールバック関数 (d3dkmddi.h)

[アーティクル]
06/09/2023

GDI ハードウェアアクセラレータをサポートするディスプレイアダプターの場合、 DxgkDdiRenderKm 関数は、カーネルモード正規ディスプレイドライバー (CDD) が渡したコマンドバッファーからダイレクトメモリアクセス (DMA) バッファーを生成します。

構文

DXGKDDI_RENDERKM DxgkddiRenderkm;

NTSTATUS DxgkddiRenderkm(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRenderKmArgs
)
{...}

パラメーター

[in] hContext

DMA バッファーとコマンドバッファーのデバイスコンテキストへのハンドル。ディスプレイミニポートドライバーの DxgkDdiCreateContext 関数は、DxgkDdiCreateContext の pCreateContext パラメーターが指すDXGKARG_CREATECONTEXT構造体の hContext メンバーで、このハンドルを以前に返しました。

ドライバーがコンテキストの作成をサポートしていない場合、Microsoft DirectX グラフィックスカーネルサブシステムは、コンテキストへのハンドルをデバイスへのハンドルに置き換えます。ディスプレイミニポートドライバーの DxgkDdiCreateDevice 関数は、DxgkDdiCreateDevice の pCreateDevice パラメーターが指すDXGKARG_CREATEDEVICE構造体の hDevice メンバーのデバイス ハンドルを以前に返しました。

[in/out] pRenderKmArgs

DMA バッファーと書式設定されたコマンドバッファーに関する情報を含む DXGKARG_RENDER構造体への ポインター。

ディスプレイミニポートドライバーが GDI ハードウェアアクセラレータをサポートしている場合、pRenderKmArgs-pCommand> は DXGK_RENDERKM_COMMAND コマンドバッファーを指します。

ドライバーは、入力コマンドバッファーを DMA バッファーコマンドに変換し、パッチの場所の一覧をビルドする必要があります。

戻り値

DxgkDdiRenderKm は 、次のいずれかの値を返します。

リターンコード	説明
STATUS_SUCCESS	コマンドバッファー全体が変換されました。
STATUS_NO_MEMORY	DxgkDdiRenderKm では、完了するために必要なメモリを割り当てませんでした。
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	現在の DMA バッファーが使い果たされました。
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm は、グラフィックスハードウェアがサポートできない命令パラメーターを検出しました。ただし、グラフィックスハードウェアは命令自体をサポートできます。ドライバーは、このエラーコードを返すために必要ありません。代わりに、サポートされていない命令パラメーターを検出したときにSTATUS_ILLEGAL_INSTRUCTIONを返すことができます。
STATUS_INVALID_USER_BUFFER	DxgkDdiRenderKm で、データまたは命令のアンダーランまたはオーバーランが検出されました。つまり、ドライバーが受け取った命令またはデータが予想よりも少ない、または多い。ドライバーは、このエラーコードを返すために必要ありません。代わりに、データまたは命令のアンダーランまたはオーバーランが検出されたときにSTATUS_ILLEGAL_INSTRUCTIONを返すことができます。
STATUS_INVALID_HANDLE	DxgkDdiRenderKm によって、コマンドバッファー内の無効なハンドルが検出されました。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	ディスプレイミニポートドライバーが DMA ストリームでエラーを検出しました。ドライバーがこのエラーコードを返した場合、グラフィックスコンテキストデバイスは失われた状態になります。

注釈

DirectX グラフィックスカーネルサブシステムは、ディスプレイミニポートドライバーの DxgkDdiRenderKm 関数を呼び出して、オペレーティングシステムによって提供されるカーネルモード正規ディスプレイドライバー (CDD) によって渡されるコマンドバッファーから DMA バッファーを生成します。出力 DMA バッファーに加えて、ディスプレイミニポートドライバーは、出力パッチの場所の一覧も生成する必要があります。ビデオメモリマネージャーは、この一覧を使用して、DMA バッファーを適切に分割および修正します。

カーネルバッファーへのアクセスには、コードからの try/except 保護は必要ありません。

ディスプレイミニポートドライバーは、情報をより最適に再作成できる場合、CDD が提供する情報を使用する必要はありません。たとえば、pRender-pPatchLocationListIn> メンバーが空の場合、ユーザーモードのディスプレイドライバーが入力パッチの場所リストを提供していないため、ディスプレイミニポートドライバーは、代わりにコマンドバッファーの内容に基づいて pRender-pPatchLocationListOut> メンバーのコンテンツを生成できます。

DirectX グラフィックスカーネルサブシステムは、デバイス固有のハンドルに加えて、各割り当ての最後の既知の GPU セグメントアドレスをディスプレイミニポートドライバーに提供します。割り当てインデックス N が現在ページアウトされている場合、DirectX グラフィックスカーネルサブシステムは、DXGKARG_RENDERの pAllocationList メンバーの N番目の要素の SegmentId メンバーを 0 に設定します。割り当てリストの N番目の要素の SegmentId メンバーが 0 に設定されていない場合、DirectX グラフィックスカーネルサブシステムが DxgkDdiPatch 関数を呼び出して DMA バッファーを再パッチする前に、ディスプレイミニポートドライバーは、指定されたセグメントアドレス情報を使用して生成された DMA バッファーにパッチを適用する必要があります。 DirectX グラフィックスカーネルサブシステムは、ドライバーが適切に修正プログラムを適用する必要がある DMA バッファーで DxgkDdiPatch 関数を呼び出さない可能性があるため、ドライバーは要求されたときにこの初期修正プログラムを実行する必要があります。

ドライバーの DxgkDdiRenderKm 関数は、前に説明したように、最初の DMA バッファーの修正プログラムの適用を実行しますが、ドライバーは引き続き、DXGKARG_RENDER の pPatchLocationListOut メンバーが指定する出力パッチの場所の一覧に割り当てへのすべての参照を挿入する必要があります。 DMA バッファーが GPU に送信される前に割り当てのアドレスが変更される可能性があるため、この一覧にはすべての参照が含まれている必要があります。したがって、DirectX グラフィックスカーネルサブシステムは DxgkDdiPatch 関数を呼び出して DMA バッファーを再パッチします。

割り当てをバインド解除するには、ディスプレイミニポートドライバーは 、NULL ハンドルを参照する割り当てリスト内の要素を指定し、その NULL 割り当てを参照する修正プログラムの場所要素を使用できます。通常、ドライバーでは、割り当てリストの最初の要素 (要素 0) を NULL 要素として使用する必要があります。

保証されたコントラクト DMA モードでは、ディスプレイミニポートドライバーがコマンドバッファーを DMA バッファーに変換する場合、CDD は変換コマンドに十分なリソースを保証する必要があります。翻訳に十分なリソースが存在しない場合、ディスプレイミニポートドライバーは DMA バッファーを拒否する必要があります。詳細については、「保証されたコントラクト DMA バッファーモデルの使用」を参照してください。

DxgkDdiRenderKm を ページング可能にする必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows 7
対象プラットフォーム	デスクトップ
Header	d3dkmddi.h
IRQL	PASSIVE_LEVEL