IDCompositionSurface

ビジュアルツリー内で合成のためにビジュアルへ関連付けできる物理ビットマップを表します。このインターフェイスは、ビットマップの内容を更新するためにも使用できます。

この Microsoft DirectComposition サーフェスオブジェクトへの描画を開始します。

型: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドを使用すると、アプリケーションは DirectComposition サーフェスオブジェクトの内容を増分的に更新できます。アプリケーションは次の手順に従う必要があります。

1. BeginDraw を呼び出して増分更新を開始します。
2. 取得したサーフェスをレンダーターゲットとして使用し、取得したオフセットの位置に更新後の内容を描画します。
3. IDCompositionSurface::EndDraw メソッドを呼び出して更新を完了します。

このメソッドが返す更新オブジェクトは、iid パラメーターの値と DirectComposition サーフェスオブジェクトの作成方法に応じて、Direct2D デバイスコンテキストまたは DXGI サーフェスのいずれかになります。iid パラメーターが __uuidof(ID2D1DeviceContext) の場合、返されるオブジェクトは DirectComposition サーフェスが既にレンダーターゲットとして選択されている Direct2D デバイスコンテキストです。それ以外の場合は、アプリケーションがレンダーターゲットとして使用できる DXGI サーフェスです。いずれの場合も、返されるオブジェクトは、アプリケーションが DCompositionCreateDevice2 関数または IDCompositionDevice2::CreateSurfaceFactory メソッドに渡した Direct2D デバイスまたは DXGI デバイスに関連付けられます。

iid パラメーターに __uuidof(ID2D1DeviceContext) を指定できるのは、DirectComposition サーフェスオブジェクトが、Direct2D デバイスに関連付けて作成された DirectComposition デバイスまたはサーフェスファクトリから作成された場合のみです。具体的には、アプリケーションは DCompositionCreateDevice2 関数または IDCompositionDevice2::CreateSurfaceFactory メソッドを、renderingDevice パラメーターに Direct2D デバイスを指定して呼び出している必要があります。DirectComposition サーフェスが Direct2D デバイスに関連付けられていないサーフェスファクトリ経由で作成された場合、または IDCompositionDevice2 インターフェイスから直接作成され、そのデバイスが Direct2D デバイスに直接関連付けられていない場合、iid パラメーターに __uuidof(ID2D1DeviceContext) を渡すと、このメソッドは E_INVALIDARG を返します。

更新オブジェクトとして Direct2D デバイスコンテキストを正常に取得した場合、アプリケーションは返された Direct2D デバイスコンテキストに対して ID2D1DeviceContext::BeginDraw メソッドや ID2D1DeviceContext::EndDraw メソッドを呼び出さないでください。

取得されるオフセットは、要求した更新矩形の左上隅と必ずしも一致しません。アプリケーションは、入力した矩形と同じ幅と高さを持つ矩形内に、指定されたオフセットの位置で描画するようにレンダリングプリミティブを変換する必要があります。この矩形の外側に描画しないでください。

updateRectangle パラメーターが NULL の場合、サーフェス全体が更新されます。その場合でも取得されるオフセットが (0,0) になるとは限らないため、アプリケーションはレンダリングプリミティブを適切に変換する必要があります。

サーフェスが仮想サーフェスでない場合、特定の非仮想サーフェスに対してこのメソッドを初めて呼び出すときは、更新矩形がサーフェス全体を覆う必要があります。要求する更新矩形にサーフェス全体を指定するか、updateRectangle パラメーターに NULL を指定します。仮想サーフェスの場合は、最初の呼び出しでサーフェスの任意の部分矩形を指定できます。

このメソッドの呼び出しごとに updateObject として異なるオブジェクトが取得される可能性があるため、アプリケーションは取得したサーフェスポインターをキャッシュしないでください。描画が終わり次第、取得したポインターを解放してください。

取得したサーフェス矩形には、ビットマップの以前の内容は含まれません。アプリケーションは、まずレンダーターゲットをクリアするか、更新矩形を完全に覆うだけのレンダリングプリミティブを発行することで、更新矩形内のすべてのピクセルを更新する必要があります。更新サーフェスの初期内容は未定義であるため、すべてのピクセルを更新しないと動作は未定義になります。

