ID2D1DeviceContext::CreateCompatibleBitmap method

Applies to: desktop apps | Windows Store apps

Creates an offscreen surface.

Syntax

HRESULT CreateCompatibleBitmap(
  [in, optional]  const D2D1_SIZE_F *desiredSize,
  [in, optional]  const D2D1_SIZE_U *desiredPixelSize,
  [in, optional]  const D2D1_PIXEL_FORMAT *desiredFormat,
  D2D1_BITMAP_OPTIONS options,
  [out]           ID2D1Bitmap1 **compatibleBitmap
);

Parameters

  • desiredSize [in, optional]
    Type: const D2D1_SIZE_F*

    The size in device-independent pixels (DIPs) of the bitmap to be created.

  • desiredPixelSize [in, optional]
    Type: const D2D1_SIZE_U*

    The size in pixels of the bitmap to be created.

  • desiredFormat [in, optional]
    Type: const D2D1_PIXEL_FORMAT*

    The pixel format of the bitmap to be created.

  • options
    Type: D2D1_BITMAP_OPTIONS

    Options used to create the bitmap.

  • compatibleBitmap [out]
    Type: ID2D1Bitmap1**

    When this method returns, contains the address of a pointer to a new bitmap object.

Return value

Type: HRESULT

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

HRESULT Description
S_OK No error occurred.
E_OUTOFMEMORY Direct2D could not allocate sufficient memory to complete the call.
E_INVALIDARG An invalid value was passed to the method.
D3DERR_OUTOFVIDEOMEMORY Direct3D does not have enough display memory to perform the operation.

 

Remarks

This is directly equivalent to calling ID2D1RenderTarget::CreateCompatibleRenderTarget except that the returned object is a target bitmap that can be set into the device context through SetTarget.

The new bitmap can be used as a target for SetTarget if it is created with D2D1_BITMAP_OPTIONS_TARGET.

If a bitmap is currently not selected in the render target, the pixel size of the device context will be set to (0, 0) and the pixel format will be set to DXGI_FORMAT_UNKNOWN, and DXGI_ALPHA_MODE_UNKNOWN. The DPI of the device context is independent to the currently selected bitmap.

If neither the pixel size nor the DIP size is specified, the compatible bitmap will be the same size as the current target surface and will have the same DPI.

If both the pixel size and the DIP size are specified, the DPI will be calculated from both values.

If only the pixel size is specified, the new bitmap will have the same DPI as the context and the DIP size will be derived from the two values.

If only the DIP size is specified, the pixel size is calculated from the context's DPI, the pixel size is rounded up to the next whole pixel and then the DPI is recalculated from the combination of the DIP and pixel size. This behavior is useful for defining DIP-sized tiles that will receive vector content.

If the pixel size is (0, 0), then the DPI is the context DPI and the DIP size is also (0, 0).

If the pixel format is not specified, the alpha mode is considered to be D2D1_ALPHA_MODE_PREMULTIPLIED and the DXGI_FORMAT is inherited from the current target surface.

If the pixel format is DXGI_FORMAT_UNKNOWN, then the call fails.

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Header

D2d1.h

DLL

D2d1.dll

See also

ID2D1DeviceContext

D2D1_SIZE_F

D2D1_SIZE_U

D2D1_PIXEL_FORMAT

D2D1_BITMAP_OPTIONS.ID2D1Bitmap1

ID2D1DeviceContext::SetTargetSurface

 

 

Send comments about this topic to Microsoft

Build date: 9/5/2012