What's New in Direct2D

[This documentation is preliminary and is subject to change.]

Changes have been made in the Direct2D API to improve functionality and to disambiguate certain components. This overview describes the changes that will cause certain code that is based on the Beta Microsoft Windows Software Development Kit (SDK) to no longer work. It contains the following sections.

  • Modifications to D2D1_RENDER_TARGET_PROPERTIES and Related Types
    • Beta Version
    • RC Version
  • Modifications to the FillOpacityMask Method
    • Beta Version
    • RC Version
  • Modifications to the D2D1_DRAW_TEXT_OPTIONS Enumeration
    • Beta Version
    • RC Version
  • What's New in the DirectWrite API

To improve the separation of render target types and usages and to enable feature discovery, the D2D1_RENDER_TARGET_PROPERTIES structure and D2D1_RENDER_TARGET_USAGE flags have changed from Beta to RC.

Beta Version

typedef enum D2D1_RENDER_TARGET_USAGE
{
        D2D1_RENDER_TARGET_USAGE_NONE = 0x00000000,
        D2D1_RENDER_TARGET_USAGE_FORCE_BITMAP_REMOTING = 0x00000001,
        D2D1_RENDER_TARGET_USAGE_FORCE_HARDWARE_RENDERING = 0x00000002,
        D2D1_RENDER_TARGET_USAGE_FORCE_SOFTWARE_RENDERING = 0x00000004,
        D2D1_RENDER_TARGET_USAGE_GDI_COMPATIBLE = 0x00000008,
        D2D1_RENDER_TARGET_USAGE_FORCE_DWORD = 0xffffffff

} D2D1_RENDER_TARGET_USAGE;

typedef struct D2D1_RENDER_TARGET_PROPERTIES
{
    D2D1_RENDER_TARGET_USAGE usage;
    D2D1_PIXEL_FORMAT pixelFormat;
    FLOAT dpiX;
    FLOAT dpiY;

} D2D1_RENDER_TARGET_PROPERTIES;

RC Version

The modified D2D1_RENDER_TARGET_PROPERTIES structure has two new members: type and minLevel.

typedef struct D2D1_RENDER_TARGET_PROPERTIES
{
    D2D1_RENDER_TARGET_TYPE type;
    D2D1_PIXEL_FORMAT pixelFormat;
    FLOAT dpiX;
    FLOAT dpiY;
    D2D1_RENDER_TARGET_USAGE usage;
    D2D1_FEATURE_LEVEL minLevel;

} D2D1_RENDER_TARGET_PROPERTIES;

The force hardware and software flags have been removed from D2D1_RENDER_TARGET_USAGE. The following syntax block shows the current D2D1_RENDER_TARGET_USAGE enumeration.

typedef enum D2D1_RENDER_TARGET_USAGE
{
        D2D1_RENDER_TARGET_USAGE_NONE = 0x00000000,
        D2D1_RENDER_TARGET_USAGE_FORCE_BITMAP_REMOTING = 0x00000001,
        D2D1_RENDER_TARGET_USAGE_GDI_COMPATIBLE = 0x00000002,
        D2D1_RENDER_TARGET_USAGE_FORCE_DWORD = 0xffffffff

} D2D1_RENDER_TARGET_USAGE;

Hardware and software rendering options are now a part of the new D2D1_RENDER_TARGET_TYPE enumeration.

This enumeration specifies whether you want to use default rendering behavior (D2D1_RENDER_TARGET_TYPE_DEFAULT), in which case Direct2D uses hardware rendering if it's available and falls back to software rendering if it's not, or whether you want to only render to hardware (D2D1_RENDER_TARGET_TYPE_HARDWARE) or software (D2D1_RENDER_TARGET_TYPE_SOFTWARE).

typedef enum D2D1_RENDER_TARGET_TYPE
{
        D2D1_RENDER_TARGET_TYPE_DEFAULT = 0,
        D2D1_RENDER_TARGET_TYPE_SOFTWARE = 1,
        D2D1_RENDER_TARGET_TYPE_HARDWARE = 2,
        D2D1_RENDER_TARGET_TYPE_FORCE_DWORD = 0xffffffff

} D2D1_RENDER_TARGET_TYPE;

D2D1_FEATURE_LEVEL is another new enumeration introduced for RC. It specifies the level of Direct3D support required for hardware rendering.

