The bitmap or command list to which the Direct2D device context will now render.
- target [in, optional]
The surface or command list to which the Direct2D device context will render.
This method does not return a value.
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
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.
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.
ID2D1Bitmap::CopyFromRenderTarget copies from the currently bound target bitmap.
Minimum supported client
|Windows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps]|
Minimum supported server
|Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps | Windows Store apps]|
Minimum supported phone
|Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]|