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_OPTIONSOptions 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
D2D1_BITMAP_OPTIONS.ID2D1Bitmap1
ID2D1DeviceContext::SetTargetSurface
Send comments about this topic to Microsoft
Build date: 9/5/2012