DXGI_DDI_BASE_FUNCTIONS 構造体 (dxgiddi.h)

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

DXGI_DDI_BASE_FUNCTIONS構造体には、出力にレンダリングされたフレームの表示、ガンマの制御、全画面表示の切り替えの管理など、低レベルのタスクを実行するためにユーザーモードディスプレイドライバーが実装できる関数が含まれています。

構文

typedef struct DXGI_DDI_BASE_FUNCTIONS {
  HRESULT()(DXGI_DDI_ARG_PRESENT *) * pfnPresent;
  HRESULT()(DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS *) * pfnGetGammaCaps;
  HRESULT()(DXGI_DDI_ARG_SETDISPLAYMODE *) * pfnSetDisplayMode;
  HRESULT()(DXGI_DDI_ARG_SETRESOURCEPRIORITY *) * pfnSetResourcePriority;
  HRESULT()(DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *) * pfnQueryResourceResidency;
  HRESULT()(DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES *) * pfnRotateResourceIdentities;
  HRESULT()(DXGI_DDI_ARG_BLT *) * pfnBlt;
} DXGI_DDI_BASE_FUNCTIONS;

メンバー

pfnPresent

PresentDXGI 関数へのポインター。アプリケーションがレンダリングを完了したことをユーザーモードの表示ドライバーに通知し、ドライバーが移動先画面に表示するように要求します。

pPresentData パラメーターが指すDXGI_DDI_ARG_PRESENT構造体の hDevice メンバーは、ドライバーの CreateDevice(D3D10) 関数がD3D10DDIARG_CREATEDEVICE構造体の hDrvDevice メンバーでランタイムに渡したのと同じハンドルです。そのため、ドライバーライターは、このハンドルの種類を慎重に定義する必要があります。さらに、ドライバーは、CreateDevice(D3D10) の呼び出しを処理した DDI 実装に基づいて、PresentDXGI 関数のさまざまな実装を提供できます。ランタイムは、DDI 実装間でドライバーハンドルを混在させることはありません。同様に、DXGI_DDI_ARG_PRESENT の hSurfaceToPresent メンバーと hDstResource メンバーは、ドライバーの CreateResource(D3D10) 関数の以前の呼び出しでドライバーがランタイムに返したドライバー定義のリソースハンドルでもあります。

DXGI_DDI_ARG_PRESENT の pDXGIContext メンバーは、不透明な通信メカニズムです。ランタイムは、この DXGI コンテキストをドライバーに渡します。ドライバーは、ドライバーが pfnPresentCbDXGI 関数を呼び出すときに、この DXGI コンテキストをDXGIDDICB_PRESENT構造体の pDXGIContext メンバーに変更せずにコピーする必要があります。

ドライバーは、 pfnRenderCb 関数を使用して、部分的に構築されたすべてのレンダリングデータ (コマンドバッファー) を送信する必要があります。その後、ドライバーはリソースハンドルパラメーターをカーネルハンドルに変換し、 pfnPresentCbDXGI の呼び出しでこれらのカーネルハンドルを使用する必要があります。

注意

ドライバーの PresentDXGI 関数が sRGB 形式のコンテンツをソースサーフェイスから非 sRGB 変換先サーフェスにコピーする場合、ドライバーは変更せずに sRGB コンテンツをコピーする必要があります (つまり、ドライバーは sRGB から線形変換を実行しないでください)。

pPresentData

[入力]変換先サーフェスに表示する方法を説明する DXGI_DDI_ARG_PRESENT 構造体へのポインター。

pfnGetGammaCaps

GetGammaCapsDXGI 関数はガンマ機能を取得します。

pGammaData

[入力]ガンマ機能を含む DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS 構造体へのポインター。

pfnSetDisplayMode

ドライバーの SetDisplayModeDXGI 関数へのポインター。

pfnSetResourcePriority

SetResourcePriorityDXGI 関数は、リソースのメモリからの削除の優先順位を設定します。

