PFND3DDDI_LOCKCB コールバック関数 (d3dumddi.h)

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

pfnLockCb 関数は、割り当てをロックし、ディスプレイミニポートドライバーまたはビデオメモリマネージャーから割り当てへのポインターを取得します。

構文

PFND3DDDI_LOCKCB Pfnd3dddiLockcb;

HRESULT Pfnd3dddiLockcb(
  HANDLE hDevice,
  D3DDDICB_LOCK *unnamedParam2
)
{...}

パラメーター

hDevice

ディスプレイデバイスへのハンドル (グラフィックスコンテキスト)。

unnamedParam2

pData [in, out]

ロックする割り当てを記述する D3DDDICB_LOCK 構造体へのポインター。

戻り値

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

リターンコード	説明
S_OK	割り当てが正常にロックされました。
D3DERR_NOTAVAILABLE	絞りは使用できませんでした。
D3DERR_WASSTILLDRAWING	割り当てはレンダリングに引き続き使用されていました。
D3DDDIERR_CANTEVICTPINNEDALLOCATION	割り当てをロックできませんでした。これは、絞りがデスワイズリングされなくなり、割り当てがピン留めされたために割り当てを削除できなかったためです。
E_OUTOFMEMORY	メモリ不足のため pfnLockCb を完了できませんでした (この状況は、システムが極端に低いメモリ状態にあり、ページの配列を割り当てるのに十分な領域がない場合に発生します)。
E_INVALIDARG	パラメーターが検証され、正しくないと判断されました。

D3DDDIERR_DEVICEREMOVED	pfnLockCb は、プラグアンドプレイ (PnP) 停止またはタイムアウト検出と回復 (TDR) イベントが発生したため、ビデオメモリマネージャーとディスプレイミニポートドライバーが適切なアクションを実行できませんでした。 pfnLockCb (通常は Lock 関数または ResourceMap 関数) を呼び出したユーザーモードのディスプレイドライバー関数は、このエラーコードを Direct3D ランタイムに返す必要があります。 Direct3D バージョン 9 注: エラーコードの返し方の詳細については、「ランタイム関数から受信したエラーコードの返し」を参照してください。 Direct3D バージョン 10 および 11 注: ドライバー関数が値を返さない場合 (つまり、戻り値のパラメーター型に VOID がある場合)、ドライバー関数は pfnSetErrorCb 関数を呼び出してランタイムにエラーコードを返します。エラーコードの処理の詳細については、「エラーの処理」を参照してください。

この関数は、他の HRESULT 値も返す場合があります。

注釈

ユーザーモードディスプレイドライバーは、Microsoft Direct3D ランタイムの pfnLockCb 関数を呼び出して割り当てをロックし、ディスプレイミニポートドライバーまたはビデオメモリマネージャーから割り当てへのポインターを取得できます。通常、ユーザーモードディスプレイドライバーは、Lock 関数または ResourceMap 関数 (または DynamicIABufferMapDiscard などの ResourceMap のその他のバリエーション) の呼び出しに応答して pfnLockCb を呼び出して、リソースまたはリソース内のサーフェスをロックします。 Lock 呼び出しまたは ResourceMap 呼び出しから戻る前に、ユーザーモードのディスプレイドライバーは、最初にリソースまたはサーフェスを適切な割り当てにマップしてから、pfnLockCb を呼び出して割り当てをロックする必要があります。割り当ては、次のロックのために、読み取りまたは書き込み前にロックする必要があります。

割り当ての仮想アドレス範囲が、ロック期間中は変更されず、有効で、読み取り可能であり、書き込み可能であることを保証します。ビデオメモリマネージャーは、この保証を提供します。
割り当ての読み取り操作と書き込み操作を、割り当てのグラフィックスハードウェアアクセスと同期する方法を提供します。ビデオメモリマネージャーとディスプレイミニポートドライバーは、同期を実行します。

Direct3D バージョン 9 注:

