ID2D1RenderTarget::CreateCompatibleRenderTarget method

Creates a bitmap render target for use during intermediate offscreen drawing that is compatible with the current render target.

Syntax


virtual HRESULT CreateCompatibleRenderTarget(
  [in, optional]  D2D1_SIZE_F *desiredSize,
  [in, optional]  D2D1_SIZE_U *desiredPixelSize,
  [in, optional]  D2D1_PIXEL_FORMAT *desiredFormat,
  D2D1_COMPATIBLE_RENDER_TARGET_OPTIONS options,
  [out]           ID2D1BitmapRenderTarget **bitmapRenderTarget
) = 0;

Parameters

desiredSize [in, optional]

Type: D2D1_SIZE_F*

The desired size of the new render target in device-independent pixels if it should be different from the original render target, or NULL. For more information, see the Remarks section.

desiredPixelSize [in, optional]

Type: D2D1_SIZE_U*

The desired size of the new render target in pixels if it should be different from the original render target, or NULL. For more information, see the Remarks section.

desiredFormat [in, optional]

Type: D2D1_PIXEL_FORMAT*

The desired pixel format and alpha mode of the new render target, or NULL. If the pixel format is set to DXGI_FORMAT_UNKNOWN or if this parameter is null, the new render target uses the same pixel format as the original render target. If the alpha mode is D2D1_ALPHA_MODE_UNKNOWN or this parameter is NULL, the alpha mode of the new render target defaults to D2D1_ALPHA_MODE_PREMULTIPLIED. For information about supported pixel formats, see Supported Pixel Formats and Alpha Modes.

options

Type: D2D1_COMPATIBLE_RENDER_TARGET_OPTIONS

A value that specifies whether the new render target must be compatible with GDI.

bitmapRenderTarget [out]

Type: ID2D1BitmapRenderTarget**

When this method returns, contains the address of a pointer to a new bitmap render target. This parameter is passed uninitialized.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This method creates a render target that can be used for intermediate offscreen drawing. The intermediate render target is created in the same location (on the same adapter or in system memory) as the original render target, which allows efficient rendering of the intermediate results to the final target. The DPI, bit depth, pixel format (with the exception of alpha mode), and color space all default to those of the original render target.

The pixel size and DPI of the new render target can be modified by specifying values for desiredSize or desiredPixelSize:

  • If desiredSize is specified but desiredPixelSize is not, the pixel size is computed from the desired size using the parent target DPI. If the desiredSize maps to a integer-pixel size, the DPI of the compatible render target is the same as the DPI of the parent target. If desiredSize maps to a fractional-pixel size, the pixel size is rounded up to the nearest integer and the DPI for the compatible render target is slightly higher than the DPI of the parent render target. In all cases, the coordinate (desiredSize.width, desiredSize.height) maps to the lower-right corner of the compatible render target.
  • If the desiredPixelSize is specified and desiredSize is not, the DPI of the new render target is the same as the original render target.
  • If both desiredSize and desiredPixelSize are specified, the DPI of the new render target is computed to account for the difference in scale.
  • If neither desiredSize nor desiredPixelSize is specified, the new render target size and DPI match the original render target.

Requirements

Minimum supported client

Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | Windows Store apps]

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Header

D2d1.h

Library

D2d1.lib

DLL

D2d1.dll

See also

ID2D1RenderTarget

 

 

Community Additions

ADD
Show:
© 2014 Microsoft