Introduce TextOptions

[Gillibald]

What does the pull request do?

This PR introduces TextOptions similar to the current RenderOptions. This allows customization of certain font rasterization properties, such as font hinting, antialiasing, or baseline pixel alignment.

What is the current behavior?

Currently, it is only possible to customize the text antialiasing.

What is the updated/expected behavior with this PR?

How was the solution implemented (if it's not obvious)?

Default Skia mapping

Freetype

FT_Int loadFlags = FT_LOAD_DEFAULT;

switch (fontHinting) {
    case SkFontHinting::kNone:
        loadFlags |= FT_LOAD_NO_HINTING;
        break;
    case SkFontHinting::kSlight:
        loadFlags |= FT_LOAD_TARGET_LIGHT;
        break;
    case SkFontHinting::kNormal:
        loadFlags |= FT_LOAD_TARGET_NORMAL;
        break;
    case SkFontHinting::kFull:
        loadFlags |= FT_LOAD_TARGET_MONO;
        break;
}

DWrite

DWRITE_RENDERING_MODE renderingMode;

switch (fontHinting) {
    case SkFontHinting::kNone:
        renderingMode = DWRITE_RENDERING_MODE_OUTLINE;
        break;
    case SkFontHinting::kSlight:
        renderingMode = DWRITE_RENDERING_MODE_NATURAL;
        break;
    case SkFontHinting::kNormal:
        renderingMode = DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL;
        break;
    case SkFontHinting::kFull:
        renderingMode = DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC;
        break;
}

CoreText

switch (fontHinting) {
    case SkFontHinting::kNone:
        options.disableFontSubpixelQuantization = true;
        break;
    case SkFontHinting::kSlight:
        options.hinting = kCTFontDescriptorOptionLightHinting;
        break;
    case SkFontHinting::kNormal:
        options.hinting = kCTFontDescriptorOptionDefaultHinting;
        break;
    case SkFontHinting::kFull:
        options.hinting = kCTFontDescriptorOptionStrongHinting;
        break;
}

Checklist

• Added unit tests (if possible)?
• Added XML documentation to any related classes?
• Consider submitting a PR to https://github.com/AvaloniaUI/avalonia-docs with user documentation

Breaking changes

Obsoletions / Deprecations

Fixed issues

Fixes: #12510
Fixes: #19553

[Copilot]

Pull Request Overview

This pull request introduces TextOptions as a new dedicated type for configuring text rendering, separating text-specific settings from the general RenderOptions. This change improves API design by providing a clearer separation of concerns between general rendering options and text-specific rendering configuration.

Key Changes

• Introduces TextOptions struct with TextRenderingMode, TextHintingMode, and BaselinePixelAlign properties
• Moves TextRenderingMode from RenderOptions to TextOptions
• Implements a new TwoLevelCache for efficient text blob caching based on complete text options
• Updates all drawing context implementations to support text options push/pop operations

Reviewed Changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/Avalonia.Base/Media/TextOptions.cs	New struct defining text rendering options with methods for getting/setting options on visuals
src/Avalonia.Base/Media/TextHintingMode.cs	New enum defining text hinting modes (None, Slight, Normal, Full)
src/Avalonia.Base/Media/TextRenderingMode.cs	Enhanced with XML documentation for each enum value
src/Avalonia.Base/Media/RenderOptions.cs	Removed TextRenderingMode property and related methods
src/Avalonia.Base/Visual.cs	Added TextOptions property alongside existing RenderOptions
src/Avalonia.Base/Platform/IDrawingContextImpl.cs	Added PushTextOptions and PopTextOptions methods to interface
src/Skia/Avalonia.Skia/TwoLevelCache.cs	New cache implementation for storing text blobs with eviction support
src/Skia/Avalonia.Skia/GlyphRunImpl.cs	Updated to use TextOptions for text blob caching instead of simple edging array
src/Skia/Avalonia.Skia/DrawingContextImpl.cs	Implemented text options stack and applies hinting/baseline settings
src/Windows/Avalonia.Direct2D1/Media/DrawingContextImpl.cs	Added text options support with separate text antialiasing control
src/Headless/Avalonia.Headless/HeadlessPlatformRenderInterface.cs	Added no-op text options methods for headless rendering
src/Avalonia.Base/Rendering/ImmediateRenderer.cs	Updated to push text options before render options
src/Avalonia.Base/Rendering/Composition/Server/ServerCompositionVisual.cs	Added text options push/pop in rendering pipeline
src/Avalonia.Base/Rendering/Composition/Server/DrawingContextProxy.cs	Added text options proxy commands
tests/Avalonia.Skia.UnitTests/Media/GlyphRunTests.cs	Updated to use new TextOptions API
tests/Avalonia.RenderTests/Media/GlyphRunTests.cs	Migrated from RenderOptions.SetTextRenderingMode to TextOptions.SetTextRenderingMode

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[avaloniaui-bot]

You can test this PR using the following package version. 12.0.999-cibuild0060178-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]