D2D1_RENDER_TARGET_PROPERTIES structure (d2d1.h)

Article
04/02/2021

Contains rendering options (hardware or software), pixel format, DPI information, remoting options, and Direct3D support requirements for a render target.

Syntax

typedef struct D2D1_RENDER_TARGET_PROPERTIES {
  D2D1_RENDER_TARGET_TYPE  type;
  D2D1_PIXEL_FORMAT        pixelFormat;
  FLOAT                    dpiX;
  FLOAT                    dpiY;
  D2D1_RENDER_TARGET_USAGE usage;
  D2D1_FEATURE_LEVEL       minLevel;
} D2D1_RENDER_TARGET_PROPERTIES;

Members

type

Type: D2D1_RENDER_TARGET_TYPE

A value that specifies whether the render target should force hardware or software rendering. A value of D2D1_RENDER_TARGET_TYPE_DEFAULT specifies that the render target should use hardware rendering if it is available; otherwise, it uses software rendering. Note that WIC bitmap render targets do not support hardware rendering.

pixelFormat

Type: D2D1_PIXEL_FORMAT

The pixel format and alpha mode of the render target. You can use the D2D1::PixelFormat function to create a pixel format that specifies that Direct2D should select the pixel format and alpha mode for you. For a list of pixel formats and alpha modes supported by each render target, see Supported Pixel Formats and Alpha Modes.

dpiX

Type: FLOAT

The horizontal DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.

dpiY

Type: FLOAT

The vertical DPI of the render target. To use the default DPI, set dpiX and dpiY to 0. For more information, see the Remarks section.

usage

Type: D2D1_RENDER_TARGET_USAGE

A value that specifies how the render target is remoted and whether it should be GDI-compatible. Set to D2D1_RENDER_TARGET_USAGE_NONE to create a render target that is not compatible with GDI and uses Direct3D command-stream remoting if it is available.

minLevel

Type: D2D1_FEATURE_LEVEL

A value that specifies the minimum Direct3D feature level required for hardware rendering. If the specified minimum level is not available, the render target uses software rendering if the type member is set to D2D1_RENDER_TARGET_TYPE_DEFAULT; if type is set to D2D1_RENDER_TARGET_TYPE_HARDWARE, render target creation fails. A value of D2D1_FEATURE_LEVEL_DEFAULT indicates that Direct2D should determine whether the Direct3D feature level of the device is adequate. This field is used only when creating ID2D1HwndRenderTarget and ID2D1DCRenderTarget objects.

Remarks

Use this structure when creating a render target, or use it with the ID2D1RenderTarget::IsSupported method to check the properties supported by an existing render target.

As a convenience, Direct2D provides the D2D1::RenderTargetProperties helper function for creating D2D1_RENDER_TARGET_PROPERTIES structures. An easy way to create a D2D1_RENDER_TARGET_PROPERTIES structure that works for most render targets is to call the function without specifying any parameters. Doing so creates a D2D1_RENDER_TARGET_PROPERTIES structure that has its fields set to default values. For more information, see D2D1::RenderTargetProperties.

Not all render targets support hardware rendering. For a list, see the Render Targets Overview.

Using Default DPI Settings

To use the default DPI, set dpiX and dpiY to 0. The default DPI varies depending on the render target:

For a compatible render target, the default DPI is the DPI of the parent render target.
For a ID2D1HwndRenderTarget, the default DPI is the system DPI obtained from the render target's ID2D1Factory.
For other render targets, the default DPI is 96.

To use the default DPI setting, both dpiX and dpiY must be set to 0. Setting only one value to 0 causes an E_INVALIDARG error when attempting to create a render target.

Examples

The following example uses the D2D1::RenderTargetProperties function to create a D2D1_RENDER_TARGET_PROPERTIES structure suitable for most render targets.

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
    );

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]
Header	d2d1.h

Share via