IDCompositionDevice

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

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

型: HRESULT

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

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

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

例

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

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

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

IDCompositionDevice::GetFrameStatistics メソッドは、合成時間とフレームレートに関する情報を合成エンジンから取得します。

型: HRESULT

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

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

指定されたウィンドウハンドル (HWND) が表すウィンドウにバインドされた合成ターゲットオブジェクトを作成します。

型: HRESULT

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

Microsoft DirectComposition のビジュアルツリーは、画面に何かを表示する前にウィンドウへバインドする必要があります。ウィンドウはトップレベルウィンドウでも子ウィンドウでもかまいません。いずれの場合もレイヤードウィンドウを使用できますが、ウィンドウは呼び出し元のプロセスに属している必要があります。ウィンドウが別のプロセスに属している場合、このメソッドは DCOMPOSITION_ERROR_ACCESS_DENIED を返します。

DirectComposition のコンテンツがウィンドウに合成されるとき、そのコンテンツは常に、GetDC 関数が返すデバイスコンテキスト (HDC) を通じて直接ウィンドウに描画された内容や、Microsoft DirectX の Present メソッド呼び出しによって描画された内容の上に合成されます。ただし、DirectComposition のコンテンツにはウィンドウのクリッピング規則が適用されるため、ウィンドウに子ウィンドウがある場合、それらの子ウィンドウがビジュアルツリーをクリップすることがあります。子ウィンドウがビジュアルツリーをクリップするかどうかは topmost パラメーターによって決まります。

概念的には、各ウィンドウは次の 4 つのレイヤーで構成されます。

1. ウィンドウハンドルに直接描画された内容 (最下層のレイヤー)。
2. 省略可能な DirectComposition のビジュアルツリー。
3. 子ウィンドウがある場合は、そのすべての内容。
4. もう 1 つの省略可能な DirectComposition のビジュアルツリー (最上層のレイヤー)。

システム内の各ウィンドウに対して作成できる合成ターゲットは、最大でも topmost が 1 つ、非 topmost が 1 つの計 2 つだけです。指定したレイヤーで既に合成ターゲットが指定ウィンドウにバインドされている場合、このメソッドは失敗します。合成ターゲットオブジェクトが破棄されると、それが合成していたレイヤーは新しい合成ターゲットオブジェクトで使用できるようになります。

例

次の例では、デバイスオブジェクトを作成して初期化し、そのデバイスオブジェクトを合成ターゲットウィンドウにバインドします。

#include <dcomp.h>
#include <d3d11.h>

HRESULT InitializeDirectCompositionDevice(HWND hwndTarget, 
        ID3D11Device **ppD3D11Device, IDCompositionDevice **ppDevice,
        IDCompositionTarget **ppCompTarget)
{
    HRESULT hr = S_OK;
    D3D_FEATURE_LEVEL featureLevelSupported;
    IDXGIDevice *pDXGIDevice = nullptr;

    // 引数が有効かどうかを確認します。
    if (hwndTarget == NULL || ppD3D11Device == nullptr || ppDevice == nullptr || 
                            ppCompTarget == nullptr)
    {
        return E_INVALIDARG;
    }

    // D3D デバイスオブジェクトを作成します。Direct2D を使用してサーフェスに
    // レンダリングするには D3D11_CREATE_DEVICE_BGRA_SUPPORT フラグが
    // 必要である点に注意してください。
    hr = D3D11CreateDevice(
        nullptr,
        D3D_DRIVER_TYPE_HARDWARE,
        NULL,
        D3D11_CREATE_DEVICE_BGRA_SUPPORT, // Direct2D を使用してサーフェスにレンダリングするために必要
        NULL,
        0,
        D3D11_SDK_VERSION,
        ppD3D11Device,
        &featureLevelSupported,
        NULL);

    if (SUCCEEDED(hr))
    {
        // ビットマップサーフェスの作成に使用する DXGI デバイスを作成します。
        hr = (*ppD3D11Device)->QueryInterface(&pDXGIDevice);
    }

    if (SUCCEEDED(hr))
    {
        // DirectComposition デバイスオブジェクトを作成します。
        hr = DCompositionCreateDevice(pDXGIDevice, __uuidof(IDCompositionDevice), 
                reinterpret_cast<void **>(ppDevice));
    }

    if (SUCCEEDED(hr))
    {
        // DirectComposition デバイスをターゲットウィンドウにバインドします。
        hr = (*ppDevice)->CreateTargetForHwnd(hwndTarget, TRUE, ppCompTarget);   
    }

    return hr;
}

IDCompositionDevice::CreateVisual メソッドは、新しいビジュアルオブジェクトを作成します。

型: HRESULT

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

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

例

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

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

型: HRESULT

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

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

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

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

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

• DXGI_FORMAT_B8G8R8A8_UNORM
• DXGI_FORMAT_R8G8B8A8_UNORM
• DXGI_FORMAT_R16G16B16A16_FLOAT

