ホーム › Graphics.DirectComposition › IDCompositionDevice2

IDCompositionDevice2

COM

📘 Microsoft Learn (日本語) · English

IID75f6468d-1b8e-447c-9bc6-75fea80b5b25継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

他のすべての Microsoft DirectComposition オブジェクトのファクトリとして機能し、トランザクション的な合成を制御するメソッドを提供します。(IDCompositionDevice2)

メソッド 21

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Commit()

このデバイスで保留中のすべての DirectComposition コマンドをコミットします。(IDCompositionDevice2.Commit)

戻り値

型: HRESULT

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

解説(Remarks)

DirectComposition のメソッド呼び出しは常にバッチ化され、単一のトランザクションとしてアトミックに実行されます。呼び出しが実際に反映されるのは IDCompositionDevice2::Commit が呼び出されたときのみで、その時点でデバイスの保留中のメソッド呼び出しがすべて一度に実行されます。

複数のデバイスを使用するアプリケーションは、デバイスごとに個別に Commit を呼び出す必要があります。ただし、合成エンジンは呼び出しを個別に処理するため、コマンドのバッチが同時に反映されるとは限りません。

vtbl 4 HRESULT WaitForCommitCompletion()

直前の IDCompositionDevice2::Commit メソッドの呼び出しを合成エンジンが処理し終えるまで待機します。

戻り値

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

vtbl 5 HRESULT GetFrameStatistics(DCOMPOSITION_FRAME_STATISTICS* statistics)

合成時間およびフレームレートに関する情報を合成エンジンから取得します。

statistics

DCOMPOSITION_FRAME_STATISTICS*

out

合成時間とフレームレートの情報を受け取る構造体です。

戻り値

型: HRESULT

解説(Remarks)

このメソッドは、ビットマップのラスタライズを独立アニメーションと同期させるためにアプリケーションが利用できる、合成エンジンのタイミング情報を取得します。

vtbl 6 HRESULT CreateVisual(IDCompositionVisual2** visual)

新しいビジュアルオブジェクトを作成します。

visual

IDCompositionVisual2**

out

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

戻り値

型: HRESULT

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

解説(Remarks)

新しいビジュアルオブジェクトは、OffsetX および OffsetY プロパティが静的値 0 に、Transform、Clip、Content の各プロパティが NULL に設定されています。作成直後のビジュアルはウィンドウの内容を変化させません。ウィンドウの外観に影響を与えるには、そのビジュアルを他のビジュアルの子として、または合成ターゲットのルートとして追加する必要があります。

vtbl 7 HRESULT CreateSurfaceFactory(IUnknown* renderingDevice, IDCompositionSurfaceFactory** surfaceFactory)

Microsoft DirectComposition のサーフェスファクトリオブジェクトを作成します。これは他の DirectComposition のサーフェスまたは仮想サーフェスオブジェクトを作成するために使用できます。

renderingDevice	IUnknown*	in	DirectComposition のサーフェスオブジェクトの作成に使用する DirectX デバイスへのポインターです。IDXGIDevice または ID2D1Device インターフェイスを実装するオブジェクトへのポインターである必要があります。このパラメーターに NULL を指定することはできません。
surfaceFactory	IDCompositionSurfaceFactory**	out	新しく作成されたサーフェスファクトリオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

解説(Remarks)

サーフェスファクトリを使用すると、アプリケーションは複数の DXGI デバイスまたは Direct2D デバイスを DirectComposition と同時に使用できます。各サーフェスファクトリは 1 つの DXGI または Direct2D デバイスと恒久的に関連付けられますが、1 つの DirectComposition デバイスは任意の数のサーフェスファクトリを持つことができます。

各サーフェスファクトリは、他のファクトリとは独立してリソースを管理します。特に、DirectComposition はサーフェスの割り当て・解放のコストを軽減するためにサーフェスの割り当てをプールしますが、このプールはサーフェスファクトリ単位で行われます。

DCompositionCreateDevice2 関数を NULL 以外の renderingDevice パラメーターで呼び出した場合、返される DirectComposition デバイスオブジェクトは、指定されたレンダリングデバイスに関連付けられた暗黙のサーフェスファクトリを内部的に保持します。この暗黙のサーフェスファクトリは、IDCompositionDevice::CreateSurface、IDCompositionDevice::CreateVirtualSurface、IDCompositionDevice2::CreateSurface、IDCompositionDevice2::CreateVirtualSurface の各メソッドの処理に使用されます。