Microsoft Direct3D ランタイムは SetResourcePriorityDXGI を呼び出して、リソースの優先度レベルを設定します。ユーザーモードディスプレイドライバーは、pPriorityData によって指されるDXGI_DDI_ARG_SETRESOURCEPRIORITY構造体の hResource メンバーで提供されるリソースハンドルを割り当てハンドルに変換する必要があります。ドライバーがこの変換を行った後、ドライバーは pfnSetPriorityCb 関数の呼び出しで結果のハンドルを渡す必要があります。

pPriorityData

[入力]リソースを設定する優先度レベルを記述する DXGI_DDI_ARG_SETRESOURCEPRIORITY 構造体へのポインター。

pfnQueryResourceResidency

この関数は、指定されたリソースの一覧の所在地を決定します。

Microsoft Direct3D ランタイムは、ユーザーモードディスプレイドライバーの QueryResourceResidencyDXGI 関数をアプリケーション用に呼び出して、システムがリソースを GPU アクセス可能にする必要がある場合に、描画時にオペレーティングシステムに重大な停止が発生するかどうかを判断します。 QueryResourceResidencyDXGI から返される情報は、アプリケーションがリソースを使用する前にリソースが降格される可能性があるため、リソースの所在地の近似値です。

QueryResourceResidencyDXGI は 、pfnQueryResidencyCb 関数を呼び出す必要があります。 pfnQueryResidencyCb は、D3DDDICB_QUERYRESIDENCY構造体の pResidencyStatus メンバーによって指定された配列の要素内のリソースの常駐状態を返します。 pfnQueryResidencyCb がクエリのD3DDDI_RESIDENCYSTATUS_NOTRESIDENTを返す場合、QueryResourceResidencyDXGI はS_NOT_RESIDENTを返す必要があります。 pfnQueryResidencyCb がクエリのD3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORYを返し、クエリのD3DDDI_RESIDENCYSTATUS_NOTRESIDENTを返さない場合、QueryResourceResidencyDXGI はS_RESIDENT_IN_SHARED_MEMORYを返す必要があります。 QueryResourceResidencyDXGI は、すべてのクエリに対する pfnQueryResidencyCb のすべての呼び出しがD3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORYを返す場合にのみ、S_OKを返す必要があります。

ランタイムが QueryResourceResidencyDXGI の呼び出しを介してクエリを実行する各リソースについて、ユーザーモードディスプレイドライバーは 、pfnQueryResidencyCb の呼び出しを介してクエリを実行するリソースに属する割り当てを決定する必要があります。 1 つの割り当てを所有するリソースの場合、決定は単純です。ドライバーはその割り当てを照会します。ただし、リソースが複数の割り当てを所有している場合、決定はより困難です。ドライバーは、アプリケーションがレンダリングに使用する可能性が高い割り当てを決定する必要があり、ドライバーはそれらの割り当てにのみクエリを実行する必要があります。たとえば、リソースがレンダリングに使用される割り当てと、ロック操作を処理するスクラッチ割り当てを所有している場合、アプリケーションではレンダリングに 2 番目の割り当てが使用されない可能性が高いため、ドライバーは最初の割り当ての所在地についてのみクエリを実行する必要があります。

注意

ランタイムはシステムメモリリソースの常駐クエリをサポートしていないため、ランタイムは常にシステムメモリリソースの常駐状態に関するアプリケーションからの要求を失敗させ、これらのシステムメモリリソースに対してユーザーモードディスプレイドライバーの QueryResourceResidencyDXGI 関数を呼び出すことはありません。

pResidencyData

[入力]所在地が検証されるリソースの一覧を記述する DXGI_DDI_ARG_QUERYRESOURCERESIDENCY 構造体へのポインター。

pfnRotateResourceIdentities

リソースの一覧をローテーションします。