同時に更新できる DirectComposition サーフェスは 1 つだけです。アプリケーションは、別のサーフェスへの描画を開始または再開する前に、一方のサーフェスの描画を中断する必要があります。同一のサーフェスに対して、または同じ DirectComposition デバイスに属する別のサーフェスに対して、間に IDCompositionSurface::EndDraw の呼び出しを挟まずに BeginDraw を 2 回呼び出すと、2 回目の呼び出しは失敗します。EndDraw を呼び出さずに IDCompositionDevice2::Commit を呼び出した場合、更新は保留状態のままになります。更新は、アプリケーションが EndDraw を呼び出し、その後 IDCompositionDevice2::Commit メソッドを呼び出したときにのみ有効になります。

この Microsoft DirectComposition サーフェスオブジェクトへの描画の終了を示します。

型: HRESULT

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードには DCOMPOSITION_ERROR_SURFACE_NOT_BEING_RENDERED が含まれることがあります。

このメソッドは、直前の IDCompositionSurface::BeginDraw メソッドの呼び出しによって開始された更新を完了します。このメソッドから制御が戻った後、アプリケーションは同じサーフェスオブジェクトまたは別のサーフェスオブジェクトに対して次の更新を開始できます。

保留中の更新があるサーフェスに対して IDCompositionSurface::EndDraw を呼び出す前に IDCompositionDevice2::Commit を呼び出した場合、その更新はその Commit の呼び出しでは処理されません。更新が画面に反映されるのは、アプリケーションが IDCompositionSurface::EndDraw を呼び出し、続いて IDCompositionDevice2::Commit メソッドを呼び出した後です。

この Microsoft DirectComposition サーフェスオブジェクトへの描画を中断します。

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードには DCOMPOSITION_ERROR_SURFACE_BEING_RENDERED や DCOMPOSITION_ERROR_SURFACE_NOT_BEING_RENDERED が含まれることがあります。

同時に描画のために開くことができるサーフェスは 1 つだけであるため、SuspendDraw を呼び出すことで、別のサーフェスに対して IDCompositionSurface::BeginDraw を呼び出せるようになります。このサーフェスへの描画は、IDCompositionSurface::ResumeDraw を呼び出すことで再開できます。

この Microsoft DirectComposition サーフェスオブジェクトへの描画を再開します。

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードには DCOMPOSITION_ERROR_SURFACE_BEING_RENDERED や DCOMPOSITION_ERROR_SURFACE_NOT_BEING_RENDERED が含まれることがあります。

このメソッドは、アクティブで中断されていない描画を行っている他のサーフェスが存在しない限り、サーフェスの更新を続行できるようにします。

Microsoft DirectComposition 論理サーフェスの矩形領域をスクロールします。

関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。エラーコードの一覧については、DirectComposition Error Codes を参照してください。

このメソッドを使用すると、アプリケーションは DirectComposition サーフェスオブジェクトの部分矩形を blt/コピーできます。これにより、既に用意されている内容を再レンダリングせずに済みます。

scrollRect 矩形はサーフェスの境界内に収まっている必要があります。scrollRect 矩形がサーフェスの境界を超える場合、このメソッドは失敗します。

スクロール操作でコピーされるビット (転送元) は、scrollRect と clipRect の矩形の交差部分によって定義されます。

画面に表示されるビット (転送先) は、オフセットを適用した転送元矩形と clipRect の交差部分によって定義されます。

スクロール操作は、BeginDraw を呼び出す前、または EndDraw を呼び出した後にのみ実行できます。中断中または再開されたサーフェスは、まだ更新中であるためスクロールの対象になりません。

IDCompositionVirtualSurface のスクロール可能領域が有効なピクセルに限定されるようにするのは、アプリケーションの責任です。scrollRect 内の無効なピクセルに対する動作は未定義です。

トリム操作またはサイズ変更操作によって破棄された仮想サーフェスの部分矩形領域は、そのトリムやサイズ変更が同じバッチで適用された場合であってもスクロールできません。Trim と Resize は即座に適用されます。

#define global IID_IDCompositionSurface "{BB8A4953-2C99-4F5A-96F5-4819027FA3AC}"
#usecom global IDCompositionSurface IID_IDCompositionSurface "{}"
#comfunc global IDCompositionSurface_BeginDraw    3 var,var,sptr,var
#comfunc global IDCompositionSurface_EndDraw      4
#comfunc global IDCompositionSurface_SuspendDraw  5
#comfunc global IDCompositionSurface_ResumeDraw   6
#comfunc global IDCompositionSurface_Scroll       7 var,var,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。