IDCompositionDevice::CreateVirtualSurface メソッドは、合成のために 1 つ以上のビジュアルに関連付けることができる、疎に配置されたサーフェスを作成します。

型: HRESULT

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

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

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

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

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

• DXGI_FORMAT_B8G8R8A8_UNORM
• DXGI_FORMAT_R8G8B8A8_UNORM
• DXGI_FORMAT_R16G16B16A16_FLOAT

例

次の例は、仮想サーフェスを作成してビジュアルに関連付ける方法を示しています。

HRESULT RenderAVisual(IDCompositionDevice *pDCompDevice, HWND hwndTarget,
                         UINT surfaceWidth, UINT surfaceHeight) 
{
    // 入力パラメーターを検証します。
    if (pDCompDevice == nullptr || hwndTarget == NULL)
        return E_INVALIDARG;
    
    HRESULT hr = S_OK;
    IDCompositionTarget *pTargetWindow = nullptr;
    IDCompositionVisual *pVisual = nullptr;
    IDCompositionVirtualSurface *pVirtualSurface = nullptr;
    ID3D10Texture2D *pTex2D = nullptr;
    POINT offset = {0};

    // レンダーターゲットを作成します。
    hr = pDCompDevice->CreateTargetForHwnd(hwndTarget, TRUE, &pTargetWindow);

    if (SUCCEEDED(hr))
    {
        // ビジュアルを作成します。
        hr = pDCompDevice->CreateVisual(&pVisual);
    }

    if (SUCCEEDED(hr))
    {
        // ビジュアルを合成ツリーのルートに追加します。
        hr = pTargetWindow->SetRoot(pVisual);
    }

    if (SUCCEEDED(hr))
    {
        // 仮想サーフェスを作成します。
        hr = pDCompDevice->CreateVirtualSurface(surfaceWidth, surfaceHeight, 
            DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_ALPHA_MODE_IGNORE, 
            &pVirtualSurface);
    }

    if (SUCCEEDED(hr))
    {
        // 仮想サーフェスをビジュアルのコンテンツとして設定します。
        hr = pVisual->SetContent(pVirtualSurface);
    }
    
    if (SUCCEEDED(hr))
    {
        // サーフェスに描画するためのインターフェースポインターを取得します。
        hr = pVirtualSurface->BeginDraw(NULL, __uuidof(ID3D10Texture2D), 
            (void **) &pTex2D, &offset);
    }

    //
    // TODO: サーフェスに描画します。
    //
    
    if (SUCCEEDED(hr))
    {
        // サーフェスの更新を完了します。
        hr = pVirtualSurface->EndDraw();
    }

    // レンダリングのために合成をコミットします。
    hr = pDCompDevice->Commit();

    // 後始末を行います。
    SafeRelease(&pTargetWindow);
    SafeRelease(&pVisual);
    SafeRelease(&pVirtualSurface);
    SafeRelease(&pTex2D);

    return hr;

}

IDCompositionDevice::CreateSurfaceFromHandle メソッドは、既存の合成サーフェスをラップする新しい合成サーフェスオブジェクトを作成します。

型: HRESULT

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

このメソッドにより、アプリケーションは共有された合成サーフェスを合成ツリー内で使用できます。

IDCompositionDevice::CreateSurfaceFromHwnd メソッドは、レイヤードウィンドウのラスタライズ結果を表し、合成のためにビジュアルに関連付けることができるラッパーオブジェクトを作成します。

型: HRESULT

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

surface ポインターは、IDCompositionVisual::SetContent メソッドの呼び出しで 1 つ以上のビジュアルのコンテンツを設定するために使用できます。コンテンツを設定すると、対象のウィンドウがレイヤードウィンドウである限り、それらのビジュアルは指定されたレイヤードウィンドウの内容を合成します。ウィンドウのレイヤード属性が解除されると、そのウィンドウの内容は合成ツリーの出力から消えます。その後ウィンドウが再びレイヤードになれば、ビジュアルとの関連付けが維持されている限り、ウィンドウの内容は再び表示されます。

ウィンドウのサイズが変更されると、影響を受けるビジュアルが再合成されます。

ウィンドウの内容はウィンドウの寿命を超えてキャッシュされることはありません。つまり、ウィンドウが破棄されると、影響を受けるビジュアルはそのウィンドウの合成を停止します。

ウィンドウが画面外に移動されたりサイズがゼロに変更されたりすると、システムはビジュアルのコンテンツの合成を停止します。元のウィンドウを非表示にしつつシステムにビジュアルのコンテンツの合成を継続させたい場合は、DwmSetWindowAttribute 関数を DWMWA_CLOAK フラグとともに使用して、レイヤード子ウィンドウを「クローク」してください。詳細については、How to animate the bitmap of a layered child window および DirectComposition layered child window sample を参照してください。

例

次のコードスニペットは、レイヤードウィンドウのラスタライズ結果を表すラッパーオブジェクトを作成します。

HRESULT hr = S_OK;
IDCompositionVisual *pVisual = nullptr;
IUnknown *pSurface = nullptr;