通常、ユーザーモードディスプレイドライバーは、Lock 関数と Unlock 関数の呼び出しごとに対応する pfnLockCb 関数と pfnUnlockCb 関数を呼び出します。ただし、リソースの作成時に、D3DDDIARG_CREATERESOURCE 構造体の Flags メンバーに動的ビットフィールドフラグが設定されたリソースがドライバーによって処理される場合を除きます。ランタイムは、多くの場合、D3DDDIARG_LOCK構造体の Flags メンバーに NoOverwrite ビットフィールドフラグを設定して、ドライバーがこれらの種類のリソースをロックすることを要求します。このようなリソース内のデータは ( NoOverwrite で示されているように) 変更しないでください。そのため、ロック要求ごとに pfnLockCb を 呼び出すと、処理時間が過剰になります。ロック要求ごとに pfnLockCb を呼び出さないように、ドライバーは、ロック関数がNoOverwrite ビットフィールドフラグを設定して呼び出されたときに、D3DDDIARG_LOCK の pSurfData メンバーで返される仮想メモリポインターをキャッシュできます。ただし、Lock 関数が呼び出されるたびに、ドライバーは引き続き pfnLockCb を呼び出すことができます、破棄ビットフィールドフラグが設定されているか、フラグが設定されません。

Direct3D バージョン 10 および 11 注:

ユーザーモードのディスプレイドライバーは通常、その ResourceMap 関数と ResourceUnmap 関数 (またはこれらの関数の他のバリエーション) へのすべての呼び出しに対応する pfnLockCb 関数と pfnUnlockCb 関数を呼び出します。これは、ドライバーがリソースの作成時にD3D10DDIARG_CREATERESOURCEまたはD3D11DDIARG_CREATERESOURCE構造体の Usage メンバーでD3D10_DDI_USAGE_DYNAMIC値が設定されたリソースを処理する場合は発生しません。ランタイムは、多くの場合、ResourceMap の呼び出しで DDIMap パラメーターにD3D10_DDI_MAP_WRITE_NOOVERWRITE値を渡すことによって、ドライバーがこれらの種類のリソースをロックするように要求します。このようなリソース内のデータは (D3D10_DDI_MAP_WRITE_NOOVERWRITEで示されているように) 変更しないでください。そのため、ロック要求ごとに pfnLockCb を 呼び出すと、処理時間が過剰になります。ロック要求ごとに pfnLockCb を呼び出さないように、ドライバーは、ResourceMap 関数が D3D10_DDI_MAP_WRITE_NOOVERWRITE で呼び出されたときに pMappedSubResource パラメーターで返される仮想メモリポインターをキャッシュできます。ただし、D3D10_DDI_MAP_WRITE_DISCARD値または 0 を DDIMap パラメーターに渡して ResourceMap 関数が呼び出されるたびに、ドライバーは pfnLockCb を引き続き呼び出すことができます。

アプリケーションは仮想メモリポインターに関連付けられているリソースに対して未処理のロックを保持しませんが、通常、ドライバーは pfnRenderCb 関数を呼び出す前に pfnUnlockCb 関数を呼び出して仮想メモリポインターのキャッシュを解除します。ロックがキャッシュされていない場合、またはアプリケーションにリソースがまだロックされているためにロックを解除できない場合、ハードウェアはロックされた割り当てからレンダリングされる可能性があります。割り当てがローカルビデオメモリ内にある場合、ビデオメモリマネージャーはこの操作モードをサポートできません。そのため、メモリマネージャーがこの状況を検出すると、メモリマネージャーによってシステムまたは AGP メモリへの割り当てが削除されます。システムまたは AGP メモリセグメントで割り当てがサポートされていない場合、メモリマネージャーは、D3DDDIERR_CANTRENDERLOCKEDALLOCATIONを使用して pfnRenderCb の呼び出しを失敗します。したがって、動的ビットフィールドフラグが D3DDDIARG_CREATERESOURCE の Flags メンバー (または D3D10DDIARG_CREATERESOURCE または D3D11DDIARG_CREATERESOURCE の Usage メンバーで設定されている D3D10_DDI_USAGE_DYNAMIC) で設定されているリソースの作成に応じて割り当てられる頂点バッファーとインデックスバッファーの割り当ては、システムセグメントまたは AGP セグメントでサポートする必要があります。

