IDXGIOutputDuplication

IDXGIOutputDuplication インターフェイスは、複製されたデスクトップイメージにアクセスして操作します。

コラボレーションアプリケーションは、IDXGIOutputDuplication を使用してデスクトップイメージにアクセスできます。IDXGIOutputDuplication は、8bpp 以外の DirectX 全画面モードおよび 8bpp 以外の OpenGL 全画面モードにおいて、デスクトップ ウィンドウ マネージャー (DWM) でサポートされます。16 ビットまたは 32 ビットの GDI による非 DWM デスクトップモードはサポートされません。

アプリケーションは、別のスレッドで IDXGIOutputDuplication を使用してデスクトップイメージを受け取り、それを独自の画像処理パイプラインに渡すことができます。アプリケーションは IDXGIOutputDuplication を使用して、次の操作を実行します。

1. 次のデスクトップイメージを取得します。
2. イメージを記述する情報を取得します。
3. イメージに対して操作を実行します。この操作は、アプリケーションがイメージのピクセルデータを読み取れるように、イメージをステージングバッファーにコピーするだけの単純なものにすることもできます。アプリケーションは、IDXGISurface::Map を呼び出した後にピクセルデータを読み取ります。あるいは、この操作をより複雑なものにすることもできます。たとえば、アプリケーションはイメージの更新された領域に対していくつかのピクセルシェーダーを実行し、それらの領域をクライアントへの送信用にエンコードできます。
4. アプリケーションは各デスクトップイメージの処理を終えると、そのイメージを解放し、手順 1 に戻ってこれらの手順を繰り返します。アプリケーションは、デスクトップイメージの処理が完了するまでこれらの手順を繰り返します。

• デスクトップイメージを合成する DWM
• 全画面の DirectX または OpenGL アプリケーション
• 別のデスクトップ (たとえば、ログイン画面の表示に使用されるセキュアデスクトップ) への切り替えを行うアプリケーション

IDXGIOutputDuplication が無効になる状況の例を次に示します。

• デスクトップの切り替え
• モード変更
• DWM のオン/オフの切り替え、または他の全画面アプリケーションへの切り替え

アプリケーションが各デスクトップイメージを処理している間、オペレーティングシステムはすべてのデスクトップイメージの更新を 1 つの更新にまとめて蓄積します。デスクトップの更新の詳細については、「デスクトップイメージデータの更新」を参照してください。

デスクトップイメージは常に DXGI_FORMAT_B8G8R8A8_UNORM 形式です。

IDXGIOutputDuplication インターフェイスは、Windows ストアアプリには存在しません。

複製された出力 (アウトプット) の記述を取得します。この記述は、デスクトップイメージを格納するサーフェスの寸法を指定します。

アプリケーションは IDXGIOutputDuplication インターフェイスを作成した後、GetDesc を呼び出して、デスクトップイメージを格納するサーフェスの寸法を取得します。デスクトップイメージの形式は常に DXGI_FORMAT_B8G8R8A8_UNORM です。

アプリケーションが次のデスクトップイメージを処理する準備ができたことを示します。

AcquireNextFrame は次の値を返します。

• 次のデスクトップイメージを正常に受信した場合は S_OK。
• デスクトップ複製インターフェイスが無効な場合は DXGI_ERROR_ACCESS_LOST。デスクトップ複製インターフェイスは、通常、別の種類のイメージがデスクトップに表示されると無効になります。この状況の例を次に示します。
  • デスクトップの切り替え
  • モード変更
  • DWM のオン/オフの切り替え、または他の全画面アプリケーションへの切り替え
  この状況では、アプリケーションは IDXGIOutputDuplication インターフェイスを解放し、新しいコンテンツ用に新しい IDXGIOutputDuplication を作成する必要があります。
• 次のデスクトップフレームが利用可能になる前にタイムアウト間隔が経過した場合は DXGI_ERROR_WAIT_TIMEOUT。
• アプリケーションが前のフレームを解放せずに AcquireNextFrame を呼び出した場合は DXGI_ERROR_INVALID_CALL。
• AcquireNextFrame のいずれかのパラメーターが正しくない場合 (たとえば pFrameInfo が NULL の場合) は E_INVALIDARG。
• その他、DXGI_ERROR トピックで説明されているエラーコードが返される場合があります。