RotateResourceIdentitiesDXGI 関数は、pRotateData パラメーターが指すDXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES構造体の pResources メンバーで渡されるリソースの配列の ID を交換する必要があります。たとえば、リソースの配列がリソース X、Y、Z を参照している場合、配列インデックスの順序を増やすと、 RotateResourceIdentitiesDXGI は、配列インデックスの順序を増やして、Y、Z、X を参照するようにこれらのハンドルを回転させる必要があります。特に、ユーザーモードディスプレイドライバーは、対応するリソースのカーネルハンドルをスワップする必要があります。ただし、ドライバーは対応するランタイム (RT) ハンドルをスワップしないでください。ランタイムは RotateResourceIdentitiesDXGI を呼び出して、プレゼンテーション中にバッファーを回転させます。そのため、 RotateResourceIdentitiesDXGI の呼び出しはまれです。ランタイムは、ランタイムがドライバーの CreateResource(D3D10) 関数を呼び出して、リソースが回転操作に参加できることを示すときに、D3D10DDIARG_CREATERESOURCE構造体の BindFlags メンバーに D3D10_DDI_BIND_PRESENT フラグを指定できます。

ユーザーモードディスプレイドライバーは、ID の交換の他の側面も処理する必要があります。たとえば、Direct3D バージョン 10 では、ビューはリソースを参照できます。このようなビューにはリソースアドレスを埋め込むことができます。そのため、ドライバーは、このようなビューを再作成する必要があります。また、ドライバーは、現在バインドされているビューを再適用する必要がある場合があります。

Windows 8以降、ドライバーはステレオバックバッファーの回転をサポートする必要があります。

pRotateData

[入力]ローテーションするリソースの一覧を記述する DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES 構造体へのポインター。

pfnBlt

ソースサーフェスの内容をコピー先サーフェスにコピーし、コンテンツを回転できます。

Direct3D ランタイムは、pBltData パラメーターが指すDXGI_DDI_ARG_BLT構造体の Flags メンバーを、複数サンプリングされたリソースを解決し、色形式の変換を実行し、一度にストレッチまたは縮小を実行するビットブロック転送 (bitblt) 操作を実行するように BltDXGI 関数を要求するように設定できます。ただし、Direct3D ランタイムは、DXGI_DDI_ARG_BLT のFlags メンバーを 0 (つまり、フラグが設定されていません) に設定することはなく、DXGI_DDI_ARG_BLTの Rotate メンバー (つまり、回転がないことを示すために) に設定されたDXGI_DDI_MODE_ROTATION_IDENTITY値と共に、メモリの直接コピー操作を実行します。代わりに、両方のリソースがマルチサンプリングされない限り、Direct3D ランタイムはドライバーの ResourceCopy または ResourceCopyRegion 関数を呼び出して、ストレートメモリコピー操作を実行します。

ユーザーモードのディスプレイドライバーが実行するストレッチまたは圧縮の品質は、二次フィルターが実行するストレッチまたは縮小と同じくらい適切である必要があります。

Direct3D ランタイムは、ドライバーの BltDXGI 関数を呼び出す頻度が低くなります。つまり、ランタイムは主にプレゼンテーションをサポートするために BltDXGI を使用するため、ランタイムはフレームごとに 1 回または 2 回以上 BltDXGI を呼び出す必要があります。

ランタイムがプレゼンテーションに対して BltDXGI を呼び出すと、ランタイムは DXGI_DDI_ARG_BLT の Flags メンバーに Present bit-field フラグを設定します。ランタイムは、ビットblt の追加の要件があり、追加の同期が必要になる可能性があることをドライバーに通知する [ビットフィールドの表示 ] フラグを設定します (たとえば、ランタイムは、ディスプレイの個別の部分を処理する 2 つのグラフィックスアダプターを含むコンピューター構成で追加の同期を実行する必要がある場合があります)。 [ビット フィールドの表示] フラグが設定されている場合、ドライバーは、アプリケーションのバックバッファーから DWM の共有サーフェイスへのコピー操作を実行する必要があります。この種類のコピー操作の同期は不正確であるため、成果物の破棄は、ユーザーが経験する最悪の種類の成果物である必要があります。この種類のコピー操作では、可能性のあるアーティファクトがはるかに悪くなるため、ドライバーは最初に変換先のサーフェスに解決してから、結果をインプレースで色変換することで、マルチパスアプローチを使用しないでください。

