ID2D1RenderTarget::CreateSharedBitmap method (d2d1.h)

Article
10/13/2021

Creates an ID2D1Bitmap whose data is shared with another resource.

Syntax

HRESULT CreateSharedBitmap(
                 REFIID                       riid,
  [in, out]      void                         *data,
  [in, optional] const D2D1_BITMAP_PROPERTIES *bitmapProperties,
  [out]          ID2D1Bitmap                  **bitmap
);

Parameters

riid

Type: REFIID

The interface ID of the object supplying the source data.

[in, out] data

Type: void*

An ID2D1Bitmap, IDXGISurface, or an IWICBitmapLock that contains the data to share with the new ID2D1Bitmap. For more information, see the Remarks section.

[in, optional] bitmapProperties

Type: D2D1_BITMAP_PROPERTIES*

The pixel format and DPI of the bitmap to create . The DXGI_FORMAT portion of the pixel format must match the DXGI_FORMAT of data or the method will fail, but the alpha modes don't have to match. To prevent a mismatch, you can pass NULL or the value obtained from the D2D1::PixelFormat helper function. The DPI settings do not have to match those of data. If both dpiX and dpiY are 0.0f, the DPI of the render target is used.

[out] bitmap

Type: ID2D1Bitmap**

When this method returns, contains the address of a pointer to the new bitmap. 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

The CreateSharedBitmap method is useful for efficiently reusing bitmap data and can also be used to provide interoperability with Direct3D.

Sharing an ID2D1Bitmap

By passing an ID2D1Bitmap created by a render target that is resource-compatible, you can share a bitmap with that render target; both the original ID2D1Bitmap and the new ID2D1Bitmap created by this method will point to the same bitmap data. For more information about when render target resources can be shared, see the Sharing Render Target Resources section of the Resources Overview.

You may also use this method to reinterpret the data of an existing bitmap and specify a new DPI or alpha mode. For example, in the case of a bitmap atlas, an ID2D1Bitmap may contain multiple sub-images, each of which should be rendered with a different D2D1_ALPHA_MODE (D2D1_ALPHA_MODE_PREMULTIPLIED or D2D1_ALPHA_MODE_IGNORE). You could use the CreateSharedBitmap method to reinterpret the bitmap using the desired alpha mode without having to load a separate copy of the bitmap into memory.

Sharing an IDXGISurface

When using a DXGI surface render target (an ID2D1RenderTarget object created by the CreateDxgiSurfaceRenderTarget method), you can pass an IDXGISurface surface to the CreateSharedBitmap method to share video memory with Direct3D and manipulate Direct3D content as an ID2D1Bitmap. As described in the Resources Overview, the render target and the IDXGISurface must be using the same Direct3D device.

Note also that the IDXGISurface must use one of the supported pixel formats and alpha modes described in Supported Pixel Formats and Alpha Modes.

For more information about interoperability with Direct3D, see the Direct2D and Direct3D Interoperability Overview.

Sharing an IWICBitmapLock

An IWICBitmapLock stores the content of a WIC bitmap and shields it from simultaneous accesses. By passing an IWICBitmapLock to the CreateSharedBitmap method, you can create an ID2D1Bitmap that points to the bitmap data already stored in the IWICBitmapLock.

To use an IWICBitmapLock with the CreateSharedBitmap method, the render target must use software rendering. To force a render target to use software rendering, set to D2D1_RENDER_TARGET_TYPE_SOFTWARE the type field of the D2D1_RENDER_TARGET_PROPERTIES structure that you use to create the render target. To check whether an existing render target uses software rendering, use the IsSupported method.

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]
Target Platform	Windows
Header	d2d1.h
Library	D2d1.lib
DLL	D2d1.dll