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

[アーティクル]
03/08/2023

DxgkDdiRender 関数は、ユーザーモードディスプレイドライバーが渡したコマンドバッファーからダイレクトメモリアクセス (DMA) バッファーを生成します。

構文

DXGKDDI_RENDER DxgkddiRender;

NTSTATUS DxgkddiRender(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRender
)
{...}

パラメーター

[in] hContext

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

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

[in/out] pRender

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

戻り値

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

リターンコード	説明
STATUS_SUCCESS	コマンドバッファー全体が変換されました。
STATUS_NO_MEMORY	DxgkDdiRender は、完了するために必要なメモリを割り当てませんでした。
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	現在の DMA バッファーが不足しています。
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender は、特権のない命令 (つまり、現在の中央処理装置 [CPU] プロセスの特権を超えてメモリにアクセスする命令) を検出しました。
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender によって、グラフィックスハードウェアでサポートできない命令が検出されました。
STATUS_INVALID_PARAMETER	DxgkDdiRender は、グラフィックスハードウェアでサポートできない命令パラメーターを検出しました。ただし、グラフィックスハードウェアは命令自体をサポートできます。ドライバーは、このエラーコードを返す必要はありません。代わりに、サポートされていない命令パラメーターを検出したときにSTATUS_ILLEGAL_INSTRUCTIONを返すことができます。
STATUS_INVALID_USER_BUFFER	DxgkDdiRender によって、データまたは命令のアンダーランまたはオーバーランが検出されました。つまり、ドライバーは予想よりも少ない、またはそれ以上の命令またはデータを受け取った。ドライバーは、このエラーコードを返す必要はありません。代わりに、データまたは命令のアンダーランまたはオーバーランが検出されたときにSTATUS_ILLEGAL_INSTRUCTIONを返すことができます。
STATUS_INVALID_HANDLE	DxgkDdiRender がコマンドバッファーで無効なハンドルを検出しました。
STATUS_GRAPHICS_DRIVER_MISMATCH	ディスプレイミニポートドライバーは、DxgkDdiRender (つまり、コマンドバッファーを送信) への呼び出しを開始したユーザーモードディスプレイドライバーと互換性がありません。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	ディスプレイミニポートドライバーは、DMA ストリームでエラーを検出しました。ドライバーがこのエラーコードを返した場合、グラフィックスコンテキストデバイスは失われた状態になります。

注釈

DirectX グラフィックスカーネルサブシステムは、ディスプレイミニポートドライバーの DxgkDdiRender 関数を呼び出して、ユーザーモードディスプレイドライバーが渡したコマンドバッファーから DMA バッファーを生成します。ディスプレイミニポートドライバーがコマンドバッファーから DMA バッファーに変換する場合、ドライバーはコマンドバッファーも検証して、コマンドバッファーに、プロセスに属していないメモリへのアクセスに使用できる特権コマンドまたはコマンドが含まれていないことを確認する必要があります。出力 DMA バッファーに加えて、ディスプレイミニポートドライバーは、出力パッチの場所の一覧も生成する必要があります。ビデオメモリマネージャーでは、この一覧を使用して DMA バッファーを適切に分割してパッチを適用します。

コマンドバッファー pCommand と、ユーザーモードディスプレイドライバーによって生成される入力パッチの場所リスト pPatchLocationListIn の 両方が、ユーザーモードのアドレス空間から割り当てられ、手つかずでディスプレイミニポートドライバーに渡されます。ディスプレイミニポートドライバーは、バッファーとリストへの任意のアクセスでコードを使用__try/__exceptする必要があり、各カーネルバッファーにコンテンツをコピーする前にバッファーとリストの内容を検証する必要があります (つまり、pCommand メンバーのコンテンツを pDmaBuffer メンバーにコピーし、pPatchLocationListIn メンバーのコンテンツを pPatchLocationListOut メンバーにコピーする前に)pRender パラメーターが指すDXGKARG_RENDER構造体のすべてのメンバーです)。

ディスプレイミニポートドライバーがと __except ロジックを使用してこれらのバッファーにアクセスする方法の例を__try次に示します。 AllocationListIn は 、ユーザーモードバッファーを指します。

__try
  {
    for (Index = 0; Index < AllocationListInSize; AllocationTable++, 
           AllocationListIn++, AllocationListOut++, Index++) 
    {
      D3DKMT_HANDLE AllocationHandle = AllocationListIn->hAllocation;
      . . .
    }
  }
__except(EXCEPTION_EXECUTE_HANDLER)
  {
    Status = STATUS_INVALID_PARAMETER;
    SAMPLE_LOG_ERROR(
  "Exception occurred accessing user-mode allocation list. Returning Status=0x%I64x",
      Status);
    goto cleanup;
  }

注意

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

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

ユーザーモードディスプレイドライバーが提供する割り当てリストは、カーネル遷移中に検証、コピー、およびカーネルモード割り当てリストに変換されます。 DirectX グラフィックスカーネルサブシステムは、ユーザーモードディスプレイドライバーが提供するD3DKMT_HANDLE型のハンドルをデバイス固有のハンドルに変換することで、各D3DDDI_ALLOCATIONLIST要素をDXGK_ALLOCATIONLIST要素に変換します。このハンドルは、ディスプレイミニポートドライバーの DxgkDdiOpenAllocation 関数が返します。各割り当てのインデックスと割り当ての書き込み状態 (つまり、 WriteOperation ビットフィールドフラグの設定) は、変換中も一定のままです。

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

注意

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

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

ディスプレイミニポートドライバーがコマンドバッファーを DMA バッファーに変換すると、ディスプレイミニポートドライバーとユーザーモードディスプレイドライバーは、次の状況に対して次のアクションを実行する必要があります。

保証されたコントラクト DMA モードでは (詳細については、「保証されたコントラクト DMA バッファーモデルの使用」を参照)、ユーザーモードディスプレイドライバーは変換コマンドに十分なリソースを保証する必要があります。翻訳に十分なリソースが存在しない場合、ディスプレイミニポートドライバーは DMA バッファーを拒否する必要があります。
ディスプレイミニポートドライバーの DxgkDdiRender 関数は DMA バッファーのサイズよりも大きく、分割できない 1 つのコマンドを処理できないため、ユーザーモードディスプレイドライバーは常に、1 つの DMA バッファーのサイズを超える可能性があるコマンドを分割する必要があります。

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

DXgkDdiRenderKm 関数のサポートは、GDI ハードウェアアクセラレーションをサポートするディスプレイアダプター用の Windows 7 以降に追加されました。

要件

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