AcquireNextFrame が正常に返ると、呼び出し元のアプリケーションは、AcquireNextFrame が ppDesktopResource の変数に返すデスクトップイメージにアクセスできます。 呼び出し元が TimeoutInMilliseconds パラメーターにゼロのタイムアウト間隔を指定した場合、AcquireNextFrame は新しいデスクトップイメージが利用可能かどうかを確認し、直ちに制御を返して、その結果を戻り値で示します。呼び出し元が TimeoutInMilliseconds パラメーターに INFINITE のタイムアウト間隔を指定した場合、タイムアウト間隔は決して経過しません。

現在のデスクトップフレームのダーティ矩形に関する情報を取得します。

GetFrameDirtyRects は次の値を返します。

• ダーティ矩形に関する情報を正常に取得した場合は S_OK。
• デスクトップ複製インターフェイスが無効な場合は DXGI_ERROR_ACCESS_LOST。デスクトップ複製インターフェイスは、通常、別の種類のイメージがデスクトップに表示されると無効になります。この状況の例を次に示します。
  • デスクトップの切り替え
  • モード変更
  • DWM のオン/オフの切り替え、または他の全画面アプリケーションへの切り替え
  この状況では、アプリケーションは IDXGIOutputDuplication インターフェイスを解放し、新しいコンテンツ用に新しい IDXGIOutputDuplication を作成する必要があります。
• 呼び出し元のアプリケーションが指定したバッファーが十分な大きさでなかった場合は DXGI_ERROR_MORE_DATA。
• アプリケーションがデスクトップイメージを所有せずに GetFrameDirtyRects を呼び出した場合は DXGI_ERROR_INVALID_CALL。
• GetFrameDirtyRects のいずれかのパラメーターが正しくない場合 (たとえば pDirtyRectsBuffer が NULL の場合) は E_INVALIDARG。
• その他、DXGI_ERROR トピックで説明されているエラーコードが返される場合があります。

GetFrameDirtyRects は、pDirtyRectsBufferSizeRequired の変数にサイズ値を格納します。この値は、GetFrameDirtyRects がダーティ領域に関する情報を格納するために必要なバイト数を指定します。この値は、pDirtyRectsBuffer に渡す今後のバッファーに割り当てるメモリ量を決定するために、次の状況で使用できます。

• GetFrameDirtyRects がバッファーの大きさが十分でないために DXGI_ERROR_MORE_DATA で失敗する場合。
• GetFrameDirtyRects に必要以上に大きなバッファーを渡した場合。pDirtyRectsBufferSizeRequired に返されるサイズ値は、呼び出し元が割り当てて DirtyRectsBufferSize パラメーターに指定したバッファー領域に対して、実際に使用されたバッファー領域の大きさを呼び出し元に通知します。

バッファーには、現在のフレームのダーティ RECT のリストが含まれます。

現在のデスクトップフレームの移動された矩形に関する情報を取得します。

GetFrameMoveRects は次の値を返します。

• 移動された矩形に関する情報を正常に取得した場合は S_OK。
• デスクトップ複製インターフェイスが無効な場合は DXGI_ERROR_ACCESS_LOST。デスクトップ複製インターフェイスは、通常、別の種類のイメージがデスクトップに表示されると無効になります。この状況の例を次に示します。
  • デスクトップの切り替え
  • モード変更
  • DWM のオン/オフの切り替え、または他の全画面アプリケーションへの切り替え
  この状況では、アプリケーションは IDXGIOutputDuplication インターフェイスを解放し、新しいコンテンツ用に新しい IDXGIOutputDuplication を作成する必要があります。
