ID2D1HwndRenderTarget interface (d2d1.h)

Article
07/27/2022

Renders drawing instructions to a window.

Inheritance

The ID2D1HwndRenderTarget interface inherits from ID2D1RenderTarget. ID2D1HwndRenderTarget also has these types of members:

Methods

Methods

The ID2D1HwndRenderTarget interface has these methods.


ID2D1HwndRenderTarget::CheckWindowState Indicates whether the HWND associated with this render target is occluded.
ID2D1HwndRenderTarget::GetHwnd Returns the HWND associated with this render target.
ID2D1HwndRenderTarget::Resize Changes the size of the render target to the specified pixel size. (overload 2/2)
ID2D1HwndRenderTarget::Resize Changes the size of the render target to the specified pixel size. (overload 1/2)

Remarks

As is the case with other render targets, you must call BeginDraw before issuing drawing commands. After you've finished drawing, call EndDraw to indicate that drawing is finished and to release access to the buffer backing the render target.

For ID2D1HwndRenderTarget, the only side effect of BeginDraw is changing the state of the render target to allow drawing commands to be issued.

EndDraw flushes any batched drawing commands. If no errors have occurred, then it also presents the buffer, causing it to appear on the associated window. Finally, EndDraw returns the HRESULT of the first error that occurred in drawing or presenting, as well as the tag state at the time the error occurred.

ID2D1HwndRenderTarget objects are double buffered, so drawing commands issued do not appear immediately, but rather are performed on an offscreen surface. When EndDraw is called, if there have been no rendering errors, the offscreen buffer is presented. If there have been rendering errors in the batch flushed by EndDraw, then the buffer is not presented, and the application must call BeginDraw and re-draw the frame. Flush can be used to check for errors before calling EndDraw if an application wants the frame to be presented regardless of errors.

A hardware render target's back-buffer is the size specified by GetPixelSize. If EndDraw presents the buffer, this bitmap is stretched to cover the surface where it is presented: the entire client area of the window. This stretch is performed using bilinear filtering if the render target is rendering in hardware and using nearest-neighbor filtering if the rendering target is using software. (Typically, an application will call Resize to ensure the pixel size of the render target and the pixel size of the destination match, and no scaling is necessary, though this is not a requirement.)

In the case where a window straddles adapters, Direct2D ensures that the portion of the off-screen render target is copied from the adapter where rendering is occurring to the adapter that needs to display the contents.

If the adapter a render target is on has been removed or the driver upgraded while the application is running, this is returned as an error in the EndDraw call. In this case, the application should create a new render target and resources as necessary.

Creating ID2D1HwndRenderTarget Objects

To create an ID2D1HwndRenderTarget, use the ID2D1Factory::CreateHwndRenderTarget method.

Your application should create render targets once and hold onto them for the life of the application or until the render target's EndDraw method returns the D2DERR_RECREATE_TARGET error. When you receive this error, you need to recreate the render target (and any resources it created).

Examples

The following example uses the CreateHwndRenderTarget method to create an ID2D1HwndRenderTarget.

RECT rc;
GetClientRect(m_hwnd, &rc);

D2D1_SIZE_U size = D2D1::SizeU(
    rc.right - rc.left,
    rc.bottom - rc.top
    );

// Create a Direct2D render target.
hr = m_pD2DFactory->CreateHwndRenderTarget(
    D2D1::RenderTargetProperties(),
    D2D1::HwndRenderTargetProperties(m_hwnd, size),
    &m_pRenderTarget
    );

The next example uses the ID2D1HwndRenderTarget to draw text to the window.

//  Called whenever the application needs to display the client
//  window. This method writes "Hello, World"
//
//  Note that this function will automatically discard device-specific
//  resources if the Direct3D device disappears during function
//  invocation, and will recreate the resources the next time it's
//  invoked.
//
HRESULT DemoApp::OnRender()
{
    HRESULT hr;

    hr = CreateDeviceResources();

    if (SUCCEEDED(hr))
    {
        static const WCHAR sc_helloWorld[] = L"Hello, World!";

        // Retrieve the size of the render target.
        D2D1_SIZE_F renderTargetSize = m_pRenderTarget->GetSize();

        m_pRenderTarget->BeginDraw();

        m_pRenderTarget->SetTransform(D2D1::Matrix3x2F::Identity());

        m_pRenderTarget->Clear(D2D1::ColorF(D2D1::ColorF::White));

        m_pRenderTarget->DrawText(
            sc_helloWorld,
            ARRAYSIZE(sc_helloWorld) - 1,
            m_pTextFormat,
            D2D1::RectF(0, 0, renderTargetSize.width, renderTargetSize.height),
            m_pBlackBrush
            );

        hr = m_pRenderTarget->EndDraw();

        if (hr == D2DERR_RECREATE_TARGET)
        {
            hr = S_OK;
            DiscardDeviceResources();
        }
    }

    return hr;
}

Code has been omitted from this example.

Requirements

Requirement	Value
Minimum supported client	Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	d2d1.h

Share via