DWRITE_PAINT_ELEMENT structure (dwrite_3.h)

Article
09/14/2023

DWRITE_PAINT_ELEMENT Structure

Specifies properties of a paint element, which is one node in a visual tree associated with a color glyph. This is passed as an output parameter to various IDWritePaintReader methods.

For a detailed description of how paint elements should be rendered, see the OpenType COLR table specification. Some of the descriptions in this topic reference the COLR paint record formats associated with each paint type.

Syntax

struct DWRITE_PAINT_ELEMENT {
  DWRITE_PAINT_TYPE paintType;
  union {
    struct {
      UINT32 childCount;
    } PAINT_LAYERS;
    PAINT_LAYERS          layers;
    struct {
      UINT32             glyphIndex;
      DWRITE_PAINT_COLOR color;
    } PAINT_SOLID_GLYPH;
    PAINT_SOLID_GLYPH     solidGlyph;
    DWRITE_PAINT_COLOR    solid;
    struct {
      UINT32 extendMode;
      UINT32 gradientStopCount;
      float  x0;
      float  y0;
      float  x1;
      float  y1;
      float  x2;
      float  y2;
    } PAINT_LINEAR_GRADIENT;
    PAINT_LINEAR_GRADIENT linearGradient;
    struct {
      UINT32 extendMode;
      UINT32 gradientStopCount;
      float  x0;
      float  y0;
      float  radius0;
      float  x1;
      float  y1;
      float  radius1;
    } PAINT_RADIAL_GRADIENT;
    PAINT_RADIAL_GRADIENT radialGradient;
    struct {
      UINT32 extendMode;
      UINT32 gradientStopCount;
      float  centerX;
      float  centerY;
      float  startAngle;
      float  endAngle;
    } PAINT_SWEEP_GRADIENT;
    PAINT_SWEEP_GRADIENT  sweepGradient;
    struct {
      UINT32 glyphIndex;
    } PAINT_GLYPH;
    PAINT_GLYPH           glyph;
    struct {
      UINT32     glyphIndex;
      D2D_RECT_F clipBox;
    } PAINT_COLOR_GLYPH;
    PAINT_COLOR_GLYPH     colorGlyph;
    DWRITE_MATRIX         transform;
    struct {
      DWRITE_COLOR_COMPOSITE_MODE mode;
    } PAINT_COMPOSITE;
    PAINT_COMPOSITE       composite;
  } PAINT_UNION;
  PAINT_UNION       paint;
};

Members

paintType

Type: DWRITE_PAINT_TYPE

Specifies the paint type, and thus which member of the union is valid.

PAINT_UNION

Specifies type-specific properties of the paint element.

PAINT_UNION.PAINT_LAYERS

Valid for paint elements of type DWRITE_PAINT_TYPE_LAYERS. Contains one or more child paint elements to be drawn in bottom-up order.

This corresponds to a PaintColrLayers record in the OpenType COLR table. Or it might correspond to a BaseGlyph record defined by COLR version 0.

PAINT_UNION.PAINT_LAYERS.childCount

Type: UINT32

Number of child paint elements in bottom-up order. Use IDWritePaintReader::MoveToFirstChild and MoveToNextSibling to retrieve the child paint elements. Use the MoveToParent method to return to the parent element.

PAINT_UNION.layers

Type: PAINT_UNION.PAINT_LAYERS

See PAINT_UNION.PAINT_LAYERS.

PAINT_UNION.PAINT_SOLID_GLYPH

Valid for paint elements of type DWRITE_PAINT_TYPE_SOLID_GLYPH. Specifies a glyph with a solid color fill. This paint element has no child elements.

This corresponds to a combination of two paint records in the OpenType COLR table: a PaintGlyph record, which references either a PaintSolid or PaintVarSolid record. Or it might correspond to a Layer record defined by COLR version 0.

PAINT_UNION.PAINT_SOLID_GLYPH.glyphIndex

Type: UINT32

Glyph index defining the shape to be filled.

PAINT_UNION.PAINT_SOLID_GLYPH.color

Type: DWRITE_PAINT_COLOR