• 呼び出し元のアプリケーションが指定したバッファーが十分な大きさでない場合は DXGI_ERROR_MORE_DATA。
• アプリケーションがデスクトップイメージを所有せずに GetFrameMoveRects を呼び出した場合は DXGI_ERROR_INVALID_CALL。
• GetFrameMoveRects のいずれかのパラメーターが正しくない場合 (たとえば pMoveRectBuffer が NULL の場合) は E_INVALIDARG。
• その他、DXGI_ERROR トピックで説明されているエラーコードが返される場合があります。

GetFrameMoveRects は、pMoveRectsBufferSizeRequired の変数にサイズ値を格納します。この値は、GetFrameMoveRects が移動された領域に関する情報を格納するために必要なバイト数を指定します。この値は、pMoveRectBuffer に渡す今後のバッファーに割り当てるメモリ量を決定するために、次の状況で使用できます。

• GetFrameMoveRects がバッファーの大きさが十分でないために DXGI_ERROR_MORE_DATA で失敗する場合。
• GetFrameMoveRects に必要以上に大きなバッファーを渡した場合。pMoveRectsBufferSizeRequired に返されるサイズ値は、呼び出し元が割り当てて MoveRectsBufferSize パラメーターに指定したバッファー領域に対して、実際に使用されたバッファー領域の大きさを呼び出し元に通知します。

バッファーには、現在のフレームの移動 RECT のリストが含まれます。

現在のデスクトップフレームの新しいポインター形状に関する情報を取得します。

GetFramePointerShape は次の値を返します。

• 新しいポインター形状に関する情報を正常に取得した場合は S_OK。
• デスクトップ複製インターフェイスが無効な場合は DXGI_ERROR_ACCESS_LOST。デスクトップ複製インターフェイスは、通常、別の種類のイメージがデスクトップに表示されると無効になります。この状況の例を次に示します。
  • デスクトップの切り替え
  • モード変更
  • DWM のオン/オフの切り替え、または他の全画面アプリケーションへの切り替え
  この状況では、アプリケーションは IDXGIOutputDuplication インターフェイスを解放し、新しいコンテンツ用に新しい IDXGIOutputDuplication を作成する必要があります。
• 呼び出し元のアプリケーションが指定したバッファーが十分な大きさでなかった場合は DXGI_ERROR_MORE_DATA。
• アプリケーションがデスクトップイメージを所有せずに GetFramePointerShape を呼び出した場合は DXGI_ERROR_INVALID_CALL。
• GetFramePointerShape のいずれかのパラメーターが正しくない場合 (たとえば pPointerShapeInfo が NULL の場合) は E_INVALIDARG。
• その他、DXGI_ERROR トピックで説明されているエラーコードが返される場合があります。

GetFramePointerShape は、pPointerShapeBufferSizeRequired の変数にサイズ値を格納します。この値は、pPointerShapeBufferSizeRequired が新しいポインター形状のピクセルデータを格納するために必要なバイト数を指定します。この値は、pPointerShapeBuffer に渡す今後のバッファーに割り当てるメモリ量を決定するために、次の状況で使用できます。

• GetFramePointerShape がバッファーの大きさが十分でないために DXGI_ERROR_MORE_DATA で失敗する場合。
• GetFramePointerShape に必要以上に大きなバッファーを渡した場合。pPointerShapeBufferSizeRequired に返されるサイズ値は、呼び出し元が割り当てて PointerShapeBufferSize パラメーターに指定したバッファー領域に対して、実際に使用されたバッファー領域の大きさを呼び出し元に通知します。

デスクトップイメージが既にシステムメモリ内にある場合に、そのデスクトップイメージへの効率的なアクセスを CPU に提供します。

MapDesktopSurface は次の値を返します。

• サーフェスデータを正常に取得した場合は S_OK。
• デスクトップ複製インターフェイスが無効な場合は DXGI_ERROR_ACCESS_LOST。デスクトップ複製インターフェイスは、通常、別の種類のイメージがデスクトップに表示されると無効になります。この状況の例を次に示します。
  • デスクトップの切り替え
  • モード変更
  • DWM のオン/オフの切り替え、または他の全画面アプリケーションへの切り替え
  この状況では、アプリケーションは IDXGIOutputDuplication インターフェイスを解放し、新しいコンテンツ用に新しい IDXGIOutputDuplication を作成する必要があります。