pfnLockCb の呼び出しで D3DDDICB_LOCK の Flags メンバーでビットフィールドフラグを破棄すると、ビデオメモリマネージャーによって、ロックされている割り当ての新しいインスタンスが作成されます。ビデオメモリマネージャーは、 D3DDDICB_LOCKの hAllocation メンバーのユーザーモードディスプレイドライバーに新しいハンドルを返すことによって、新しいインスタンスを表します。

メモディスプレイミニポートドライバーの DxgkDdiCreateAllocation 関数は、割り当ての新しいインスタンスが作成されるときに呼び出されません。インスタンスは、複数の異なる場所に同時にページングされる割り当てとしてディスプレイミニポートドライバーに表示されます。

ビデオメモリマネージャーは、新しいインスタンスを作成したり、割り当ての既存のインスタンスを再利用したりできないため、ビットフィールドの破棄フラグが設定されているロックが失敗する可能性があります。このエラーが発生した場合、ユーザーモードのディスプレイドライバーは pfnRenderCb 関数を呼び出して、現在のコマンドバッファーをカーネルにフラッシュする必要があります。このコマンドバッファーのフラッシュにより、破棄ビットフィールドフラグを使用してロックできなかった割り当ての一部のインスタンスが廃止される可能性があります。

コマンドバッファーをフラッシュした後、ユーザーモードのディスプレイドライバーは 、Discard と NoExistingReference の両方のビットフィールドフラグを使用して、サーフェスをもう一度ロックする必要があります。 NoExistingReference ビットフィールドフラグは、ドライバーが現在、そのコマンドバッファーでキューにロックされている割り当てのインスタンスへの参照がないことをビデオメモリマネージャーに示します。その後、ビデオメモリマネージャーは、割り当ての任意のインスタンスを再利用して、現在のインスタンスを含むロックを処理できます。

ビットフィールドの破棄フラグが設定されている pfnLockCb を呼び出した後、ユーザーモードのディスプレイドライバーは、D3DDDICB_LOCKの hAllocation メンバーの更新されたハンドル値に対して常にチェックする必要があります。新しい割り当てハンドルが指定されている場合、ユーザーモードのディスプレイドライバーは、新しい割り当てハンドルを参照するように内部データ構造を更新する必要があります。また、ユーザーモードのディスプレイドライバーは、ロックされた割り当てベースアドレスの再プログラミングされたバージョンを現在のコマンドバッファーに追加する必要があります (割り当てインスタンスには異なるベースアドレスが含まれているため)。ビデオメモリマネージャーは、ドライバーによって使用される割り当てインスタンスの使用を検証し、割り当てインスタンスを誤って使用する DMA バッファーを拒否します (つまり、割り当てインスタンスを誤って使用すると、pfnPresentCb と pfnRenderCb の呼び出しは失敗します)。ドライバーが割り当ての特定のインスタンスを参照すると、ドライバーは同じ割り当ての以前のインスタンスを参照できなくなります。たとえば、コマンドバッファーが割り当て A を使用し、現在インスタンス A0 と A1 を使用している場合、A1 が使用されるとすぐに (つまり、パッチの場所の一覧に表示されます)、A0 は無効になります。ディスプレイミニポートドライバーは、A0 と A1 の両方を参照するパッチの場所の一覧を生成できます。ただし、参照は順序付けする必要があります (つまり、最初に A0 を使用できます)。A0 は、A2 を使用すると無効になります。A1 は、A2 を使用すると無効になります。など)。