typedef enum D2D1_FEATURE_LEVEL
{
        D2D1_FEATURE_LEVEL_DEFAULT = 0,
        D2D1_FEATURE_LEVEL_9 = D3D10_FEATURE_LEVEL_9_1,
        D2D1_FEATURE_LEVEL_10 = D3D10_FEATURE_LEVEL_10_0,
        D2D1_FEATURE_LEVEL_FORCE_DWORD = 0xffffffff

} D2D1_FEATURE_LEVEL;

Modifications to the FillOpacityMask Method

The ID2D1RenderTarget::FillOpacityMask method has been changed. Instead of having an optional D2D1_GAMMA parameter, it now has a required D2D1_OPACITY_MASK_CONTENT parameter you use to specify the correct color space for blending.

Beta Version

    STDMETHOD_(void, FillOpacityMask)(
        __in ID2D1Bitmap *opacityMask,
        __in ID2D1Brush *brush,
        __in_opt CONST D2D1_RECT_F *destinationRectangle = NULL,
        __in_opt CONST D2D1_RECT_F *sourceRectangle = NULL,
        __in_opt CONST D2D1_GAMMA *gammaSetting = NULL 
        ) PURE;

RC Version

STDMETHOD_(void, FillOpacityMask)(
    __in ID2D1Bitmap *opacityMask,
    __in ID2D1Brush *brush,
    __in CONST D2D1_OPACITY_MASK_CONTENT contentType,
    __in_opt CONST D2D1_RECT_F *destinationRectangle = NULL,
    __in_opt CONST D2D1_RECT_F *sourceRectangle = NULL 
    ) PURE;

The new D2D1_OPACITY_MASK_CONTENT enumeration is used to specify the type of content in the opacity mask bitmap. Direct2D uses this information to determine how to best perform the blend.

typedef enum D2D1_OPACITY_MASK_CONTENT
{       
        //
        // The mask contains geometries or bitmaps
        //
        D2D1_OPACITY_MASK_CONTENT_GRAPHICS= 0,
        
        //
        // The mask contains text rendered using one of the natural text modes
        //
        D2D1_OPACITY_MASK_CONTENT_TEXT_NATURAL = 1,

        //
        // The mask contains text rendered using one of the GDI compatible modes
        //
        D2D1_OPACITY_MASK_CONTENT_TEXT_GDI_COMPATIBLE = 2,

        D2D1_OPACITY_MASK_CONTENT _FORCE_DWORD = 0xffffffff
} D2D1_MASK_CONTENT

Modifications to the D2D1_DRAW_TEXT_OPTIONS Enumeration

In the beta version, the default D2D1_DRAW_TEXT_OPTIONS setting caused text to be clipped to the bounds of the layout rectangle. In RC, this behavior has been changed so that the default behavior does not clip.

Beta Version

typedef enum D2D1_DRAW_TEXT_OPTIONS
{       //
        // Do not snap the baseline of the text vertically.
        //
        D2D1_DRAW_TEXT_OPTIONS_NO_SNAP = 0x00000001,       
        //
        // Do not clip the text to the content bounds.
        //
        D2D1_DRAW_TEXT_OPTIONS_NO_CLIP = 0x00000002,
        D2D1_DRAW_TEXT_OPTIONS_NONE = 0x00000000,
        D2D1_DRAW_TEXT_OPTIONS_FORCE_DWORD = 0xffffffff
} D2D1_DRAW_TEXT_OPTIONS;

RC Version

typedef enum D2D1_DRAW_TEXT_OPTIONS
{        //
        // Do not snap the baseline of the text vertically.
        //
        D2D1_DRAW_TEXT_OPTIONS_NO_SNAP = 0x00000001,
        D2D1_DRAW_TEXT_OPTIONS_CLIP = 0x00000002,       
        D2D1_DRAW_TEXT_OPTIONS_NONE = 0x00000000,
        D2D1_DRAW_TEXT_OPTIONS_FORCE_DWORD = 0xffffffff

} D2D1_DRAW_TEXT_OPTIONS;

What's New in the DirectWrite API

Several changes have been made to the DirectWrite API. For more information, see DirectWrite Breaking Changes from Beta to RC.

See Also

DirectWrite Breaking Changes from Beta to RC

Send comments about this topic to Microsoft

Build date: 5/6/2009