Introduce TextOptions #20107

Gillibald · 2025-11-20T06:28:17Z

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

…elinePixelAlign

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.

src/Avalonia.Base/Rendering/Composition/Server/DrawingContextProxy.cs

src/Avalonia.Base/Media/TextHintingMode.cs

src/Windows/Avalonia.Direct2D1/Media/DrawingContextImpl.cs

src/Skia/Avalonia.Skia/TwoLevelCache.cs

src/Avalonia.Base/Rendering/Composition/Server/ServerCompositionVisual.cs

# Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.

Co-authored-by: Copilot <[email protected]>

…nto feature/TextOptions

avaloniaui-bot · 2025-11-20T10:16:56Z

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]

MrJul · 2025-12-03T09:36:29Z

Notes from the API review meeting:

Keep RenderOptions.TextRenderingMode and make it obsolete (redirect to TextOptions.TextRenderingMode)
For consistency, BaselinePixelAlign might be better as an enum rather than a bool?. Proposed: BaselinePixelAlignment { Unspecified, Aligned, Unaligned }

MrJul · 2025-12-03T09:37:17Z

Also, make sure documentation states that the various backends/platforms may behave a bit differently here.

avaloniaui-bot · 2026-01-06T13:20:08Z

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

avaloniaui-bot · 2026-01-07T11:09:32Z

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

MrJul · 2026-01-07T15:27:05Z

native/Avalonia.Native/src/OSX/DerivedData/Avalonia.Native.OSX/info.plist

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>


This file has likely been committed by mistake, please remove.

MrJul · 2026-01-07T16:03:40Z

src/Avalonia.Base/Media/TextOptions.cs

+    /// <remarks>Use this enumeration to control whether the baseline of rendered content is aligned to the
+    /// pixel grid, which can affect visual crispness and positioning. The value may influence rendering quality,
+    /// especially at small font sizes or when precise alignment is required.</remarks>
+    public enum BaselinePixelAlignment


I know we've been pretty inconsistent with the usual "one type per file", but other used enums in this file are in their own files. Please move it to its own.

MrJul · 2026-01-07T16:04:58Z

src/Avalonia.Base/Media/TextOptions.cs

+    /// <remarks>Use this enumeration to control whether the baseline of rendered content is aligned to the
+    /// pixel grid, which can affect visual crispness and positioning. The value may influence rendering quality,
+    /// especially at small font sizes or when precise alignment is required.</remarks>
+    public enum BaselinePixelAlignment


Other enums used in RenderOptions and TextOptions specify a byte underlying type for tight packing of the render data. We should probably do the same here for consistency?

MrJul · 2026-01-07T16:50:35Z

src/Skia/Avalonia.Skia/TwoLevelCache.cs

+            }
+
+            // If primary matches after factory (unlikely) return primary and dispose created
+            if (_comparer.Equals(_primaryKey!, key))


Unless I'm mistaken, this isn't unlikely (as noted by the comment above), but completely impossible? _primaryKey and key didn't change and the primary key comparison was already handled by TryGet at the beginning of the method.

MrJul · 2026-01-07T17:12:19Z

src/Skia/Avalonia.Skia/TwoLevelCache.cs

+            }
+
+            // Rotate into secondary (evict last)
+            var newSec = new KeyValuePair<TKey, TValue>[sec.Length];


This should be rotated in place, there is no need to allocate a new array each time.

MrJul · 2026-01-07T17:15:31Z

src/Skia/Avalonia.Skia/TwoLevelCache.cs

+    /// thread-safe.</remarks>
+    /// <typeparam name="TKey">The type of keys used to identify cached values. Must be non-nullable.</typeparam>
+    /// <typeparam name="TValue">The type of values to be stored in the cache. Must be a reference type.</typeparam>
+    internal class TwoLevelCache<TKey, TValue>


I'm aware this is an internal helper, but a couple of unit tests testing basic features (primary key, secondary cache, eviction) might be nice. This is typically the type of helper that has just enough complexity to contain hidden bugs ;)

(For example, we had several bugs in the past with InlineDictionary that manifested only in some specific scenarios.)

MrJul · 2026-01-07T17:21:04Z

tests/Avalonia.RenderTests/Controls/TextBlockTests.cs

+        [InlineData(TextRenderingMode.Alias, TextHintingMode.None)]
+        [InlineData(TextRenderingMode.Antialias, TextHintingMode.Light)]
+        [InlineData(TextRenderingMode.Alias, TextHintingMode.Light)]
+        [Theory(Skip = "Backend dependent")]


Can we at least execute the tests on Windows?

Introduce TextOptions with TextRenderingMode, TextHintingMode and Bas…

500c76e

…elinePixelAlign

Gillibald added enhancement breaking-change wont-backport needs-api-review The PR adds new public APIs that should be reviewed. labels Nov 20, 2025

Gillibald requested a review from Copilot November 20, 2025 06:35

Copilot started reviewing on behalf of Gillibald November 20, 2025 06:36 View session

Copilot finished reviewing on behalf of Gillibald November 20, 2025 06:39

Copilot AI reviewed Nov 20, 2025

View reviewed changes

Gillibald and others added 7 commits November 20, 2025 08:15

Apply suggestions from code review

d82a7d6

Co-authored-by: Copilot <[email protected]>

Merge branch 'feature/TextOptions' of github.com:Gillibald/Avalonia i…

ad92c32

…nto feature/TextOptions

TextHintingMode adjustments

b77f157

Revert submodule change

e5a3daf

Fix encoding

c36736b

Update baseline

aaa4559

Gillibald marked this pull request as draft November 20, 2025 08:48

MrJul added api-change-requested The new public APIs need some changes. and removed needs-api-review The PR adds new public APIs that should be reviewed. labels Dec 3, 2025

Adjustments after API review

9d88be6

MrJul added api-approved The new public APIs have been approved. and removed api-change-requested The new public APIs need some changes. labels Dec 4, 2025

Gillibald added 2 commits January 6, 2026 13:38

Merge remote-tracking branch 'origin/master' into feature/TextOptions

96588e8

update api baseline

10d2e0c

Gillibald added 2 commits January 6, 2026 19:13

Fix merge

3ce243c

Skip new test for TextOptions

da1d024

Merge branch 'master' into feature/TextOptions

45f96bd

Gillibald marked this pull request as ready for review January 7, 2026 10:30

MrJul reviewed Jan 7, 2026

View reviewed changes

Uh oh!

Introduce TextOptions #20107

Are you sure you want to change the base?

Introduce TextOptions #20107

Conversation

Gillibald commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does the pull request do?

What is the current behavior?

What is the updated/expected behavior with this PR?

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

Default Skia mapping

Freetype

DWrite

CoreText

Checklist

Breaking changes

Obsoletions / Deprecations

Fixed issues

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avaloniaui-bot commented Nov 20, 2025

Uh oh!

MrJul commented Dec 3, 2025

Uh oh!

MrJul commented Dec 3, 2025

Uh oh!

avaloniaui-bot commented Jan 6, 2026

Uh oh!

avaloniaui-bot commented Jan 7, 2026

Uh oh!

MrJul Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MrJul Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MrJul Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MrJul Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MrJul Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MrJul Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MrJul Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Gillibald commented Nov 20, 2025 •

edited

Loading