ビジュアルの座標系は、OffsetX、OffsetY、および Transform の各プロパティによって変更されます。通常、これらのプロパティはビジュアルの座標系を直接の親ビジュアルからの相対として定義します。このメソッドは、このビジュアルの座標系の基準となるビジュアルを指定します。指定するビジュアルは、現在のビジュアルの先祖でなければなりません。先祖でない場合、TransformParent プロパティが NULL に設定されている場合と同様に、座標系はこのビジュアルの直接の親を基準とします。ビジュアルは親を変更できるため、親の変更操作によって指定したビジュアルが対象ビジュアルの先祖になると、このプロパティは再び有効になります。

visual パラメーターが NULL の場合、座標系は常にビジュアルの直接の親を基準として変換されます。これは、このメソッドを使用しない場合の既定の動作です。

visual パラメーターが無効なポインターである場合、またはこのビジュアルを作成した IDCompositionDevice インターフェイスとは異なるインターフェイスによって作成されたものである場合、このメソッドは失敗します。このインターフェイスは独自の実装であってはなりません。このメソッドでは、Microsoft DirectComposition によって作成されたインターフェイスのみを使用できます。

vtbl 10 HRESULT SetEffect(IDCompositionEffect* effect)

このビジュアルの Effect プロパティを設定します。

effect

IDCompositionEffect*

inoptional

エフェクトオブジェクトへのポインターです。このパラメーターには NULL を指定できます。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、このビジュアルをルートとするサブツリーを合成する先となる暗黙のオフスクリーンサーフェスを作成します。このサーフェスは、指定したエフェクトへの入力の 1 つとして使用されます。エフェクトの出力は、合成ターゲットへ直接合成されます。一部のエフェクトは、合成ターゲットをもう 1 つの暗黙の入力としても使用します。これは、不透明度のような合成系またはブレンド系のエフェクトで一般的であり、この場合、合成ターゲットは「背景」とみなされます。その場合、現在のビジュアルより「後ろ」にあるビジュアルは、現在のビジュアルの描画時に合成ターゲットに含まれ、このビジュアルが合成される「背景」とみなされます。

このビジュアルがビジュアルツリーのルートではなく、その先祖の 1 つにもエフェクトが適用されている場合、最も近い先祖が作成したオフスクリーンサーフェスが、このビジュアルのエフェクトの合成先となる合成ターゲットになります。それ以外の場合、合成ターゲットはルート合成ターゲットになります。その結果、合成系およびブレンド系エフェクトの背景には、エフェクトを持つ最も近い先祖までのビジュアルのみが含まれます。逆に、現在のビジュアルより下位のビジュアルに適用されたエフェクトは、新しく作成されたオフスクリーンサーフェスを背景として使用します。これは、それらのビジュアルが、エンドユーザーが「後ろにある」と認識するものの上にどのように合成されるかに影響する可能性があります。

effect パラメーターが NULL の場合、このビジュアルにはビットマップエフェクトが適用されません。このビジュアルに関連付けられていた以前のエフェクトは削除されます。オフスクリーンサーフェスも削除され、ビジュアルのサブツリーは親の合成ターゲットへ直接合成されます。これにより、このビジュアルより下位の合成系またはブレンド系エフェクトの描画結果にも影響が及ぶ可能性があります。

effect が無効なポインターである場合、またはこのビジュアルを作成した IDCompositionDevice インターフェイスとは異なるインターフェイスによって作成されたものである場合、このメソッドは失敗します。このインターフェイスは独自の実装であってはなりません。このメソッドでは、Microsoft DirectComposition によって作成されたインターフェイスのみを使用できます。

vtbl 11 HRESULT SetBitmapInterpolationMode(DCOMPOSITION_BITMAP_INTERPOLATION_MODE interpolationMode)

BitmapInterpolationMode プロパティを設定します。このプロパティは、軸に整列していない、または正確な等倍で描画されないビットマップのピクセルを補間する際に Microsoft DirectComposition が使用するモードを指定します。

