DirectWrite API Reference

Graphics API | Windows

DirectWrite Overview

DirectWrite is a modern text rendering API that provides high-quality text rendering, modern text features, and international typographic support. It is part of the Windows Graphics infrastructure, enabling applications to display text with advanced typographic features such as OpenType layout, color fonts, and complex script shaping.

Key benefits of using DirectWrite include:

  • High-Quality Rendering: Clearer, sharper text at various sizes and resolutions.
  • Advanced Typographic Features: Support for advanced OpenType features like ligatures, stylistic sets, and contextual alternates.
  • International Support: Robust handling of diverse languages and writing systems, including complex scripts.
  • Performance: Optimized for efficient text layout and rendering.
  • Cross-Platform Compatibility (via Win32 API): Integrates seamlessly with other Windows graphics APIs like GDI and Direct2D.

Core Concepts

DirectWrite revolves around several core concepts:

  • Font Objects: Represent font faces and font collections, allowing access to font metrics and glyph data.
  • Text Layout: The process of arranging text according to formatting properties, including wrapping, justification, and line breaking.
  • Text Rendering: Drawing the laid-out text onto a target surface, with options for anti-aliasing and pixel-snapping.
  • Typography: The API exposes advanced typographic features available in OpenType fonts.

Core Interfaces

IDWriteFactory

The IDWriteFactory interface is the entry point for all DirectWrite functionality. You use it to create other DirectWrite objects, such as font collections, text formats, and text layouts.

HRESULT CreateTextFormat( [string] PCWSTR fontFamilyName, [in, optional] IDWriteFontCollection* fontCollection, DWRITE_FONT_WEIGHT fontWeight, DWRITE_FONT_STYLE fontStyle, DWRITE_FONT_STRETCH fontStretch, FLOAT fontSize, [string] PCWSTR localeName, [out] IDWriteTextFormat** textFormat );

Parameters:

  • fontFamilyName: The name of the font family.
  • fontCollection: An optional font collection to search within.
  • fontWeight: The desired font weight.
  • fontStyle: The desired font style.
  • fontStretch: The desired font stretch.
  • fontSize: The desired font size in DIPs (device-independent pixels).
  • localeName: The locale name for font selection.
  • textFormat: Receives a pointer to the created IDWriteTextFormat object.

IDWriteTextLayout

The IDWriteTextLayout interface represents a block of text that has been formatted for layout. It handles text wrapping, alignment, and other layout properties.

HRESULT Draw( [in, optional] void* clientDrawingContext, [in] IDWriteTextRenderer* renderer, FLOAT originX, FLOAT originY );

Parameters:

  • clientDrawingContext: A context pointer passed to the renderer.
  • renderer: A pointer to an implementation of the IDWriteTextRenderer interface.
  • originX: The X coordinate of the layout's origin.
  • originY: The Y coordinate of the layout's origin.

IDWriteTextRenderer

IDWriteTextRenderer is an abstract interface that applications implement to draw text. DirectWrite calls methods on this interface to draw glyphs, run breaks, and other text elements.

IDWriteTextFormat

IDWriteTextFormat specifies the font family, size, style, weight, and locale for text. It's used to create an IDWriteTextLayout object.

IDWriteTextRange

Represents a range of characters within a string, defined by a starting character position and a length.

typedef struct DWRITE_TEXT_RANGE {
    UINT32 start;
    UINT32 length;
} DWRITE_TEXT_RANGE;

Common Enumerations

DirectWrite utilizes several enumerations to define properties:

  • DWRITE_FONT_WEIGHT: Specifies font weights (e.g., thin, light, normal, bold).
  • DWRITE_FONT_STYLE: Specifies font styles (e.g., normal, italic, oblique).
  • DWRITE_FONT_STRETCH: Specifies font width (e.g., condensed, normal, expanded).
  • DWRITE_TEXT_ALIGNMENT: Specifies horizontal text alignment (e.g., left, center, right).
  • DWRITE_PARAGRAPH_ALIGNMENT: Specifies vertical text alignment within a paragraph.

Key Structures

  • DWRITE_FONT_METRICS: Contains font metrics like ascent, descent, and line gap.
  • DWRITE_TEXT_RANGE: Defines a contiguous range of text.
  • DWRITE_TRIMMING: Specifies how text is trimmed when it exceeds layout bounds.

Helper Functions

While most functionality is accessed via interfaces, some global functions are also available for utility purposes.

Note: DirectWrite is typically used in conjunction with Direct2D for rendering. You would obtain an IDWriteFactory, create an IDWriteTextFormat, then an IDWriteTextLayout, and finally use a IDWriteTextRenderer (often implemented by a Direct2D render target) to draw the text.