サーフェスファクトリオブジェクトは、それが作成したサーフェスまたは仮想サーフェスのいずれかが生存している限り(アプリケーションが直接参照を保持している場合だけでなく、そうしたサーフェスが 1 つ以上のビジュアルオブジェクトに関連付けられていることによる間接的な場合も含めて)、生存し続けます。

vtbl 8 HRESULT CreateSurface(DWORD width, DWORD height, DXGI_FORMAT pixelFormat, DXGI_ALPHA_MODE alphaMode, IDCompositionSurface** surface)

合成のために 1 つ以上のビジュアルに関連付けることができる、更新可能なサーフェスオブジェクトを作成します。

width

DWORD

サーフェスの幅(ピクセル単位)です。DirectComposition デバイスの作成時に渡されたレンダリングデバイスの機能レベルによる制約を受けます。

height

DWORD

サーフェスの高さ(ピクセル単位)です。DirectComposition デバイスの作成時に渡されたレンダリングデバイスの機能レベルによる制約を受けます。

pixelFormat

DXGI_FORMAT

サーフェスのピクセル形式です。

alphaMode

DXGI_ALPHA_MODE

ピクセル形式にアルファチャネルが含まれる場合の、アルファチャネルの形式です。次のいずれかの値を指定できます。

値	意味
DXGI_ALPHA_MODE_UNSPECIFIED	アルファチャネルは指定されません。この値は DXGI_ALPHA_MODE_IGNORE と同じ効果を持ちます。
DXGI_ALPHA_MODE_PREMULTIPLIED	カラーチャネルには、アルファチャネルで乗算済み(プリマルチプライド)の値が格納されます。
DXGI_ALPHA_MODE_IGNORE	アルファチャネルは無視され、ビットマップは不透明として描画されます。

surface

IDCompositionSurface**

out

新しく作成されたサーフェスオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

解説(Remarks)

Microsoft DirectComposition のサーフェスは、合成のためにビジュアルに関連付けることができる、ピクセルの矩形配列です。

新しく作成されたサーフェスオブジェクトは未初期化の状態です。未初期化の間、そのサーフェスはビジュアルツリーの合成に影響を与えず、100% 透明なピクセルを持つサーフェスとまったく同じように振る舞います。

サーフェスをピクセルデータで初期化するには、IDCompositionSurface::BeginDraw および IDCompositionSurface::EndDraw メソッドを使用します。このメソッドの最初の呼び出しでは、すべてのピクセルに初期値を与えるために、サーフェス全体を対象とする必要があります。以降の呼び出しでは、更新対象としてサーフェスのより小さな部分矩形を指定できます。

DirectComposition のサーフェスは次のピクセル形式をサポートします。

vtbl 9 HRESULT CreateVirtualSurface(DWORD initialWidth, DWORD initialHeight, DXGI_FORMAT pixelFormat, DXGI_ALPHA_MODE alphaMode, IDCompositionVirtualSurface** virtualSurface)

合成のために 1 つ以上のビジュアルに関連付けることができる、疎に実体化されたサーフェスを作成します。(IDCompositionDevice2.CreateVirtualSurface)

initialWidth

DWORD

サーフェスの幅(ピクセル単位)です。最大幅は 16,777,216 ピクセルです。

initialHeight

DWORD

サーフェスの高さ(ピクセル単位)です。最大高さは 16,777,216 ピクセルです。

pixelFormat

DXGI_FORMAT

サーフェスのピクセル形式です。

alphaMode

DXGI_ALPHA_MODE

ピクセル形式にアルファチャネルが含まれる場合の、アルファチャネルの意味です。次のいずれかの値を指定できます。

値	意味
DXGI_ALPHA_MODE_UNSPECIFIED	アルファチャネルは指定されません。この値は DXGI_ALPHA_MODE_IGNORE と同じ効果を持ちます。
DXGI_ALPHA_MODE_PREMULTIPLIED	カラーチャネルには、アルファチャネルで乗算済み(プリマルチプライド)の値が格納されます。
DXGI_ALPHA_MODE_IGNORE	アルファチャネルは無視され、ビットマップは不透明として描画されます。

virtualSurface

IDCompositionVirtualSurface**

out

新しく作成されたサーフェスオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

解説(Remarks)

Microsoft DirectComposition のスパースサーフェスは、合成のためにビジュアルに関連付けることができるピクセルの矩形配列のように振る舞う論理的なオブジェクトです。このサーフェスは、すべてのピクセルに対して物理的なビデオメモリやシステムメモリが割り当てられているとは限りません。アプリケーションは、論理サーフェスの一部を任意のタイミングで実体化したり仮想化したりできます。