interpolationMode

DCOMPOSITION_BITMAP_INTERPOLATION_MODE

使用する補間モードです。

戻り値

型: HRESULT

解説(Remarks)

補間モードは、ビットマップ内のピクセルと画面上のピクセルが 1 対 1 に対応しないような変換がビットマップに適用された場合の、ビットマップの合成方法に影響します。

既定では、ビジュアルは親ビジュアルの補間モードを継承し、その親ビジュアルもさらにその親の補間モードを継承する、というように継承が行われます。ビジュアルに対してこのメソッドが一度も呼び出されない場合、または DCOMPOSITION_BITMAP_INTERPOLATION_MODE_INHERIT を指定して呼び出された場合、ビジュアルは既定の補間モードを使用します。どのビジュアルも補間モードを設定しない場合、ビジュアルツリー全体の既定は最近傍補間となり、これは表示品質が最も低い代わりにパフォーマンスが最も高くなります。

interpolationMode パラメーターが DCOMPOSITION_BITMAP_INTERPOLATION_MODE_INHERIT 以外である場合、このビジュアルのビットマップは指定した補間モードで合成され、そのモードがこのビジュアルの子に対する新しい既定モードになります。つまり、このビジュアルの子の補間モードが変更されていない場合、または明示的に DCOMPOSITION_BITMAP_INTERPOLATION_MODE_INHERIT に設定されている場合、子ビジュアルのビットマップはこのビジュアルの補間モードを使用して合成されます。

vtbl 12 HRESULT SetBorderMode(DCOMPOSITION_BORDER_MODE borderMode)

BorderMode プロパティを設定します。このプロパティは、このビジュアル、またはこのビジュアルをルートとするサブツリー内のビジュアルに関連付けられたビットマップおよびクリップの端をどのように合成するかを指定します。

borderMode

DCOMPOSITION_BORDER_MODE

使用するボーダーモードです。

戻り値

型: HRESULT

解説(Remarks)

ボーダーモードは、ビットマップの端が軸に正確に整列せず、ピクセル境界にも正確に一致しないような変換が適用された場合の、ビットマップの端の合成方法に影響します。また、角が丸いクリップの角部分でコンテンツがどのようにクリップされるか、および端が軸に正確に整列しないような変換が適用されたクリップの端でどのようにクリップされるかにも影響します。

既定では、ビジュアルは親ビジュアルのボーダーモードを継承し、その親ビジュアルもさらにその親のボーダーモードを継承する、というように継承が行われます。ビジュアルに対してこのメソッドが一度も呼び出されない場合、または DCOMPOSITION_BORDER_MODE_INHERIT を指定して呼び出された場合、ビジュアルは既定のボーダーモードを使用します。どのビジュアルもボーダーモードを設定しない場合、ビジュアルツリー全体の既定はエイリアシングありの描画となり、これは表示品質が最も低い代わりにパフォーマンスが最も高くなります。

borderMode パラメーターが DCOMPOSITION_BORDER_MODE_INHERIT 以外である場合、このビジュアルのビットマップとクリップは指定したボーダーモードで合成されます。さらに、このボーダーモードは現在のビジュアルの子に対する新しい既定になります。つまり、このビジュアルの子のボーダーモードが変更されていない場合、または明示的に DCOMPOSITION_BORDER_MODE_INHERIT に設定されている場合、子ビジュアルのビットマップおよびクリップはこのビジュアルのボーダーモードを使用して合成されます。

vtbl 13 HRESULT SetClip(IDCompositionClip* clip)

clip

IDCompositionClip*

inoptional

ビジュアルに適用するクリップオブジェクトへのポインタ。NULLで解除。

vtbl 14 HRESULT SetClip(D2D_RECT_F* rect)

rect

D2D_RECT_F*

クリップ矩形を示すD2D_RECT_Fへのポインタ。

vtbl 15 HRESULT SetContent(IUnknown* content)

このビジュアルの Content プロパティを、指定したビットマップまたはウィンドウラッパーに設定します。

