ビジュアル レイヤーを使用して UI を拡張する (Windows App SDK/WinUI 3)

Windows App SDK/WinUI 3 のビジュアル レイヤーは、グラフィックス、エフェクト、アニメーション、入力のためのハイ パフォーマンスの保持モード API を提供します。 これは、Windows デバイス全体のすべての UI のための基礎です。

Microsoft.UI.Composition の型は、ビジュアル レイヤーの Windows App SDK/WinUI 3 実装を形成します。 これは UWP ビジュアル レイヤー とよく似ており、Windows.UI.Composition 名前空間に実装されています。 この 2 つの違いと Windows アプリ SDK/WinUI 3 ビジュアル レイヤーの不足している機能は次のとおりです。

UWP との相違点

Microsoft.UI.Composition と UWP ビジュアル レイヤーの最も明白な違いは、名前空間です。 Microsoft.UI.Composition を使用すると、最も一般的に使用されるシナリオにおいて、UWP ビジュアル レイヤーとほぼ同じ機能にアクセスできます。 ただし、例外がありますし、相違点もあります。

Windows App SDK/WinUI 3 では Microsoft.UI.Composition を使用して個々のビジュアルのツリーを記述します。 その後、これらのビジュアルは、ウィンドウの完全なレンダリングを作成するために合成されます。 これは、Windows.UI.Composition のしくみとよく似ています (UWP アプリの場合)。 ただし、Microsoft.UI.Composition コンポジターは Windows アプリ SDK アプリ内で完全に実行され、描画されたピクセルにのみアクセスできる点が大きく異なります。 つまり、外部コンテンツ (コンポジターによって描画されなかったコンテンツ) はコンポジターに対して不明です。 これにより、特定の制限事項が作られます。

外部コンテンツの例として、(Microsoft.UI.Xaml.Controls) MediaPlayerElement があります。 Windows メディア スタックは、不透明なメディア スワップ チェーン ハンドルを XAML に提供します。 XAML は、そのハンドルをコンポジターに渡し、コンポジターは Windows (Windows.UI.Composition 経由) に渡して表示します。 具体的には、コンポジターはメディア スワップ チェーン内のどのピクセルも表示できないため、ウィンドウの全体的なレンダリングの一部として合成することはできません。 代わりに、メディア スワップ チェーンを Windows に渡してコンポジターのレンダリングの下にレンダリングし、その下のメディア スワップ チェーンを視覚化できるようにコンポジターのレンダリングから穴を開けます。 この設定を視覚化したのがこちらです。

一般に、このアプローチでは、外部コンテンツ (スワップ チェーンなど) をウィンドウの全体的なレンダリングの一部にすることができます。また、コンポジターで描画された他のコンテンツを外部コンテンツの上部に重ねることができます。たとえば、XAML の MediaTransportControls レンダリングがメディアの上部に表示されます。 ただし、この外部コンテンツとのより高度な効果の相互作用は許可されません。 これは、XAML (たとえば、SwapChainPanel の使用)、またはコンポジション (たとえば、ICompositorInterop::CreateCompositionSurfaceForSwapChain の使用) を使用して、スワップ チェーンをビューに差し込むために使用できるすべての方法に適用されます。

Windows アプリ SDK/WinUI 3 では、次の API はすべて外部コンテンツを作成します。

• MediaPlayerElement
• SwapChainPanel
• WebView2
• MicaBackdrop と DesktopAcrylicBackdrop、およびそれらが使用する基礎になる MicaController と DesktopAcrylicController。

上記で説明した外部コンテンツを扱うモデルでは、次のような制限が生じます。

• コンポジター コンテンツを外部コンテンツの背後 (つまり、上の図の外部レイヤーの背後または下) に配置することはできません。 そのため、たとえば、WEBView2 の背後にある XAML ボタンや画像を表示するために、透明な背景を WebView2 に付与することはできません。 外部コンテンツの背後にすることができるのは、他の外部コンテンツとウィンドウの背景のみです。 そのため、外部コンテンツの透明性を推奨または無効にしています。
• 外部コンテンツからコンポジター コンテンツをサンプリングすることはできません。 たとえば、AcrylicBrush では、MediaPlayerElement からピクセルをサンプリングしたりぼかしたりすることはできません。 AcrylicBrush はコンポジターの画像からサンプリングします。これは、外部コンテンツ領域に対して透明な黒になります。 透明な黒が AcrylicBrush のぼかしになります。 同様に、MicaBackdrop or DesktopAcrylicBackdrop の前にある AcrylicBrush では、背景に描かれる色は見えません。代わりに、ブラシは透明な黒をぼかします。
• もう 1 つのシナリオは「宛先の反転」と呼ばれます。これは、テキスト ボックス コントロールのキャレットに使用され、テキスト挿入キャレットが前にあるピクセルを反転させます。 この反転も同様に、コンポジターの表面からサンプリングし、テキストボックスにコンポジターで描画される不透明な背景がない場合に、この反転は影響を受けます。
• WinUI 3 SwapChainPanel は外部コンテンツを作成するため、透明性をサポートしていません。 また、AcrylicBrush やその前に CompositionBackdropBrush を使用する他の効果の適用もサポートしていません。 AcrylicBrush とその他の CompositionBackdropBrush ベースの効果はSwapChainPanel からサンプリングできません。
• デスクトップ アプリ (WinUI 3 アプリはデスクトップ アプリ) では、Window.Current は null です。 そのため、Compositor のインスタンスを Window.Current.Compositor から取得することはできません。 XAML アプリ (WinUI 3 と UWP の両方) では、ElementCompositionPreview.GetElementVisual(UIElement) を呼び出してコンポジションのビジュアルを取得し、Compositor をそのビジュアルの コンポジター プロパティから取得することをお勧めします。 UIElement にアクセスできない (CompositionBrush をクラス ライブラリで作成する場合など) 場合は、CompositionTarget.GetCompositorForCurrentThread を呼び出すことができます。

ビジュアル レイヤーの詳細については、UWP ドキュメントのビジュアル レイヤーの概要に関する記事を参照してください。 ほとんどの場合、ドキュメントとサンプルは、Microsoft.UI.Composition にも適用できます。

Microsoft.UI.Composition を使用するための前提条件

Windows App SDK/WinUI 3 で Microsoft.UI.Composition API を使用するには、次の手順を実行します。

1. Windows App SDK の最新リリースをダウンロードしてインストールします。 詳細については、「Windows App SDK 用ツールをインストールする」を参照してください。
2. その後、手順に従って、最初の WinUI 3 プロジェクトを作成するか、既存のプロジェクトで Windows App SDK を使用します。

Windows App SDK/WinUI 3 での Microsoft.UI.Composition の可用性に関する詳細については、リリース チャネルに関する記事を参照してください。

Windows Composition サンプル ギャラリー

Windows Composition サンプル ギャラリーを更新し、Windows App SDK Composition API に依存するようになりました。 WindowsCompositionSamples にアクセスして、Microsoft.UI.Composition API の動作を確認してください。

関連トピック

• UWP ビジュアル レイヤーの概要
• デスクトップ アプリでのビジュアル レイヤーの使用