新しく作成されたサーフェスオブジェクトは未初期化の状態です。未初期化の間、そのサーフェスはビジュアルツリーの合成に影響を与えず、100% 透明なピクセルで初期化されたサーフェスとまったく同じように振る舞います。

サーフェスをピクセルデータで初期化するには、IDCompositionSurface::BeginDraw および IDCompositionSurface::EndDraw メソッドを使用します。このメソッドはサーフェスにピクセルを提供するだけでなく、それらのピクセルのための実際の記憶領域も割り当てます。このメモリ割り当ては、アプリケーションがメモリの一部をシステムに返却するまで保持されます。アプリケーションは IDCompositionVirtualSurface::Trim メソッドを呼び出すことで、割り当て済みメモリの一部またはすべてを解放できます。

DirectComposition のサーフェスは次のピクセル形式をサポートします。

新しい行列変換オブジェクトの初期値は単位行列です。単位行列とは、次の図に示すように主対角成分が 1 で、それ以外が 0 である 3x2 行列です。

単位変換をオブジェクトに適用しても、オブジェクトの位置、形状、サイズは変化しません。これは、数値に 1 を掛けてもその数値が変わらないのと同様です。単位変換以外の変換は、オブジェクトの位置、形状、サイズのいずれか(または複数)を変更します。

vtbl 15 HRESULT CreateTransformGroup(IDCompositionTransform** transforms, DWORD elements, IDCompositionTransform** transformGroup)

2D 変換オブジェクトの配列を保持する 2D 変換グループオブジェクトを作成します。

transforms	IDCompositionTransform**	in	この変換グループを構成する 2D 変換オブジェクトの配列です。
elements	DWORD	in	transforms 配列の要素数です。
transformGroup	IDCompositionTransform**	out	新しい変換グループオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

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

解説(Remarks)

新しい 3D 行列変換の値は単位行列です。単位行列とは、次の図に示すように主対角成分が 1 で、それ以外が 0 である 4x4 行列です。

vtbl 20 HRESULT CreateTransform3DGroup(IDCompositionTransform3D** transforms3D, DWORD elements, IDCompositionTransform3D** transform3DGroup)

3D 変換オブジェクトの配列を保持する 3D 変換グループオブジェクトを作成します。

transforms3D	IDCompositionTransform3D**	in	この変換グループを構成する 3D 変換オブジェクトの配列です。
elements	DWORD	in	transforms 配列の要素数です。
transform3DGroup	IDCompositionTransform3D**	out	新しい 3D 変換グループオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

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

解説(Remarks)

3D 変換グループ内の配列要素を変更することはできません。ただし、配列内の各変換は、それぞれのプロパティ設定メソッドを通じて変更できます。配列内の変換が変更された場合、その変更は変換グループの計算後の行列に反映されます。

vtbl 21 HRESULT CreateEffectGroup(IDCompositionEffectGroup** effectGroup)

ビジュアルのサブツリーに適用する複数のエフェクトを表すオブジェクトを作成します。(IDCompositionDevice2.CreateEffectGroup)

effectGroup

IDCompositionEffectGroup**

out

新しいエフェクトグループオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

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

解説(Remarks)

エフェクトグループを使用すると、アプリケーションは 1 つのビジュアルサブツリーに複数のエフェクトを適用できます。

新しいエフェクトグループは、既定の不透明度値が 1.0 であり、3D 変換は設定されていません。

不透明度や変換の値を設定するには、作成した IDCompositionEffectGroup の対応するメソッドを使用します。

vtbl 22 HRESULT CreateRectangleClip(IDCompositionRectangleClip** clip)

ビジュアルサブツリーの描画を矩形領域に制限するために使用できるクリップオブジェクトを作成します。(IDCompositionDevice2.CreateRectangleClip)

clip

IDCompositionRectangleClip**

out

新しいクリップオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

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

解説(Remarks)

新しく作成されたクリップオブジェクトは、left および top プロパティの値が -2^21、right および bottom プロパティの値が 2^21 であり、実質的に何もしないクリップオブジェクトとなります。

vtbl 23 HRESULT CreateAnimation(IDCompositionAnimation** animation)

1 つ以上の Microsoft DirectComposition オブジェクトの、1 つ以上のスカラープロパティをアニメーション化するために使用するアニメーションオブジェクトを作成します。(IDCompositionDevice2.CreateAnimation)

animation

IDCompositionAnimation**

out

新しいアニメーションオブジェクトです。このパラメーターに NULL を指定することはできません。

戻り値

型: HRESULT

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

解説(Remarks)