ディスプレイミニポートドライバーが実際に送信、DMA を介して、またはグラフィックスハードウェアにこれらの割り当てを非同期的に転送する処理中である可能性があるため、ユーザーモードのディスプレイドライバーは、メモリが事前に割り当てられていない場合でも、システムメモリ割り当てのために pfnLockCb を呼び出す可能性があります。したがって、アプリケーションがサーフェスへの書き込みを許可される前に、必要に応じてロックをブロックできるように、ディスプレイミニポートドライバーとビデオメモリマネージャーに通知する必要があります。

ユーザーモードのディスプレイドライバーは、割り当てのサブ領域をロックすることもできます。この種類のロックは、一般に、ハードウェアの絞りを読み取ったり直線化したりする場合に必要ありません。この状況では、ユーザーモードのディスプレイドライバーは、ポインターをオフセットすることによって、割り当て全体のロックをサブ領域に変換できるためです。ただし、D3DERR_NOTAVAILABLEを使用して絞りが使用できないことを示すために pfnLockCb が失敗した場合、メモリマネージャーは、ビデオメモリの内容をコピーするようにユーザーモードのディスプレイドライバーに要求します。ユーザーモードディスプレイドライバは、ビデオメモリの内容を別のメモリ領域にコピーするときに、ビデオメモリの内容をスウィズルまたはリニアライズします。この状況では、ユーザーモードのディスプレイドライバーは、大量の割り当てで小さなサブ領域をロックするときに大量のコピーを保存するためにコピーするページの一覧を指定できます。ユーザーモードディスプレイドライバーがD3DDDICB_LOCK構造体のFlags メンバーで LockEntire ビットフィールドフラグを設定せず、D3DDDICB_LOCKの pPages メンバーにページリストを指定しなかった場合、メモリマネージャーは pfnLockCb の呼び出しに失敗し、D3DERR_NOTAVAILABLEに注意してください。ユーザーモードディスプレイドライバーで LockEntire ビットフィールドフラグを設定する場合は、D3DDDICB_LOCKの NumPages メンバーと pPages メンバーをそれぞれ 0 と NULL に設定する必要があります。永続的なバッキングストアで作成された割り当てをロックする場合、ユーザーモードのディスプレイドライバーは常に pPages のページリストを指定する必要があります。この場合、メモリマネージャーはページリストを使用して特定のページのみをダーティとしてマークし、レンダリングに使用するときにバッキングストアから割り当て全体をコピーする必要はありません。

ユーザーモードディスプレイドライバーは 、pfnLockCb を呼び出して、1 つの割り当てに対して複数のスウィズリング範囲を取得できます (たとえば、MIP レベルごとに 1 つのスウィズリング範囲)。ドライバーがいずれかの範囲を取得できない場合、Direct3D ランタイムは、ロック (すべての MIP レベル) を処理する割り当て全体を削除し、すべてのスウィズリング範囲を再利用します。

ユーザーモードディスプレイドライバーは、割り当てにスウィズリング範囲を割り当てることを要求すると、ドライバーは実質的に割り当てのまぶしいビットへのアクセスを要求します。このような要求の場合、ビデオメモリマネージャーは、メモリセグメントへの割り当て内のページと、メモリセグメントへの割り当てまたは割り当て内のページにアクセスするスウィズル範囲を設定し、システムメモリへの割り当てを削除します。システムメモリへの割り当てをドライバーが割り当て解除するように要求します。システムメモリに割り当てられなかった割り当ては、GPU が再び割り当てを使用する前に (ビデオメモリにページングされることによって) 再び読み込まれます。その結果、ドライバーは、スウィズリング範囲を取得するときに ( DonotWait ビットフィールドフラグを設定することによって) 上書きなしの種類のロックを要求できません。同様に、ドライバーは、(DMA バッファーが拒否されるため) GPU に送信される DMA バッファーでこのような方法で割り当てロックを参照することはできません。