Glyph color used to fill the glyph shape.

PAINT_UNION.solidGlyph

Type: PAINT_UNION.PAINT_SOLID_GLYPH

See PAINT_UNION.PAINT_SOLID_GLYPH.

PAINT_UNION.solid

Type: DWRITE_PAINT_COLOR

Valid for paint elements of type DWRITE_PAINT_TYPE_SOLID. Specifies a solid color used to fill the current shape or clip. This paint element has no child elements.

This corresponds to a PaintSolid or PaintVarSolid record in the OpenType COLR table.

PAINT_UNION.PAINT_LINEAR_GRADIENT

Valid for paint elements of type DWRITE_PAINT_TYPE_LINEAR_GRADIENT. Specifies a linear gradient used to fill the current shape or clip. This paint element has no child elements.

This corresponds to a PaintLinearGradient or PaintVarLinearGradient record in the OpenType COLR table.

PAINT_UNION.PAINT_LINEAR_GRADIENT.extendMode

Type: UINT32

A D2D1_EXTEND_MODE value specifying how colors outside the interval are defined.

PAINT_UNION.PAINT_LINEAR_GRADIENT.gradientStopCount

Type: UINT32

Number of gradient stops. Use the IDWritePaintReader::GetGradientStops method to get the gradient stops.

PAINT_UNION.PAINT_LINEAR_GRADIENT.x0

Type: float

X coordinate of the start point of the color line.

PAINT_UNION.PAINT_LINEAR_GRADIENT.y0

Type: float

Y coordinate of the start point of the color line.

PAINT_UNION.PAINT_LINEAR_GRADIENT.x1

Type: float

X coordinate of the end point of the color line.

PAINT_UNION.PAINT_LINEAR_GRADIENT.y1

Type: float

Y coordinate of the end point of the color line.

PAINT_UNION.PAINT_LINEAR_GRADIENT.x2

Type: float

X coordinate of the rotation point of the color line.

PAINT_UNION.PAINT_LINEAR_GRADIENT.y2

Type: float

Y coordinate of the rotation point of the color line.

PAINT_UNION.linearGradient

Type: PAINT_UNION.PAINT_LINEAR_GRADIENT

See PAINT_UNION.PAINT_LINEAR_GRADIENT.

PAINT_UNION.PAINT_RADIAL_GRADIENT

Valid for paint elements of type DWRITE_PAINT_TYPE_RADIAL_GRADIENT. Specifies a radial gradient used to fill the current shape or clip. This paint element has no child elements.

This corresponds to a PaintRadialGradient or PaintVarRadialGradient record in the OpenType COLR table.

PAINT_UNION.PAINT_RADIAL_GRADIENT.extendMode

Type: UINT32

A D2D1_EXTEND_MODE value specifying how colors outside the interval are defined.

PAINT_UNION.PAINT_RADIAL_GRADIENT.gradientStopCount

Type: UINT32

Number of gradient stops. Use the IDWritePaintReader::GetGradientStops method to get the gradient stops.

PAINT_UNION.PAINT_RADIAL_GRADIENT.x0

Type: float

Center X coordinate of the start circle.

PAINT_UNION.PAINT_RADIAL_GRADIENT.y0

Type: float

Center Y coordinate of the start circle.

PAINT_UNION.PAINT_RADIAL_GRADIENT.radius0

Type: float

Radius of the start circle.

PAINT_UNION.PAINT_RADIAL_GRADIENT.x1

Type: float

Center X coordinate of the end circle.

PAINT_UNION.PAINT_RADIAL_GRADIENT.y1

Type: float

Center Y coordinate of the end circle.

PAINT_UNION.PAINT_RADIAL_GRADIENT.radius1

Type: float

Radius of the end circle.

PAINT_UNION.radialGradient

Type: PAINT_UNION.PAINT_RADIAL_GRADIENT

See PAINT_UNION.PAINT_RADIAL_GRADIENT.

PAINT_UNION.PAINT_SWEEP_GRADIENT

Valid for paint elements of type DWRITE_PAINT_TYPE_SWEEP_GRADIENT. Specifies a sweep gradient used to fill the current shape or clip. This paint element has no child elements.

