IDCompositionDevice：：CreateVirtualSurface 方法 (dcomp.h)

建立疏鬆填入的介面，可與一或多個視覺效果建立關聯以進行組合。

語法

HRESULT CreateVirtualSurface(
  [in]  UINT                        initialWidth,
  [in]  UINT                        initialHeight,
  [in]  DXGI_FORMAT                 pixelFormat,
  [in]  DXGI_ALPHA_MODE             alphaMode,
  [out] IDCompositionVirtualSurface **virtualSurface
);

參數

[in] initialWidth

類型： UINT

表面的寬度，以像素為單位。 最大寬度為 16,777,216 圖元。

[in] initialHeight

類型： UINT

表面的高度，以像素為單位。 高度上限為 16,777,216 圖元。

[in] pixelFormat

類型： DXGI_FORMAT

表面的像素格式。

[in] alphaMode

類型： DXGI_ALPHA_MODE

如果圖元格式包含 Alpha 色板，則 Alpha 色板的意義。 它可能是下列其中一個值：

值	意義
DXGI_ALPHA_MODE_UNSPECIFIED	未指定 Alpha 色板。 這個值的效果與 DXGI_ALPHA_MODE_IGNORE相同。
DXGI_ALPHA_MODE_PREMULTIPLIED	色彩色板包含預先乘以Alpha色板的值。
DXGI_ALPHA_MODE_IGNORE	應該忽略 Alpha 色板，而且應該不透明地轉譯位圖。

[out] virtualSurface

類型： IDCompositionVirtualSurface**

新建立的 Surface 物件。 此參數不得為 NULL。

傳回值

類型： HRESULT

如果函式成功，則會傳回S_OK。 否則，它會傳回 HRESULT 錯誤碼。 如需錯誤碼清單，請參閱 DirectComposition 錯誤碼 。

備註

Microsoft DirectComposition 疏鬆表面是一個邏輯物件，其行為就像與視覺效果相關聯的矩形像素數位進行組合。 表面不一定受到其每一個圖元的任何實體視訊或系統記憶體支援。 應用程式可以在不同時間實現或虛擬化邏輯介面的元件。

新建立的 Surface 對象處於未初始化的狀態。 雖然未初始化，但介面對可視化樹狀結構的組合沒有任何作用。 其行為與以 100% 透明圖元初始化的介面完全相同。

若要使用像素數據初始化表面，請使用 IDCompositionSurface：：BeginDraw 方法。 這個方法不僅提供表面的圖元，也會配置這些像素的實際儲存空間。 記憶體配置會持續存在，直到應用程式將部分記憶體傳回系統為止。 應用程式可以藉由呼叫 IDComposition：：VirtualSurfaceTrim 方法來釋放部分或所有配置的記憶體。

DirectComposition 表面支持下列像素格式：

• DXGI_FORMAT_B8G8R8A8_UNORM
• DXGI_FORMAT_R8G8B8A8_UNORM
• DXGI_FORMAT_R16G16B16A16_FLOAT

如果 initialWidth 或 initialHeight 超過 16,777,216 像素，這個方法就會失敗。

範例

下列範例示範如何建立虛擬表面，並將其與視覺效果產生關聯。

HRESULT RenderAVisual(IDCompositionDevice *pDCompDevice, HWND hwndTarget,
                         UINT surfaceWidth, UINT surfaceHeight) 
{
    // Validate the input parameters.
    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};

    // Create the rendering target. 
    hr = pDCompDevice->CreateTargetForHwnd(hwndTarget, TRUE, &pTargetWindow);

    if (SUCCEEDED(hr))
    {
        // Create a visual.
        hr = pDCompDevice->CreateVisual(&pVisual);
    }

    if (SUCCEEDED(hr))
    {
        // Add the visual to the root of the composition tree.
        hr = pTargetWindow->SetRoot(pVisual);
    }

    if (SUCCEEDED(hr))
    {
        // Create a virtual surface.
        hr = pDCompDevice->CreateVirtualSurface(surfaceWidth, surfaceHeight, 
            DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_ALPHA_MODE_IGNORE, 
            &pVirtualSurface);
    }

    if (SUCCEEDED(hr))
    {
        // Set the virtual surface as the content of the visual.
        hr = pVisual->SetContent(pVirtualSurface);
    }
    
    if (SUCCEEDED(hr))
    {
        // Retrieve and interface pointer for draw on the surface.
        hr = pVirtualSurface->BeginDraw(NULL, __uuidof(ID3D10Texture2D), 
            (void **) &pTex2D, &offset);
    }

    //
    // TODO: Draw on the surface.
    //
    
    if (SUCCEEDED(hr))
    {
        // Complete the updates to the surface.
        hr = pVirtualSurface->EndDraw();
    }

    // Commit the composition for rendering.
    hr = pDCompDevice->Commit();

    // Clean up.
    SafeRelease(&pTargetWindow);
    SafeRelease(&pVisual);
    SafeRelease(&pVirtualSurface);
    SafeRelease(&pTex2D);

    return hr;

}

規格需求

需求	值
最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
目標平台	Windows
標頭	dcomp.h
程式庫	Dcomp.lib
Dll	Dcomp.dll

另請參閱

IDCompositionDevice

IDCompositionDevice：：CreateSurface