IDCompositionSurface::BeginDraw メソッド (dcomp.h)
この Microsoft DirectComposition サーフェス オブジェクトでの描画を開始します。 更新四角形は、サーフェスの境界内にある必要があります。それ以外の場合、このメソッドは失敗します。
構文
HRESULT BeginDraw(
[in, optional] const RECT *updateRect,
[in] REFIID iid,
[out] void **updateObject,
[out] POINT *updateOffset
);
パラメーター
[in, optional] updateRect
型: const RECT*
更新する四角形。 このパラメーターが NULL の場合、ビットマップ全体が更新されます。
[in] iid
型: REFIID
取得するインターフェイスの識別子。
[out] updateObject
型: void**
iid パラメーターで指定された型のインターフェイス ポインターを受け取ります。 このパラメーターを NULL にすることはできません。
[out] updateOffset
種類: POINT*
アプリケーションが更新されたコンテンツを描画するサーフェスへのオフセット。 このオフセットは、更新四角形の左上隅を参照します。
戻り値
型: HRESULT
関数が成功した場合は、S_OK を返します。 そうでない場合は、HRESULT エラー コードを返します。
注釈
このメソッドを使用すると、アプリケーションで DirectComposition サーフェス オブジェクトの内容を増分更新できます。 アプリケーションでは、次のシーケンスを使用する必要があります。
- BeginDraw を呼び出して増分更新を開始します。
- 取得したサーフェスをレンダー ターゲットとして使用し、取得したオフセットに更新されたコンテンツを描画します。
- IDCompositionSurface::EndDraw メソッドを呼び出して更新を完了します。
iid パラメーターは、DirectComposition サーフェス オブジェクトが DirectComposition デバイスまたは関連付けられた Direct2D デバイスで作成されたサーフェス ファクトリから作成された場合にのみ、__uuidof(ID2D1DeviceContext) にすることができます。 特に、アプリケーションは、Direct2D デバイスを renderingDevice パラメーターとして使用して、DCompositionCreateDevice2 関数または IDCompositionDevice2::CreateSurfaceFactory メソッドを呼び出す必要があります。 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 デバイスに属する別のサーフェスに対して BeginDraw を 2 回呼び出した場合、 IDCompositionSurface::EndDraw の呼び出しが間もなく行われます。2 回目の呼び出しは失敗します。 アプリケーションが EndDraw を呼び出さずに IDCompositionDevice2::Commit を呼び出した場合、更新は保留中のままです。 更新は、アプリケーションが EndDraw を呼び出してから IDCompositionDevice2::Commit メソッドを呼び出した後にのみ有効になります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2012 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | dcomp.h |
| Library | Dcomp.lib |
| [DLL] | Dcomp.dll |