DirectComposition オブジェクトの多くのプロパティは、その値としてアニメーションオブジェクトを持つことができます。プロパティの値がアニメーションオブジェクトである場合、DirectComposition はアニメーション化されているプロパティの値の変化を反映するために、リフレッシュレートに合わせてビジュアルを再描画します。

新しく作成されたアニメーションオブジェクトには、アニメーションセグメントが 1 つも関連付けられていません。アプリケーションは、アニメーションオブジェクトを他の DirectComposition オブジェクトのプロパティとして設定する前に、IDCompositionAnimation インターフェイスのメソッドを使用してアニメーション関数を構築する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IDCompositionDevice2 "{75F6468D-1B8E-447C-9BC6-75FEA80B5B25}"
#usecom global IDCompositionDevice2 IID_IDCompositionDevice2 "{}"
#comfunc global IDCompositionDevice2_Commit                      3
#comfunc global IDCompositionDevice2_WaitForCommitCompletion     4
#comfunc global IDCompositionDevice2_GetFrameStatistics          5 var
#comfunc global IDCompositionDevice2_CreateVisual                6 sptr
#comfunc global IDCompositionDevice2_CreateSurfaceFactory        7 sptr,sptr
#comfunc global IDCompositionDevice2_CreateSurface               8 int,int,int,int,sptr
#comfunc global IDCompositionDevice2_CreateVirtualSurface        9 int,int,int,int,sptr
#comfunc global IDCompositionDevice2_CreateTranslateTransform    10 sptr
#comfunc global IDCompositionDevice2_CreateScaleTransform        11 sptr
#comfunc global IDCompositionDevice2_CreateRotateTransform       12 sptr
#comfunc global IDCompositionDevice2_CreateSkewTransform         13 sptr
#comfunc global IDCompositionDevice2_CreateMatrixTransform       14 sptr
#comfunc global IDCompositionDevice2_CreateTransformGroup        15 sptr,int,sptr
#comfunc global IDCompositionDevice2_CreateTranslateTransform3D  16 sptr
#comfunc global IDCompositionDevice2_CreateScaleTransform3D      17 sptr
#comfunc global IDCompositionDevice2_CreateRotateTransform3D     18 sptr
#comfunc global IDCompositionDevice2_CreateMatrixTransform3D     19 sptr
#comfunc global IDCompositionDevice2_CreateTransform3DGroup      20 sptr,int,sptr
#comfunc global IDCompositionDevice2_CreateEffectGroup           21 sptr
#comfunc global IDCompositionDevice2_CreateRectangleClip         22 sptr
#comfunc global IDCompositionDevice2_CreateAnimation             23 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDCompositionDevice2 "{75F6468D-1B8E-447C-9BC6-75FEA80B5B25}"
#usecom global IDCompositionDevice2 IID_IDCompositionDevice2 "{}"
#comfunc global IDCompositionDevice2_Commit                      3
#comfunc global IDCompositionDevice2_WaitForCommitCompletion     4
#comfunc global IDCompositionDevice2_GetFrameStatistics          5 sptr
#comfunc global IDCompositionDevice2_CreateVisual                6 sptr
#comfunc global IDCompositionDevice2_CreateSurfaceFactory        7 sptr,sptr
#comfunc global IDCompositionDevice2_CreateSurface               8 int,int,int,int,sptr
#comfunc global IDCompositionDevice2_CreateVirtualSurface        9 int,int,int,int,sptr
#comfunc global IDCompositionDevice2_CreateTranslateTransform    10 sptr
#comfunc global IDCompositionDevice2_CreateScaleTransform        11 sptr
#comfunc global IDCompositionDevice2_CreateRotateTransform       12 sptr
#comfunc global IDCompositionDevice2_CreateSkewTransform         13 sptr
#comfunc global IDCompositionDevice2_CreateMatrixTransform       14 sptr
#comfunc global IDCompositionDevice2_CreateTransformGroup        15 sptr,int,sptr
#comfunc global IDCompositionDevice2_CreateTranslateTransform3D  16 sptr
#comfunc global IDCompositionDevice2_CreateScaleTransform3D      17 sptr
#comfunc global IDCompositionDevice2_CreateRotateTransform3D     18 sptr
#comfunc global IDCompositionDevice2_CreateMatrixTransform3D     19 sptr
#comfunc global IDCompositionDevice2_CreateTransform3DGroup      20 sptr,int,sptr
#comfunc global IDCompositionDevice2_CreateEffectGroup           21 sptr
#comfunc global IDCompositionDevice2_CreateRectangleClip         22 sptr
#comfunc global IDCompositionDevice2_CreateAnimation             23 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。