ユーザーモードのディスプレイドライバーは、スウィズルされた形式で割り当てのビットにアクセスする必要がある場合、スウィズル範囲を取得せずにスウィズル割り当てをロックする可能性があります。この状況では、ビデオメモリマネージャーは、割り当てのスウィズルビットへのポインターをドライバーに提供します。ただし、割り当て解除されたビットの要求が未処理である間は、ドライバーは割り当てのスウィズルされたビットへのポインターを要求できません (つまり、取得されたスウィズリング範囲で現在、割り当てに対するロックが保留中です)。

ユーザーモードのディスプレイドライバーは、次の状況で pfnLockCb 呼び出しのD3DDDICB_LOCKの Flags メンバーのビットフィールドフラグを破棄する必要があります。

Direct3D ランタイムが、ユーザーモードディスプレイドライバーの Lock 関数の呼び出しで、D3DDDIARG_LOCK構造体の Flags メンバーのビットフィールドフラグを破棄する
ランタイムがドライバーの ResourceMap 関数の呼び出しで DDIMap パラメーターにD3D10_DDI_MAP_WRITE_DISCARD値を渡す場合

ビットフィールドの破棄フラグを設定すると、メモリマネージャーは割り当ての名前を変更するか、割り当てがアイドル状態になるまでアプリケーションスレッドを停止させる必要があるかどうかを判断します。割り当ての名前変更の詳細については、「割り当ての名前変更の要求」を参照してください。ドライバーは、独自の名前変更のサポートまたはメモリマネージャーの名前変更のサポートを使用できます。独自の名前変更のサポートを使用するために、ドライバーは、ビットフィールドの破棄フラグが設定された Lock 呼び出しに応答して、またはD3D10_DDI_MAP_WRITE_DISCARD値が設定された ResourceMap 呼び出しに応答して、DonotWait ビットフィールドフラグを設定します。 DonotWait ビットフィールドフラグを設定すると、グラフィックスハードウェアがまだ割り当てを使用している場合、メモリマネージャーは D3DERR_WASSTILLDRAWING を使用して pfnLockCb の呼び出しに失敗します。このようなエラーは、割り当ての名前を変更または複数バッファーにユーザーモードのディスプレイドライバーを示します。

メモ[ビットフィールドの破棄] フラグも設定されている場合、DonotWait ビットフィールドフラグはメモリマネージャーに影響しません。

グラフィックスハードウェアが割り当てを使用しているかどうかをメモリマネージャーがチェックする必要がない場合、ユーザーモードのディスプレイドライバーは、D3DDDICB_LOCK の Flags メンバーで IgnoreSync ビットフィールドフラグを設定する必要があります。その後、ユーザーモードディスプレイドライバーは、割り当てへのアクセスを適切に同期する必要があります。 DonotWait ビットフィールドフラグが IgnoreSync ビットフィールドフラグと共に指定されていない場合、メモリマネージャーは IgnoreSync ビットフィールドフラグを無視します。

メモ[ビットフィールドの破棄] フラグも設定されている場合、IgnoreSync ビットフィールドフラグはメモリマネージャーに影響しません。

例

次のコード例は、pfnLockCb の呼び出しでビットフィールドフラグを破棄する方法を示しています。

HRESULT hr;
D3DDDICB_LOCK LockData;
LockData.hAllocation = AllocationToLock;
LockData.Flags.Discard = TRUE;
hr = pfnLockCb(&LockData)
if (FAILED(hr)) {
    FlushAccumulatedCommandBufferToKernel();
    LockData.Flags.Discard = TRUE;
    LockData.Flags.NoExistingReference = TRUE;
    hr = pfnLockCb(&LockData);
    if (FAILED(hr)) {
        // Fails the lock to the application
    }
}
UpdateAllocationHandleInUMDDataStructure(LockData.hAllocation);
ProgramSurfaceBaseAddressInCurrentCommandBuffer(LockData.hAllocation);

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降のバージョンの Windows オペレーティングシステムで使用できます。
対象プラットフォーム	デスクトップ
Header	d3dumddi.h (D3dumddi.h を含む)