• アプリケーションがデスクトップイメージに対して未解決のマップを既に持っている場合は DXGI_ERROR_INVALID_CALL。アプリケーションは、MapDesktopSurface を再度呼び出す前に UnMapDesktopSurface を呼び出す必要があります。また、MapDesktopSurface を呼び出したときにアプリケーションがデスクトップイメージを所有していなかった場合も DXGI_ERROR_INVALID_CALL が返されます。
• デスクトップイメージがシステムメモリ内にない場合は DXGI_ERROR_UNSUPPORTED。この状況では、アプリケーションはまずイメージをステージングサーフェスに転送し、その後 IDXGISurface::Map メソッドを呼び出してイメージをロックする必要があります。
• pLockedRect パラメーターが正しくない場合 (たとえば pLockedRect が NULL の場合) は E_INVALIDARG。
• その他、DXGI_ERROR トピックで説明されているエラーコードが返される場合があります。

DXGI_OUTDUPL_DESC 構造体の DesktopImageInSystemMemory メンバーが TRUE に設定されている場合、MapDesktopSurface を正常に呼び出すことができます。DesktopImageInSystemMemory が FALSE の場合、MapDesktopSurface は DXGI_ERROR_UNSUPPORTED を返します。DXGI_OUTDUPL_DESC 構造体を取得するには、IDXGIOutputDuplication::GetDesc を呼び出します。

IDXGIOutputDuplication::MapDesktopSurface を使用して取得したデスクトップイメージへのポインターを無効化します。

UnMapDesktopSurface は次の値を返します。

• 正常に完了した場合は S_OK。
• アプリケーションが IDXGIOutputDuplication::MapDesktopSurface を呼び出してデスクトップサーフェスをマップしていなかった場合は DXGI_ERROR_INVALID_CALL。
• その他、DXGI_ERROR トピックで説明されているエラーコードが返される場合があります。

アプリケーションがフレームの処理を終了したことを示します。

ReleaseFrame は次の値を返します。

• 正常に完了した場合は S_OK。
• アプリケーションが既にフレームを解放している場合は DXGI_ERROR_INVALID_CALL。
• デスクトップ複製インターフェイスが無効な場合は DXGI_ERROR_ACCESS_LOST。デスクトップ複製インターフェイスは、通常、別の種類のイメージがデスクトップに表示されると無効になります。この状況の例を次に示します。
  • デスクトップの切り替え
  • モード変更
  • DWM のオン/オフの切り替え、または他の全画面アプリケーションへの切り替え
  この状況では、アプリケーションは IDXGIOutputDuplication インターフェイスを解放し、新しいコンテンツ用に新しい IDXGIOutputDuplication を作成する必要があります。
• その他、DXGI_ERROR トピックで説明されているエラーコードが返される場合があります。

アプリケーションは、次のフレームを取得する前に、フレームを解放する必要があります。フレームを解放すると、デスクトップビットマップを格納するサーフェスは無効になり、そのサーフェスを DirectX グラフィックス操作で使用できなくなります。

パフォーマンス上の理由から、次のフレームを取得する IDXGIOutputDuplication::AcquireNextFrame メソッドを呼び出す直前にフレームを解放することをお勧めします。クライアントがフレームを所有していない場合、オペレーティングシステムはすべてのデスクトップの更新をサーフェスにコピーします。これにより、オペレーティングシステムが発生する各フレームで同じ領域を更新すると、GPU サイクルが無駄になる可能性があります。クライアントがフレームを取得すると、クライアントはこの領域に対する最終的な更新のみを認識します。そのため、以前のフレームでの重複する更新はすべて無駄になります。クライアントがフレームを取得すると、クライアントはサーフェスを所有するため、オペレーティングシステムは更新された領域のみを追跡でき、デスクトップの更新をサーフェスにコピーできません。この動作のため、現在のフレームを解放する呼び出しと次のフレームを取得する呼び出しの間の時間を最小限に抑えることをお勧めします。