Click or drag to resize
Interop with Direct2D

Win2D is implemented as a layer on top of Direct2D, and supports interop in both directions. If you have a Win2D object, you can access the native Direct2D object that is used to implement it. If you have a Direct2D object, you can look up the Win2D object that wraps it, or create a new wrapper if one did not already exist.

Interop allows you to mix and match Win2D with native DirectX APIs. You can write an app that mostly uses Win2D, but drop down to native DirectX at any point - perhaps to call into some other API or 3rd party component that requires native interfaces. Or your app can be mostly native DirectX, yet you can switch over to Win2D in specific places where you want its extra convenience or C# support.

Interop APIs

C++/CX interop APIs are defined in the header Microsoft.Graphics.Canvas.native.h:

#include <Microsoft.Graphics.Canvas.native.h>

using namespace Microsoft::Graphics::Canvas;

To get the native Direct2D object that is wrapped by a Win2D object:

template<typename T, typename U>
Microsoft::WRL::ComPtr<T> GetWrappedResource(U^ wrapper);

template<typename T, typename U>
Microsoft::WRL::ComPtr<T> GetWrappedResource(CanvasDevice^ device, U^ wrapper);

template<typename T, typename U>
Microsoft::WRL::ComPtr<T> GetWrappedResource(CanvasDevice^ device, U^ wrapper, float dpi);

For most types GetWrappedResource can be called with only a Win2D wrapper object as parameter. For a few types (see below table) it must also be passed a device and/or DPI value. It is not an error to pass a device or DPI when using GetWrappedResource with types that do not require them.

To get a Win2D object wrapping a native Direct2D object:

template<typename WRAPPER>
WRAPPER^ GetOrCreate(IUnknown* resource);

template<typename WRAPPER>
WRAPPER^ GetOrCreate(CanvasDevice^ device, IUnknown* resource);

template<typename WRAPPER>
WRAPPER^ GetOrCreate(ID2D1Device1* device, IUnknown* resource);

template<typename WRAPPER>
WRAPPER^ GetOrCreate(CanvasDevice^ device, IUnknown* resource, float dpi);

template<typename WRAPPER>
WRAPPER^ GetOrCreate(ID2D1Device1* device, IUnknown* resource, float dpi);

GetOrCreate returns an existing wrapper instance if one already exists, or creates a new wrapper if one does not. Calling it repeatedly on the same native object will return the same wrapper each time, as long as that wrapper instance continues to exist. If all references to the wrapper are released such that its reference count goes to zero and it is destroyed, any later call to GetOrCreate will have to create a new wrapper.

For some types GetOrCreate can be called with only a Direct2D resource object as parameter, while for other types (see below table) it must also be passed a device and DPI value. It is not an error to pass a device or DPI when using GetOrCreate with types that do not require them. If a Win2D wrapper already exists, it is ok to omit the device and DPI even for types that would normally need them: these parameters are only used when creating new wrapper instances.

GetOrCreate understands inheritance hierarchies and will always create the appropriate most-derived wrapper type. For instance if you call GetOrCreate<CanvasBitmap>(ID2D1Bitmap1*) with an ID2D1Bitmap1 that has the D2D1_BITMAP_OPTIONS_TARGET flag, the returned wrapper instance will in fact be a CanvasRenderTarget (which derives from CanvasBitmap). The other way around, if you call GetOrCreate<CanvasRenderTarget>(ID2D1Bitmap1*) with an ID2D1Bitmap1 that does not have D2D1_BITMAP_OPTIONS_TARGET, this will throw an invalid cast exception.

Taking this to the extreme, it is valid to call GetOrCreate<Object>(IUnknown*), and also GetWrappedResource<IUnknown>(Object^).

Types that support interop

Win2D type

Direct2D type

GetOrCreate parameters

GetWrappedResource parameters

CanvasBitmapID2D1Bitmap1 without D2D1_BITMAP_OPTIONS_TARGETDevice-
CanvasCachedGeometryID2D1GeometryRealizationDevice-
CanvasCommandListID2D1CommandListDevice-
CanvasDeviceID2D1Device1--
CanvasDrawingSessionID2D1DeviceContext1--
CanvasFontFaceIDWriteFontFaceReference--
CanvasFontSetIDWriteFontSet--
CanvasGeometryID2D1Geometry, or one of its derived interfaces ID2D1PathGeometry, ID2D1RectangleGeometry, ID2D1RoundedRectangleGeometry, ID2D1EllipseGeometry, ID2D1TransformedGeometry, or ID2D1GeometryGroupDevice-
CanvasGradientMeshID2D1GradientMeshDevice-
CanvasImageBrushID2D1BitmapBrush1 (if Image is a CanvasBitmap and SourceRectangle is null) or ID2D1ImageBrush (if Image is any other type of ICanvasImage, or if SourceRectangle is set) DeviceOptional DPI(1)
CanvasLinearGradientBrushID2D1LinearGradientBrushDevice-
CanvasNumberSubstitutionIDWriteNumberSubstitution--
CanvasRadialGradientBrushID2D1RadialGradientBrushDevice-
CanvasRenderTargetID2D1Bitmap1 with D2D1_BITMAP_OPTIONS_TARGETDevice-
CanvasSolidColorBrushID2D1SolidColorBrushDevice-
CanvasStrokeStyleID2D1StrokeStyle1-Device
CanvasSvgDocumentID2D1SvgDocument(2)Device-
CanvasSwapChainIDXGISwapChain1Device, DPI-
CanvasTextFormatIDWriteTextFormat1--
CanvasTextLayoutIDWriteTextLayout3Device-
CanvasTextRenderingParametersIDWriteRenderingParams3--
CanvasTypographyIDWriteTypography--
CanvasVirtualBitmapID2D1ImageSource or ID2D1TransformedImageSourceDevice-
ColorManagementProfileID2D1ColorContextDeviceDevice
EffectTransferTable3DID2D1LookupTable3DDevice-
Microsoft.Graphics.Canvas.Effects.* (multiple Win2D classes map to the same D2D type) ID2D1Effect with the appropriate D2D1_PROPERTY_TYPE_CLSIDDeviceDevice, optional DPI(1)

(1) optional DPI means it is valid to call GetWrappedResource for this type without specifying a DPI value, but if you do specify DPI, Win2D may be able to more efficiently configure effect graphs by leaving out redundant DPI compensation nodes. This applies when calling GetWrappedResource on an effect, or on a CanvasImageBrush that has an effect as its source image.

(2) When a CanvasSvgDocument is produced from an ID2D1SvgDocument using native C++ interop, the ID2D1SvgDocument's viewport size is ignored.

Example
#include <Microsoft.Graphics.Canvas.native.h>
#include <d2d1_2.h>

using namespace Microsoft::Graphics::Canvas;
using namespace Microsoft::WRL;

// Interop Win2D -> Direct2D.
CanvasDevice^ canvasDevice = ...;
CanvasBitmap^ canvasBitmap = ...;

ComPtr<ID2D1Device> nativeDevice = GetWrappedResource<ID2D1Device>(canvasDevice);
ComPtr<ID2D1Bitmap1> nativeBitmap = GetWrappedResource<ID2D1Bitmap1>(canvasBitmap);

// Interop Direct2D -> Win2D.
canvasDevice = GetOrCreate<CanvasDevice>(nativeDevice.Get());
bitmap = GetOrCreate<CanvasBitmap>(canvasDevice, nativeBitmap.Get());