This corresponds to a PaintSweepGradient or PaintVarSweepGradient record in the OpenType COLR table.

PAINT_UNION.PAINT_SWEEP_GRADIENT.extendMode

Type: UINT32

A D2D1_EXTEND_MODE value specifying how colors outside the interval are defined.

PAINT_UNION.PAINT_SWEEP_GRADIENT.gradientStopCount

Type: UINT32

Number of gradient stops. Use the IDWritePaintReader::GetGradientStops method to get the gradient stops.

PAINT_UNION.PAINT_SWEEP_GRADIENT.centerX

Type: float

Center X coordinate.

PAINT_UNION.PAINT_SWEEP_GRADIENT.centerY

Type: float

Center Y coordinate.

PAINT_UNION.PAINT_SWEEP_GRADIENT.startAngle

Type: float

Start of the angular range of the gradient, measured in counter-clockwise degrees from the direction of the positive x axis.

PAINT_UNION.PAINT_SWEEP_GRADIENT.endAngle

Type: float

End of the angular range of the gradient, measured in counter-clockwise degrees from the direction of the positive x axis.

PAINT_UNION.sweepGradient

Type: PAINT_UNION.PAINT_SWEEP_GRADIENT

See PAINT_UNION.PAINT_SWEEP_GRADIENT.

PAINT_UNION.PAINT_GLYPH

Valid for paint elements of type DWRITE_PAINT_TYPE_GLYPH. Specifies a glyph shape to be filled or, equivalently, a clip region. This paint element has one child element.

The child paint element defines how the glyph shape is filled. The child element can be a single paint element, such as a linear gradient. Or the child element can be the root of a visual tree to be rendered with the glyph shape as a clip region. This corresponds to a PaintGlyph record in the OpenType COLR table.

PAINT_UNION.PAINT_GLYPH.glyphIndex

Type: UINT32

Glyph index of the glyph that defines the shape to be filled.

PAINT_UNION.glyph

Type: PAINT_UNION.PAINT_GLYPH

See PAINT_UNION.PAINT_GLYPH.

PAINT_UNION.PAINT_COLOR_GLYPH

Valid for paint elements of type DWRITE_PAINT_TYPE_COLOR_GLYPH. Specifies another color glyph, used as a reusable component. This paint element has one child element, which is the root paint element of the specified color glyph.

This corresponds to a PaintColorGlyph record in the OpenType COLR table.

PAINT_UNION.PAINT_COLOR_GLYPH.glyphIndex

Type: UINT32

Glyph index of the referenced color glyph.

PAINT_UNION.PAINT_COLOR_GLYPH.clipBox

Type: D2D_RECT_F

Clip box of the referenced color glyph, in ems. If the color glyph doesn't specify a clip box, then this is an empty rectangle. If it isn't an empty rectangle, then the client is required to clip the child content to this box.

PAINT_UNION.colorGlyph

Type: PAINT_UNION.PAINT_COLOR_GLYPH

See PAINT_UNION.PAINT_COLOR_GLYPH.

PAINT_UNION.transform

Type: DWRITE_MATRIX

Valid for paint elements of type DWRITE_PAINT_TYPE_TRANSFORM. Specifies an affine transform to be applied to child content. This paint element has one child element, which is the transformed content.

This corresponds to paint formats 12 through 31 in the OpenType COLR table.

PAINT_UNION.PAINT_COMPOSITE

Valid for paint elements of type DWRITE_PAINT_TYPE_COMPOSITE. Combines the two child paint elements using the specified compositing or blending mode. This paint element has two child elements. The first child is the paint source. The second child is the paint destination (or backdrop).

This corresponds to a PaintComposite record in the OpenType COLR table.

PAINT_UNION.PAINT_COMPOSITE.mode

Type: DWRITE_COLOR_COMPOSITE_MODE

Specifies the compositing or blending mode.

PAINT_UNION.composite

Type: PAINT_UNION.PAINT_COMPOSITE

See PAINT_UNION.PAINT_COMPOSITE.

paint

Type: PAINT_UNION

See PAINT_UNION.