How to initialize DirectComposition
Note
For apps on Windows 10, we recommend using Windows.UI.Composition APIs instead of DirectComposition. For more info, see Modernize your desktop app using the Visual layer.
This topic demonstrates how to create and initialize the minimum set of Microsoft DirectComposition objects needed to create a simple composition.
What you need to know
Technologies
Prerequisites
- C/C++
- Microsoft Win32
- Component Object Model (COM)
Instructions
Step 1: Create the Direct3D device object
Use the D3D11CreateDevice function from the Microsoft Direct3D API to create an instance of a device object that represents the display adapter.
ID3D11Device *m_pD3D11Device;
D3D_FEATURE_LEVEL featureLevelSupported;
// Create the D3D device object. The D3D11_CREATE_DEVICE_BGRA_SUPPORT
// flag enables rendering on surfaces using Direct2D.
hr = D3D11CreateDevice(
nullptr,
D3D_DRIVER_TYPE_HARDWARE,
NULL,
D3D11_CREATE_DEVICE_BGRA_SUPPORT,
NULL,
0,
D3D11_SDK_VERSION,
&m_pD3D11Device,
&featureLevelSupported,
nullptr);
Step 2: Retrieve a pointer to the DXGI object
Use the QueryInterface method to retrieve the IDXGIDevice pointer from the Direct3D device object. DirectComposition will use the Microsoft DirectX Graphics Infrastructure (DXGI) object to create all surface objects for the DirectComposition device.
IDXGIDevice *pDXGIDevice = nullptr;
// Check the result of calling D3D11CreateDriver.
if (SUCCEEDED(hr))
{
// Create the DXGI device used to create bitmap surfaces.
hr = m_pD3D11Device->QueryInterface(&pDXGIDevice);
}
Step 3: Create the DirectComposition device object
Use the DCompositionCreateDevice function to create an instance of the DirectComposition device object, specifying the IDXGIDevice pointer retrieved in the previous step. The function retrieves an IDCompositionDevice pointer used to create all other DirectComposition objects used in a composition.
IDCompositionDevice *m_pDCompDevice;
if (SUCCEEDED(hr))
{
// Create the DirectComposition device object.
hr = DCompositionCreateDevice(pDXGIDevice,
__uuidof(IDCompositionDevice),
reinterpret_cast<void **>(&m_pDCompDevice));
}
Step 4: Create the composition target object
Use the IDCompositionDevice::CreateTargetForHwnd method to create an instance of the composition target object. Calling CreateTargetForHwnd binds the device object to the application window that will display the composition.
IDCompositionTarget *m_pDCompTarget;
if (SUCCEEDED(hr))
{
// Create the composition target object based on the
// specified application window.
hr = m_pDCompDevice->CreateTargetForHwnd(m_hwnd, TRUE, &m_pDCompTarget);
}
Step 5: Create a visual object
Use the IDCompositionDevice::CreateVisual method to create a visual object. The method retrieves an IDCompositionVisual pointer used to set the properties of the visual. For more information, see Properties of a visual object.
IDCompositionVisual *pVisual = nullptr;
// Create a visual object.
hr = m_pDCompDevice->CreateVisual(&pVisual);
Step 6: Create a composition surface and render a bitmap to the surface
Create an IDCompositionSurface pointer.
IDCompositionSurface *pSurface = nullptr;
if (SUCCEEDED(hr))
{
// Create a composition surface and render a GDI bitmap
// to the surface.
hr = MyCreateGDIRenderedDCompSurface(m_hBitmap, &pSurface);
}
The following function creates a Microsoft DirectComposition surface and draws the bitmap on the surface.
// MyCreateGDIRenderedDCompSurface - Creates a DirectComposition surface and
// copies the bitmap to the surface.
//
// Parameters:
// hBitmap - a GDI bitmap.
// ppSurface - the composition surface object.
//
HRESULT DemoApp::MyCreateGDIRenderedDCompSurface(HBITMAP hBitmap,
IDCompositionSurface **ppSurface)
{
HRESULT hr = S_OK;
int bitmapWidth = 0;
int bitmapHeight = 0;
int bmpSize = 0;
BITMAP bmp = { };
HBITMAP hBitmapOld = NULL;
HDC hSurfaceDC = NULL;
HDC hBitmapDC = NULL;
IDXGISurface1 *pDXGISurface = nullptr;
IDCompositionSurface *pDCSurface = nullptr;
POINT pointOffset = { };
if (ppSurface == nullptr)
return E_INVALIDARG;
// Get information about the bitmap.
bmpSize = GetObject(hBitmap, sizeof(BITMAP), &bmp);
hr = bmpSize ? S_OK : E_FAIL;
if (SUCCEEDED(hr))
{
// Save the bitmap dimensions.
bitmapWidth = bmp.bmWidth;
bitmapHeight = bmp.bmHeight;
// Create a DirectComposition-compatible surface that is the same size
// as the bitmap. The DXGI_FORMAT_B8G8R8A8_UNORM flag is required for
// rendering on the surface using GDI via GetDC.
hr = m_pDCompDevice->CreateSurface(bitmapWidth, bitmapHeight,
DXGI_FORMAT_B8G8R8A8_UNORM, DXGI_ALPHA_MODE_IGNORE, &pDCSurface);
}
if (SUCCEEDED(hr))
{
// Begin rendering to the surface.
hr = pDCSurface->BeginDraw(NULL, __uuidof(IDXGISurface1),
reinterpret_cast<void**>(&pDXGISurface), &pointOffset);
}
if (SUCCEEDED(hr))
{
// Get the device context (DC) for the surface.
hr = pDXGISurface->GetDC(FALSE, &hSurfaceDC);
}
if (SUCCEEDED(hr))
{
// Create a compatible DC and select the surface
// into the DC.
hBitmapDC = CreateCompatibleDC(hSurfaceDC);
if (hBitmapDC != NULL)
{
hBitmapOld = (HBITMAP)SelectObject(hBitmapDC, hBitmap);
BitBlt(hSurfaceDC, pointOffset.x, pointOffset.y,
bitmapWidth, bitmapHeight, hBitmapDC, 0, 0, SRCCOPY);
if (hBitmapOld)
{
SelectObject(hBitmapDC, hBitmapOld);
}
DeleteDC(hBitmapDC);
}
pDXGISurface->ReleaseDC(NULL);
}
// End the rendering.
pDCSurface->EndDraw();
*ppSurface = pDCSurface;
// Call an application-defined macro to free the surface pointer.
SafeRelease(&pDXGISurface);
return hr;
}
Step 7: Bind surface to visual and set the properties of the visual object
Call the methods of the visual object's IDCompositionVisual interface to set the properties of the visual.
This next example sets the bitmap content for the visual, and the horizontal and vertical position of the visual relative to upper-left corner of its container. Because it is the root visual, the container for this visual is the composition target window.
if (SUCCEEDED(hr))
{
// Set the bitmap content of the visual.
hr = pVisual->SetContent(pSurface);
}
if (SUCCEEDED(hr))
{
// Set the horizontal and vertical position of the visual relative
// to the upper-left corner of the composition target window.
hr = pVisual->SetOffsetX(xOffset);
if (SUCCEEDED(hr))
{
hr = pVisual->SetOffsetY(yOffset);
}
}
Step 8: Set the root visual of the visual tree
Set the root visual of the visual tree by calling the IDCompositionTarget::SetRoot method.
if (SUCCEEDED(hr))
{
// Set the visual to be the root of the visual tree.
hr = m_pDCompTarget->SetRoot(pVisual);
}
Step 9: Commit the composition
Call the IDCompositionDevice::Commit method to commit the batch of commands to DirectComposition for processing. The resulting composition appears in the target window.
if (SUCCEEDED(hr))
{
// Commit the visual to be composed and displayed.
hr = m_pDCompDevice->Commit();
}
Step 10: Free the DirectComposition objects
It is good programming practice to free any visual objects as soon as you no longer need them. The following example calls the application-defined SafeRelease macro to free the visual object.
// Free the visual.
SafeRelease(&pVisual);
Also, remember to free the DXGI object, the device object, and composition target object before your application exits.
SafeRelease(&pDXGIDevice);
SafeRelease(&m_pDCompDevice);
SafeRelease(&m_pDCompTarget);
SafeRelease(&m_pD3D11Device);
Complete example
//
// SimpleComposition.h
//
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (c) Microsoft Corporation. All rights reserved
#pragma once
// Modify the following definitions if you need to target a platform prior to the ones specified below.
// Refer to MSDN for the latest info on corresponding values for different platforms.
#ifndef WINVER // Allow use of features specific to Windows 7 or later.
#define WINVER 0x0700 // Change this to the appropriate value to target other versions of Windows.
#endif
#ifndef _WIN32_WINNT // Allow use of features specific to Windows 7 or later.
#define _WIN32_WINNT 0x0700 // Change this to the appropriate value to target other versions of Windows.
#endif
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN // Exclude rarely-used items from Windows headers
// Windows Header Files:
#include <windows.h>
// C RunTime Header Files
#include <math.h>
// DirectComposition Header Files
#include <dcomp.h>
// Direct3D Header Files
#include <d3d11.h>
/******************************************************************
* *
* Macros *
* *
******************************************************************/
template<class Interface>
inline void
SafeRelease(
Interface **ppInterfaceToRelease
)
{
if (*ppInterfaceToRelease != NULL)
{
(*ppInterfaceToRelease)->Release();
(*ppInterfaceToRelease) = NULL;
}
}
#ifndef HINST_THISCOMPONENT
EXTERN_C IMAGE_DOS_HEADER __ImageBase;
#define HINST_THISCOMPONENT ((HINSTANCE)&__ImageBase)
#endif
/******************************************************************
* *
* DemoApp *
* *
******************************************************************/
class DemoApp
{
public:
DemoApp();
~DemoApp();
HRESULT Initialize();
void RunMessageLoop();
private:
HRESULT InitializeDirectCompositionDevice();
HRESULT CreateResources();
void DiscardResources();
HRESULT OnClientClick();
HRESULT LoadResourceGDIBitmap(
PCWSTR resourceName,
HBITMAP &hbmp
);
HRESULT MyCreateGDIRenderedDCompSurface(HBITMAP hBitmap,
IDCompositionSurface **ppSurface);
static LRESULT CALLBACK WndProc(
HWND hWnd,
UINT message,
WPARAM wParam,
LPARAM lParam
);
private:
HWND m_hwnd;
HBITMAP m_hBitmap;
ID3D11Device *m_pD3D11Device;
IDCompositionDevice *m_pDCompDevice;
IDCompositionTarget *m_pDCompTarget;
};
//
// SimpleComposition.cpp
//
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (c) Microsoft Corporation. All rights reserved
// Instructions: Right-click in the client area to cause DirectCompostion
// to create a simple composition consisting of a single GDI bitmap.
#include "SimpleComposition.h"
/******************************************************************
* *
* The application entry point. *
* *
******************************************************************/
int WINAPI WinMain(
HINSTANCE /* hInstance */,
HINSTANCE /* hPrevInstance */,
LPSTR /* lpCmdLine */,
int /* nCmdShow */
)
{
// Ignore the return value because we want to run the program even in the
// unlikely event that HeapSetInformation fails.
HeapSetInformation(NULL, HeapEnableTerminationOnCorruption, NULL, 0);
if (SUCCEEDED(CoInitialize(NULL)))
{
{
DemoApp app;
if (SUCCEEDED(app.Initialize()))
{
app.RunMessageLoop();
}
}
CoUninitialize();
}
return 0;
}
/******************************************************************
* *
* DemoApp::DemoApp constructor *
* *
* Initialize member data. *
* *
******************************************************************/
DemoApp::DemoApp() :
m_hwnd(NULL),
m_hBitmap(NULL),
m_pDCompDevice(nullptr),
m_pDCompTarget(nullptr),
m_pD3D11Device(nullptr)
{
}
/******************************************************************
* *
* Release resources. *
* *
******************************************************************/
DemoApp::~DemoApp()
{
SafeRelease(&m_pDCompDevice);
SafeRelease(&m_pDCompTarget);
SafeRelease(&m_pD3D11Device);
}
/*******************************************************************
* *
* Create the application window. *
* *
*******************************************************************/
HRESULT DemoApp::Initialize()
{
HRESULT hr;
// Register the window class.
WNDCLASSEX wcex = { sizeof(WNDCLASSEX) };
wcex.style = CS_HREDRAW | CS_VREDRAW;
wcex.lpfnWndProc = DemoApp::WndProc;
wcex.cbClsExtra = 0;
wcex.cbWndExtra = sizeof(LONG_PTR);
wcex.hInstance = HINST_THISCOMPONENT;
wcex.hbrBackground = (HBRUSH)(COLOR_WINDOW+1);;
wcex.lpszMenuName = nullptr;
wcex.hCursor = LoadCursor(NULL, IDC_ARROW);
wcex.lpszClassName = L"DirectCompDemoApp";
RegisterClassEx(&wcex);
// Create the application window.
//
// Because the CreateWindow function takes its size in pixels, we
// obtain the system DPI and use it to scale the window size.
int dpiX = 0;
int dpiY = 0;
HDC hdc = GetDC(NULL);
if (hdc)
{
dpiX = GetDeviceCaps(hdc, LOGPIXELSX);
dpiY = GetDeviceCaps(hdc, LOGPIXELSY);
ReleaseDC(NULL, hdc);
}
m_hwnd = CreateWindow(
L"DirectCompDemoApp",
L"DirectComposition Demo Application",
WS_OVERLAPPEDWINDOW,
CW_USEDEFAULT,
CW_USEDEFAULT,
static_cast<UINT>(ceil(640.f * dpiX / 96.f)),
static_cast<UINT>(ceil(480.f * dpiY / 96.f)),
NULL,
NULL,
HINST_THISCOMPONENT,
this
);
hr = m_hwnd ? S_OK : E_FAIL;
if (SUCCEEDED(hr))
{
ShowWindow(m_hwnd, SW_SHOWNORMAL);
UpdateWindow(m_hwnd);
// Initialize DirectComposition resources, such as the
// device object and composition target object.
hr = InitializeDirectCompositionDevice();
}
if (SUCCEEDED(hr))
{
hr = CreateResources();
}
return hr;
}
/******************************************************************
* *
* This method creates the DirectComposition device object and *
* and the composition target object. These objects endure for *
* the lifetime of the application. *
* *
******************************************************************/
HRESULT DemoApp::InitializeDirectCompositionDevice()
{
HRESULT hr = S_OK;
D3D_FEATURE_LEVEL featureLevelSupported;
// Create the D3D device object. The D3D11_CREATE_DEVICE_BGRA_SUPPORT
// flag enables rendering on surfaces using Direct2D.
hr = D3D11CreateDevice(
nullptr,
D3D_DRIVER_TYPE_HARDWARE,
NULL,
D3D11_CREATE_DEVICE_BGRA_SUPPORT,
NULL,
0,
D3D11_SDK_VERSION,
&m_pD3D11Device,
&featureLevelSupported,
nullptr);
IDXGIDevice *pDXGIDevice = nullptr;
// Check the result of calling D3D11CreateDriver.
if (SUCCEEDED(hr))
{
// Create the DXGI device used to create bitmap surfaces.
hr = m_pD3D11Device->QueryInterface(&pDXGIDevice);
}
if (SUCCEEDED(hr))
{
// Create the DirectComposition device object.
hr = DCompositionCreateDevice(pDXGIDevice,
__uuidof(IDCompositionDevice),
reinterpret_cast<void **>(&m_pDCompDevice));
}
if (SUCCEEDED(hr))
{
// Create the composition target object based on the
// specified application window.
hr = m_pDCompDevice->CreateTargetForHwnd(m_hwnd, TRUE, &m_pDCompTarget);
}
SafeRelease(&pDXGIDevice);
return hr;
}
/******************************************************************
* *
* This method creates the GDI bitmap that the application gives *
* to DirectComposition to be composed. *
* *
******************************************************************/
HRESULT DemoApp::CreateResources()
{
HRESULT hr = S_OK;
hr = LoadResourceGDIBitmap(L"Logo", m_hBitmap);
return hr;
}
/******************************************************************
* *
* Discard device-specific resources. *
* *
******************************************************************/
void DemoApp::DiscardResources()
{
DeleteObject(m_hBitmap);
}
/******************************************************************
* *
* The main window's message loop. *
* *
******************************************************************/
void DemoApp::RunMessageLoop()
{
MSG msg;
while (GetMessage(&msg, NULL, 0, 0))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}
/******************************************************************
* *
* Called whenever the user clicks in client area of the main *
* window. This method builds a simple visual tree and passes it *
* to DirectComposition.
* *
******************************************************************/
HRESULT DemoApp::OnClientClick()
{
HRESULT hr = S_OK;
float xOffset = 20; // horizonal position of visual
float yOffset = 20; // vertical position of visual
IDCompositionVisual *pVisual = nullptr;
// Create a visual object.
hr = m_pDCompDevice->CreateVisual(&pVisual);
IDCompositionSurface *pSurface = nullptr;
if (SUCCEEDED(hr))
{
// Create a composition surface and render a GDI bitmap
// to the surface.
hr = MyCreateGDIRenderedDCompSurface(m_hBitmap, &pSurface);
}
if (SUCCEEDED(hr))
{
// Set the bitmap content of the visual.
hr = pVisual->SetContent(pSurface);
}
if (SUCCEEDED(hr))
{
// Set the horizontal and vertical position of the visual relative
// to the upper-left corner of the composition target window.
hr = pVisual->SetOffsetX(xOffset);
if (SUCCEEDED(hr))
{
hr = pVisual->SetOffsetY(yOffset);
}
}
if (SUCCEEDED(hr))
{
// Set the visual to be the root of the visual tree.
hr = m_pDCompTarget->SetRoot(pVisual);
}
if (SUCCEEDED(hr))
{
// Commit the visual to be composed and displayed.
hr = m_pDCompDevice->Commit();
}
// Free the visual.
SafeRelease(&pVisual);
return hr;
}
/******************************************************************
* *
* The window's message handler. *
* *
******************************************************************/
LRESULT CALLBACK DemoApp::WndProc(HWND hwnd, UINT message,
WPARAM wParam, LPARAM lParam)
{
LRESULT result = 0;
if (message == WM_CREATE)
{
LPCREATESTRUCT pcs = (LPCREATESTRUCT)lParam;
DemoApp *pDemoApp = (DemoApp *)pcs->lpCreateParams;
::SetWindowLongPtrW(
hwnd,
GWLP_USERDATA,
PtrToUlong(pDemoApp)
);
result = 1;
}
else
{
DemoApp *pDemoApp = reinterpret_cast<DemoApp *>(static_cast<LONG_PTR>(
::GetWindowLongPtrW(
hwnd,
GWLP_USERDATA
)));
bool wasHandled = false;
if (pDemoApp)
{
switch (message)
{
case WM_LBUTTONDOWN:
{
pDemoApp->OnClientClick();
}
wasHandled = true;
result = 0;
break;
case WM_DISPLAYCHANGE:
{
InvalidateRect(hwnd, NULL, FALSE);
}
wasHandled = true;
result = 0;
break;
case WM_DESTROY:
{
PostQuitMessage(0);
pDemoApp->DiscardResources();
}
wasHandled = true;
result = 1;
break;
}
}
if (!wasHandled)
{
result = DefWindowProc(hwnd, message, wParam, lParam);
}
}
return result;
}
/******************************************************************
* *
* This method loads the specified GDI bitmap from the *
* application resources, creates a new bitmap that is in a *
* format that DirectComposition can use, and copies the contents *
* of the original bitmap to the new bitmap. *
* *
******************************************************************/
HRESULT DemoApp::LoadResourceGDIBitmap(PCWSTR resourceName, HBITMAP &hbmp)
{
hbmp = static_cast<HBITMAP>(LoadImageW(HINST_THISCOMPONENT, resourceName,
IMAGE_BITMAP, 0, 0, LR_DEFAULTCOLOR));
return hbmp ? S_OK : E_FAIL;
}
// MyCreateGDIRenderedDCompSurface - Creates a DirectComposition surface and
// copies the bitmap to the surface.
//
// Parameters:
// hBitmap - a GDI bitmap.
// ppSurface - the composition surface object.
//
HRESULT DemoApp::MyCreateGDIRenderedDCompSurface(HBITMAP hBitmap,
IDCompositionSurface **ppSurface)
{
HRESULT hr = S_OK;
int bitmapWidth = 0;
int bitmapHeight = 0;
int bmpSize = 0;
BITMAP bmp = { };
HBITMAP hBitmapOld = NULL;
HDC hSurfaceDC = NULL;
HDC hBitmapDC = NULL;
IDXGISurface1 *pDXGISurface = nullptr;
IDCompositionSurface *pDCSurface = nullptr;
POINT pointOffset = { };
if (ppSurface == nullptr)
return E_INVALIDARG;
// Get information about the bitmap.
bmpSize = GetObject(hBitmap, sizeof(BITMAP), &bmp);
hr = bmpSize ? S_OK : E_FAIL;
if (SUCCEEDED(hr))
{
// Save the bitmap dimensions.
bitmapWidth = bmp.bmWidth;
bitmapHeight = bmp.bmHeight;
// Create a DirectComposition-compatible surface that is the same size
// as the bitmap. The DXGI_FORMAT_B8G8R8A8_UNORM flag is required for
// rendering on the surface using GDI via GetDC.
hr = m_pDCompDevice->CreateSurface(bitmapWidth, bitmapHeight,
DXGI_FORMAT_B8G8R8A8_UNORM, DXGI_ALPHA_MODE_IGNORE, &pDCSurface);
}
if (SUCCEEDED(hr))
{
// Begin rendering to the surface.
hr = pDCSurface->BeginDraw(NULL, __uuidof(IDXGISurface1),
reinterpret_cast<void**>(&pDXGISurface), &pointOffset);
}
if (SUCCEEDED(hr))
{
// Get the device context (DC) for the surface.
hr = pDXGISurface->GetDC(FALSE, &hSurfaceDC);
}
if (SUCCEEDED(hr))
{
// Create a compatible DC and select the surface
// into the DC.
hBitmapDC = CreateCompatibleDC(hSurfaceDC);
if (hBitmapDC != NULL)
{
hBitmapOld = (HBITMAP)SelectObject(hBitmapDC, hBitmap);
BitBlt(hSurfaceDC, pointOffset.x, pointOffset.y,
bitmapWidth, bitmapHeight, hBitmapDC, 0, 0, SRCCOPY);
if (hBitmapOld)
{
SelectObject(hBitmapDC, hBitmapOld);
}
DeleteDC(hBitmapDC);
}
pDXGISurface->ReleaseDC(NULL);
}
// End the rendering.
pDCSurface->EndDraw();
*ppSurface = pDCSurface;
// Call an application-defined macro to free the surface pointer.
SafeRelease(&pDXGISurface);
return hr;
}
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for