content

IUnknown*

inoptional

このビジュアルの新しいコンテンツとなるオブジェクトです。このパラメーターには NULL を指定できます。

戻り値

型: HRESULT

解説(Remarks)

content パラメーターは、次のいずれかを指す必要があります。

IDCompositionSurface インターフェイスを実装するオブジェクト。
IDXGISwapChain1 インターフェイスを実装するオブジェクト。
CreateSurfaceFromHandle メソッドまたは CreateSurfaceFromHwnd メソッドが返すラッパーオブジェクト。

新しいコンテンツは、このビジュアルに以前関連付けられていたコンテンツを置き換えます。content パラメーターが NULL の場合、このビジュアルに関連付けられたコンテンツはなくなります。

ビジュアルには、ビットマップオブジェクトまたはウィンドウラッパーを関連付けることができます。ビットマップは、Microsoft DirectX のスワップチェーンか、Microsoft DirectComposition のサーフェスのいずれかです。

ウィンドウラッパーは CreateSurfaceFromHwnd メソッドで作成され、別のウィンドウ (トップレベルウィンドウまたはレイヤード子ウィンドウである必要があります) のラスタライズ結果の代替となります。ウィンドウラッパーは概念的には、対象ウィンドウと同じサイズで、そのウィンドウの内容が描画されたビットマップと同等です。この内容には、対象ウィンドウの子ウィンドウ (レイヤードかどうかを問わない) と、その子ウィンドウ内に描画された DirectComposition のコンテンツが含まれます。

DirectComposition のサーフェスラッパーは CreateSurfaceFromHandle メソッドで作成され、スワップチェーンへの参照となります。アプリケーションは、あるプロセスがスワップチェーンを作成し、別のプロセスがそのビットマップをビジュアルに関連付けるといったプロセス間のシナリオで、サーフェスラッパーを使用することがあります。

ビットマップは常に、ビジュアルの座標系における位置 (0,0) に描画されます。ただし、その座標系は OffsetX、OffsetY、Transform の各プロパティによって直接影響を受け、また先祖ビジュアルの変換によって間接的にも影響を受けます。ビジュアルのビットマップは、常にそのビジュアルの子よりも後ろに描画されます。

vtbl 16 HRESULT AddVisual(IDCompositionVisual* visual, BOOL insertAbove, IDCompositionVisual* referenceVisual)

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

visual	IDCompositionVisual*	in	追加する子ビジュアルです。このパラメーターに NULL を指定することはできません。
insertAbove	BOOL	in	新しい子ビジュアルを referenceVisual パラメーターで指定したビジュアルの前面に配置する場合は TRUE、referenceVisual の背面に配置する場合は FALSE を指定します。
referenceVisual	IDCompositionVisual*	inoptional	新しいビジュアルを追加する位置の基準となる、既存の子ビジュアルです。

戻り値

型: HRESULT

解説(Remarks)

子ビジュアルは順序付きリストとして並べられます。子ビジュアルの内容は親ビジュアルの内容の前面 (上) に描画され、その子の内容の背面 (下) に描画されます。

referenceVisual パラメーターは、親ビジュアルの既存の子であるか、NULL でなければなりません。insertAbove パラメーターは、新しい子を Z オーダー上で基準ビジュアルのすぐ上に描画するか、すぐ下に描画するかを示します。

referenceVisual パラメーターが NULL の場合、指定したビジュアルは insertAbove パラメーターの値に応じて、親ビジュアルのすべての子の上または下に描画されます。insertAbove が TRUE の場合、新しい子ビジュアルはどの兄弟よりも上には位置しないため、すべての兄弟の下に描画されます。逆に insertAbove が FALSE の場合、そのビジュアルはどの兄弟よりも下には位置しないため、すべての兄弟の上に描画されます。

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

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

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

例

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

vtbl 17 HRESULT RemoveVisual(IDCompositionVisual* visual)

このビジュアルの子リストから子ビジュアルを削除します。

visual

IDCompositionVisual*

