#1592 [Win32] Add SCI_SETFONTRENDERINGPARAMETER to set DirectWrite rendering parameters (gamma, contrast, ClearType level, pixel geometry, rendering mode)

[Pyre]

On Win32 with DirectWrite, Scintilla draws text with the monitor's rendering parameters (CreateMonitorRenderingParams) and, for ClearType, a custom set whose gamma comes from SPI_GETFONTSMOOTHINGCONTRAST. Applications can't adjust them, but users ask for it: DirectWrite's default rendering mode for small text (natural symmetric) antialiases vertically, which blurs small text compared with GDI; thin fonts look faint; OLED and rotated screens need grayscale or a different pixel geometry. Notepad++ has a feature request and implementation for this (https://github.com/notepad-plus-plus/notepad-plus-plus/issues/18414, https://github.com/notepad-plus-plus/notepad-plus-plus/pull/18418), and a reviewer there suggested that it belongs in Scintilla.

The attached patch (against 5.6.7) adds, for Windows:

set void SetFontRenderingParameter=2822(FontRenderingParameter parameter, int value)
get int GetFontRenderingParameter=2823(FontRenderingParameter parameter,)

The parameters SC_FONTRENDERING_GAMMA, _ENHANCEDCONTRAST, _GRAYSCALEENHANCEDCONTRAST, _CLEARTYPELEVEL, _PIXELGEOMETRY and _RENDERINGMODE map onto the arguments of IDWriteFactory::CreateCustomRenderingParams, in integer units Windows already uses:

• gamma in thousandths, 1000..2200 (as SPI_GETFONTSMOOTHINGCONTRAST);
• enhanced contrasts in hundredths, 0..1000;
• ClearType level in percent, 0..100;
• pixel geometry SC_PIXELGEOMETRY_FLAT, _RGB, _BGR (the DWRITE_PIXEL_GEOMETRY values);
• rendering mode SC_RENDERINGMODE_DEFAULT, _GDICLASSIC, _GDINATURAL, _NATURAL, _NATURALSYMMETRIC (the DWRITE_RENDERING_MODE values; aliased and outline are excluded).
  SC_FONT_RENDERING_DEFAULT (-1) restores the monitor's value, which is also what GetFontRenderingParameter returns for a parameter not set. Out-of-range values are ignored. Values not set keep the monitor's values and the ClearType contrast still applies unless the gamma is set, so nothing changes until an application sets something. Values are kept when the technology changes and only affect the DirectWrite technologies.

Related behaviour:

• With the GDI rendering modes, text is also measured with GDI-compatible layouts (CreateGdiCompatibleTextLayout) and a whole-pixel font height, so caret and selection positions match the glyphs as drawn. Only while GDI scaling is not active (device scale factor 1). The measuring mode is carried in two bits of the font quality above SC_EFF_QUALITY_MASK, which SCI_SETFONTQUALITY preserves and SCI_GETFONTQUALITY hides, so fonts are realised and cached per measuring mode.
• Aliased text (SC_EFF_QUALITY_NON_ANTIALIASED) keeps the monitor's parameters, as a rendering mode set by the application can be incompatible with aliased drawing.
• The autocompletion list draws with the editor's parameters once the application customises text rendering (a font quality other than default, or a parameter set); otherwise it is drawn as before.

No new platform requirement: the patch uses the IDWriteRenderingParams1 / CreateCustomRenderingParams calls Scintilla already makes, plus CreateGdiCompatibleTextLayout.

Scintilla.iface entries, headers regenerated with HFacer.py and ScintillaAPIFacer.py, and ScintillaDoc.html documentation are included. Names and message numbers are suggestions. If you prefer the element colour pattern (a Reset message instead of -1), that is an easy change.

Testing (MinGW-w64 g++, Wine 9):

• g++ --std=c++17 -Wpedantic -Wall -Wextra: no warnings, also with DISABLE_D2D. HeaderCheck.py and CheckMentioned.py are clean.
• A test program driving a Scintilla window: 229 checks pass. They cover value validation and round trips, values kept across technology changes, drawing in every rendering mode, font quality and technology, whole-pixel advances with the GDI modes, the autocompletion list and call tips, WM_SETTINGCHANGE, and no repainting while idle.
  <windows: tried="" in="" notepad++="" with="" the="" same="" scintilla="" code:="" ...=""></windows:>

The patch applies on its own to 5.6.7. It touches the same DirectWrite font constructor as the fix in bug #2519, so a second version that applies after that fix is attached too.

Two further options Notepad++ uses, a rendering mode that switches to natural for small text and a separate gamma for light text on dark backgrounds, are left out and could be proposed separately.

This patch was prepared with the help of an AI assistant (Claude), then reviewed and tested.

[Neil Hodgson]

I am not currently accepting LLM-generated contributions.

The presentation of this feature, with 100 new setting combinations, is overwhelming so will not be that helpful for users.