IDCompositionVisual::AddVisual メソッド (dcomp.h)

このビジュアルの子リストに新しい子ビジュアルを追加します。

構文

HRESULT AddVisual(
  [in]           IDCompositionVisual *visual,
  [in]           BOOL                insertAbove,
  [in, optional] IDCompositionVisual *referenceVisual
);

パラメーター

[in] visual

種類: IDCompositionVisual*

追加する子ビジュアル。 このパラメーターを NULL にすることはできません。

[in] insertAbove

種類: BOOL

referenceVisual パラメーターで指定されたビジュアルの前に新しい子ビジュアルを配置する場合は TRUE、referenceVisual の後ろに配置する場合は FALSE。

[in, optional] referenceVisual

種類: IDCompositionVisual*

新しいビジュアルを追加する必要がある横にある既存の子ビジュアル。

戻り値

種類: HRESULT

関数が成功した場合は、S_OK を返します。 そうでない場合は、HRESULT エラー コードを返します。 エラー コードの一覧については、「 DirectComposition エラー コード 」を参照してください。

解説

子ビジュアルは順序付きリストに配置されます。 子ビジュアルの内容は、親ビジュアルの内容の前 (またはそれ以降) に描画されますが、その子の内容の背後 (または下) に描画されます。

referenceVisual パラメーターは、親ビジュアルの既存の子であるか、NULL である必要があります。 insertAbove パラメーターは、新しい子を参照ビジュアルのすぐ上で Z オーダーでレンダリングするか、そのすぐ下にレンダリングするかを示します。

referenceVisual パラメーターが NULL の場合、insertAbove パラメーターの値に応じて、指定したビジュアルが親ビジュアルのすべての子の上または下にレンダリングされます。 insertAbove が TRUE の場合、新しい子ビジュアルは兄弟の上にないため、すべての兄弟の下にレンダリングされます。 逆に、 insertAbove が FALSE の場合、ビジュアルは兄弟を下回っていないため、すべての兄弟の上にレンダリングされます。

visual パラメーターで指定された ビジュアル は、他の 1 つのビジュアルの子、またはコンポジション ターゲットに関連付けられているビジュアル ツリーのルートにすることはできません。 ビジュアルが既に別のビジュアルの子である場合、AddVisual は失敗します。 子ビジュアルは、新しい親の子リストに追加する前に、前の親の子リストから削除する必要があります。 ビジュアルがビジュアル ツリーのルートである場合、ビジュアルを新しい親の子リストに追加する前に、そのビジュアル ツリーとの関連付けを解除する必要があります。 ビジュアルをビジュアル ツリーから関連付け解除するには、 IDCompositionTarget::SetRoot メソッドを呼び出し、 visual パラメーターとして 別のビジュアルまたは NULL を指定します。

子ビジュアルは、その親と同じ IDCompositionDevice インターフェイスによって作成されている必要はありません。 異なるデバイスのビジュアルを同じビジュアル ツリーに結合すると、Microsoft DirectComposition は通常と同じようにツリーを構成します。ただし、特定のビジュアルに対する変更は、ビジュアルを作成したデバイス オブジェクトで IDCompositionDevice::Commit が呼び出された場合にのみ有効になります。 異なるデバイスのビジュアルを結合する機能により、複数のスレッドで 1 つのビジュアル ツリーを作成および操作しながら、変更を非同期でコミットするために使用できる独立したデバイスを維持できます。

visual または referenceVisual が無効なポインターである場合、または referenceVisual パラメーターによって参照されるビジュアルが親ビジュアルの子ではない場合、このメソッドは失敗します。 これらのインターフェイスをカスタム実装にすることはできません。このメソッドでは、DirectComposition によって作成されたインターフェイスのみを使用できます。

例

例については、「 How to Build a Simple Visual Tree」を参照してください。

要件

関連項目

IDCompositionDevice::CreateVisual

IDCompositionTarget::SetRoot

IDCompositionVisual

IDCompositionVisual::RemoveAllVisuals

IDCompositionVisual::RemoveVisual