子リストから削除する子ビジュアルです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

解説(Remarks)

指定した子ビジュアルが子リストから削除されます。残りの子ビジュアルの順序は変更されません。

visual が親ビジュアルの子でない場合、このメソッドは失敗します。

vtbl 18 HRESULT RemoveAllVisuals()

このビジュアルの子リストからすべてのビジュアルを削除します。

戻り値

型: HRESULT

解説(Remarks)

このメソッドは、このビジュアルに子がない場合でも呼び出すことができます。

vtbl 19 HRESULT SetCompositeMode(DCOMPOSITION_COMPOSITE_MODE compositeMode)

このビジュアルのブレンドモードを設定します。

compositeMode

DCOMPOSITION_COMPOSITE_MODE

ビジュアルを画面に合成する際に使用するブレンドモードです。

戻り値

型: HRESULT

解説(Remarks)

合成モードは、ビジュアルのビットマップを画面とどのようにブレンドするかを決定します。既定では、ビジュアルは「source over」のセマンティクスでブレンドされます。つまり、色はピクセル単位の透明度を用いてブレンドされます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IDCompositionVisual "{4D93059D-097B-4651-9A60-F0F25116E2F3}"
#usecom global IDCompositionVisual IID_IDCompositionVisual "{}"
#comfunc global IDCompositionVisual_SetOffsetX                  3 sptr
#comfunc global IDCompositionVisual_SetOffsetX                  4 float
#comfunc global IDCompositionVisual_SetOffsetY                  5 sptr
#comfunc global IDCompositionVisual_SetOffsetY                  6 float
#comfunc global IDCompositionVisual_SetTransform                7 sptr
#comfunc global IDCompositionVisual_SetTransform                8 var
#comfunc global IDCompositionVisual_SetTransformParent          9 sptr
#comfunc global IDCompositionVisual_SetEffect                   10 sptr
#comfunc global IDCompositionVisual_SetBitmapInterpolationMode  11 int
#comfunc global IDCompositionVisual_SetBorderMode               12 int
#comfunc global IDCompositionVisual_SetClip                     13 sptr
#comfunc global IDCompositionVisual_SetClip                     14 var
#comfunc global IDCompositionVisual_SetContent                  15 sptr
#comfunc global IDCompositionVisual_AddVisual                   16 sptr,int,sptr
#comfunc global IDCompositionVisual_RemoveVisual                17 sptr
#comfunc global IDCompositionVisual_RemoveAllVisuals            18
#comfunc global IDCompositionVisual_SetCompositeMode            19 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDCompositionVisual "{4D93059D-097B-4651-9A60-F0F25116E2F3}"
#usecom global IDCompositionVisual IID_IDCompositionVisual "{}"
#comfunc global IDCompositionVisual_SetOffsetX                  3 sptr
#comfunc global IDCompositionVisual_SetOffsetX                  4 float
#comfunc global IDCompositionVisual_SetOffsetY                  5 sptr
#comfunc global IDCompositionVisual_SetOffsetY                  6 float
#comfunc global IDCompositionVisual_SetTransform                7 sptr
#comfunc global IDCompositionVisual_SetTransform                8 sptr
#comfunc global IDCompositionVisual_SetTransformParent          9 sptr
#comfunc global IDCompositionVisual_SetEffect                   10 sptr
#comfunc global IDCompositionVisual_SetBitmapInterpolationMode  11 int
#comfunc global IDCompositionVisual_SetBorderMode               12 int
#comfunc global IDCompositionVisual_SetClip                     13 sptr
#comfunc global IDCompositionVisual_SetClip                     14 sptr
#comfunc global IDCompositionVisual_SetContent                  15 sptr
#comfunc global IDCompositionVisual_AddVisual                   16 sptr,int,sptr
#comfunc global IDCompositionVisual_RemoveVisual                17 sptr
#comfunc global IDCompositionVisual_RemoveAllVisuals            18
#comfunc global IDCompositionVisual_SetCompositeMode            19 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。