ID2D1DeviceContext::SetTarget method (d2d1_1.h)

Article
10/13/2021

The bitmap or command list to which the Direct2D device context will now render.

Syntax

void SetTarget(
  [in, optional] ID2D1Image *image
);

Parameters

[in, optional] image

Type: ID2D1Image*

The surface or command list to which the Direct2D device context will render.

Return value

None

Remarks

The target can be changed at any time, including while the context is drawing.

The target can be either a bitmap created with the D2D1_BITMAP_OPTIONS_TARGET flag, or it can be a command list. Other kinds of images cannot be set as a target. For example, you cannot set the output of an effect as target. If the target is not valid the context will enter the D2DERR_INVALID_TARGET error state.

You cannot use SetTarget to render to a bitmap/command list from multiple device contexts simultaneously. An image is considered “being rendered to” if it has ever been set on a device context within a BeginDraw/EndDraw timespan. If an attempt is made to render to an image through multiple device contexts, all subsequent device contexts after the first will enter an error state.

Callers wishing to attach an image to a second device context should first call EndDraw on the first device context.

Here is an example of the correct calling order.

pDC1->BeginDraw();
pDC1->SetTarget(pImage);
// …
pDC1->EndDraw();

pDC2->BeginDraw();
pDC2->SetTarget(pImage);
// …
pDC2->EndDraw();

Here is an example of the incorrect calling order.

pDC1->BeginDraw();
pDC2->BeginDraw();

pDC1->SetTarget(pImage);

// ...

pDC1->SetTarget(NULL);

pDC2->SetTarget(pImage); // This call is invalid, even though pImage is no longer set on pDC1.

// ...

pDC1->EndDraw(); // This EndDraw SUCCEEDs.
pDC2->EndDraw(); // This EndDraw FAILs

Note Changing the target does not change the bitmap that an HWND render target presents from, nor does it change the bitmap that a DC render target blts to/from.

This API makes it easy for an application to use a bitmap as a source (like in DrawBitmap) and as a destination at the same time. Attempting to use a bitmap as a source on the same device context to which it is bound as a target will put the device context into the D2DERR_BITMAP_BOUND_AS_TARGET error state.

It is acceptable to have a bitmap bound as a target bitmap on multiple render targets at once. Applications that do this must properly synchronize rendering with Flush or EndDraw.

You can change the target at any time, including while the context is drawing.

You can set the target to NULL, in which case drawing calls will put the device context into an error state with D2DERR_WRONG_STATE. Calling SetTarget with a NULL target does not restore the original target bitmap to the device context.

If the device context has an outstanding HDC, the context will enter the D2DERR_WRONG_STATE error state. The target will not be changed.

If the bitmap and the device context are not in the same resource domain, the context will enter \ error state. The target will not be changed.

ID2D1RenderTarget::GetPixelSize returns the size of the current target bitmap (or 0, 0) if there is no bitmap bound). ID2D1RenderTarget::GetSize returns the pixel size of the current bitmap scaled by the DPI of the render target. SetTarget does not affect the DPI of the render target.

ID2D1RenderTarget::GetPixelFormat returns the pixel format of the current target bitmap (or DXGI_FORMAT_UNKNOWN, D2D1_ALPHA_MODE_UNKNOWN if there is none).

ID2D1Bitmap::CopyFromRenderTarget copies from the currently bound target bitmap.

Requirements

Requirement	Value
Minimum supported client	Windows 8 and Platform Update for Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	d2d1_1.h
DLL	D2d1.dll