ドライバーがプライマリサーフェスの作成時にDXGI_DDI_ERR_UNSUPPORTEDを返す (つまり、CreateResource(D3D10) 関数の呼び出しから DXGI_DDI_ERR_UNSUPPORTEDを返す) 場合、D3D10DDIARG_CREATERESOURCE の BindFlags メンバーに D3D10_DDI_BIND_PRESENT フラグを設定し、D3D10DDIARG_CREATERESOURCEの pPrimaryDesc メンバーと共に設定します。が NULL 以外に設定されている場合)、ドライバーはコピー操作中のローテーションもサポートする必要があります。ドライバーが CreateResource(D3D10) 関数の呼び出しからDXGI_DDI_ERR_UNSUPPORTEDを返さない場合、ランタイムは DXGI_DDI_ARG_BLT の Rotate メンバーにDXGI_DDI_MODE_ROTATION_ROTATE90、DXGI_DDI_MODE_ROTATION_ROTATE180、またはDXGI_DDI_MODE_ROTATION_ROTATE270値を渡すことはありません。そのため、この状況では、ドライバーの BltDXGI 関数は回転をサポートするために必要ありません。

ランタイムは、 DXGI_DDI_ARG_BLT の Rotate メンバーの値を設定して、ドライバーがコンテンツをコピー先にコピーする前に、ソースの内容を反時計回りに回転させる度数を示します。回転は 90 度単位で指定します。

注意

ドライバーの BltDXGI 関数が sRGB 形式のコンテンツをソースサーフェイスから sRGB 以外の変換先サーフェスにコピーする場合、ドライバーは sRGB コンテンツを変更せずにコピーする必要があります (つまり、ドライバーは sRGB から線形変換を実行しないでください)。

ソースの制限

BltDXGI 関数は、常にソースサブリソース全体 (一部のサブ四角形領域) を使用してビットblt 操作を実行します。さらに、ソースはD3D10DDIRESOURCE_TEXTURE2D表現です (ユーザーモードディスプレイドライバーの CreateResource(D3D10) 関数の呼び出しでソースが作成されるときに、D3D10DDIARG_CREATERESOURCE の ResourceDimension メンバーで指定されます)。ランタイムが DXGI_DDI_ARG_BLT の Flags メンバーで Resolve ビットフィールドを設定すると、ソースはマルチサンプリングリソースになります。ソースリソースは、D3D10DDIARG_CREATERESOURCE の BindFlags メンバーでD3D10_DDI_BIND_PRESENT フラグが設定されたリソースに制限されます。 ソースの形式 (D3D10DDIARG_CREATERESOURCE の Format メンバーで指定) は、DXGI_FORMAT列挙の次の値によって指定される表示モード形式に制限されます。

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM (下記の注を参照)。
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

注意

ドライバーがソース形式 のDXGI_FORMAT_B8G8R8A8_UNORMをサポートしている場合は、次の制限が適用されます。

ドライバーは、浮動小数点形式からBGRA8888などの整数形式にビットblt 操作を実行する場合、結果にガンマを暗黙的にエンコードする必要があります。
逆に、ドライバーが整数形式から浮動小数点形式へのビットブル演算を実行する場合、結果からガンマエンコードを暗黙的に削除する必要があります。

宛先の制限

変換先は 、D3D10DDIRESOURCE_TEXTURE2D 表現でもあります。変換先の形式も、表示モード形式に制限されます。ターゲットリソースは、レンダーターゲットとしてバインドされているリソースに制限されます (D3D10DDIARG_CREATERESOURCEまたはD3D11DDIARG_CREATERESOURCEの BindFlags メンバーに設定D3D10_DDI_BIND_RENDER_TARGET)。

ステレオバックバッファーの作成

Windows 8以降、ドライバーがステレオバックバッファーを作成する必要がある場合は、CreateResource(D3D10) 関数または CreateResource(D3D11) 関数の pCreateResource パラメーターが指すD3D10DDIARG_CREATERESOURCEまたは D3D11DDIARG_CREATERESOURCE 構造体のメンバーをそれぞれ設定する必要があります。