// ビジュアルを作成します。g_pDevice は、事前に作成したデバイスオブジェクトの
// IDCompositionDevice ポインターです。
hr = g_pDevice->CreateVisual(&pVisual);

if (SUCCEEDED(hr))
{
    // g_hwndChild ウィンドウハンドル (HWND) で識別されるレイヤード子ウィンドウの
    // イメージを含むサーフェスを作成します。
    hr = g_pDevice->CreateSurfaceFromHwnd(g_hwndChild, &pSurface);
}

if (SUCCEEDED(hr))
{
    // Control 子ビジュアルのコンテンツを設定します。
    hr = pVisual->SetContent(pSurface);
}

IDCompositionDevice::CreateTranslateTransform メソッドは、2D 平行移動変換オブジェクトを作成します。

型: HRESULT

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

新しく作成された 2D 平行移動変換オブジェクトは、OffsetX および OffsetY プロパティが静的な値 0 を持ちます。

IDCompositionDevice::CreateScaleTransform メソッドは、2D 拡大縮小変換オブジェクトを作成します。

型: HRESULT

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

新しく作成された 2D 拡大縮小変換オブジェクトは、ScaleX、ScaleY、CenterX、CenterY の各プロパティが静的な値 0 を持ちます。

2D 回転変換オブジェクトを作成します。(IDCompositionDevice.CreateRotateTransform)

型: HRESULT

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

新しく作成された 2D 回転変換オブジェクトは、Angle、CenterX、CenterY の各プロパティが静的な値 0 を持ちます。

IDCompositionDevice::CreateSkewTransform メソッドは、2D スキュー (せん断) 変換オブジェクトを作成します。

型: HRESULT

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

新しく作成された 2D スキュー変換オブジェクトは、AngleX、AngleY、CenterX、CenterY の各プロパティが静的な値 0 を持ちます。

2D の 3x2 行列変換オブジェクトを作成します。(IDCompositionDevice.CreateMatrixTransform)

型: HRESULT

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

新しく作成された行列変換オブジェクトは、初期値として単位行列を持ちます。単位行列とは、次の図に示すように、主対角成分が 1 で他がすべて 0 である 3x2 行列です。

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

IDCompositionDevice::CreateTransformGroup メソッドは、2D 変換オブジェクトの配列を保持する 2D 変換グループオブジェクトを作成します。

型: HRESULT

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

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

IDCompositionDevice::CreateTranslateTransform3D メソッドは、3D 平行移動変換オブジェクトを作成します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

新しく作成された 3D 平行移動変換は、OffsetX、OffsetY、OffsetZ の各プロパティが静的な値 0 を持ちます。

IDCompositionDevice::CreateScaleTransform3D メソッドは、3D 拡大縮小変換オブジェクトを作成します。

型: HRESULT

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

新しく作成された 3D 拡大縮小変換オブジェクトは、ScaleX、ScaleY、ScaleZ の各プロパティが静的な値 1.0 を持ちます。

IDCompositionDevice インターフェースの CreateRotateTransform3D メソッドは、3D 回転変換オブジェクトを作成します。

型: HRESULT

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

新しく作成された 3D 回転変換オブジェクトは、Angle、CenterX、CenterY、AxisX、AxisY の各プロパティが既定の静的な値 0 を持ち、AxisZ プロパティが既定の静的な値 1.0 を持ちます。

3D の 4x4 行列変換オブジェクトを作成します。(IDCompositionDevice.CreateMatrixTransform3D)

型: HRESULT

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

新しい 3D 行列変換は、単位行列を値として持ちます。単位行列とは、次の図に示すように、主対角成分が 1 で他がすべて 0 である 4x4 行列です。

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

IDCompositionDevice::CreateTransform3DGroup メソッドは、3D 変換オブジェクトの配列を保持する 3D 変換グループオブジェクトを作成します。

型: HRESULT

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

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

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

型: HRESULT

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

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

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

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

型: HRESULT

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

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

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

型: HRESULT

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

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

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

DirectComposition デバイスオブジェクトがまだ有効かどうかを判定します。

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

Microsoft DirectX Graphics Infrastructure (DXGI) デバイスが失われると、その DXGI デバイスに関連付けられた DirectComposition デバイスも失われます。デバイスの喪失を検出すると、DirectComposition は失われたデバイスを使用して DirectComposition のコンテンツを合成しているすべてのウィンドウに WM_PAINT メッセージを送信します。アプリケーションは、DirectComposition デバイスオブジェクトがまだ有効であることを確認するために、各 WM_PAINT メッセージに応じて CheckDeviceState を呼び出す必要があります。デバイスオブジェクトが無効になった場合、アプリケーションはコンテンツを復旧するための処理を行わなければなりません。その処理には、新しい DXGI デバイスと DirectComposition デバイスの作成、およびすべてのコンテンツの再作成が含まれます (新しい DXGI デバイスだけを作成して既存の DirectComposition デバイスに関連付けることはできません)。システムは、WM_PAINT メッセージの間はデバイスオブジェクトが有効であり続けることを保証します。