Add functions to detect and configure Subpixel rendering mode

[1bsyl]

Add functions to detect and configure Subpixel rendering mode

TTF_GetSubpixelMode()
TTF_SetLcdFilter()
TTF_SetLcdFilterWeights()
TTF_SetLcdGeometry()

see #296

[slouken]

@1bsyl, can you rename the functions using "LCD" instead of "Lcd" and resolve the merge conflicts if you think this is still valuable?

[1bsyl]

@slouken updated!
I only wonder if the LCD mode should be per font (currently) or not (eg for the whole library).

[slouken]

I'm wondering now if instead of adding these APIs, we should expose the underlying FreeType library as an SDL3 property, so people can extend the font rendering however they like?

[slouken]

I wonder if we can simplify the API more by having properties for font shaping, etc.?

[1bsyl]

yes, it's would be better to give the FreeType handle to the user, so that he can do whatever he wants. Especially because the current functions of this PR are only 1to1 mapping with FreeType.

On the other hand, I am not sure if exposing "#include <freetype.h>" is kind of easy. There is the ft2build.h header file which I remember having issues with.

[slouken]

Okay, let's hold off merging while we consider this.

[slouken]

We shouldn't expose the FreeType library handle, because there's no guarantee that the version of FreeType used by the application matches the one built into SDL_ttf.

[slouken]

It also looks like FT_Library_SetLcdGeometry() is unimplemented in all builds of FreeType. Am I missing something?

[slouken]

FYI, here's an attempt to update the header for these API functions to the new SDL 3.0 conventions:

diff --git a/include/SDL3_ttf/SDL_ttf.h b/include/SDL3_ttf/SDL_ttf.h
index af278ff..c6e58c3 100644
--- a/include/SDL3_ttf/SDL_ttf.h
+++ b/include/SDL3_ttf/SDL_ttf.h
@@ -1382,6 +1384,100 @@ extern SDL_DECLSPEC bool SDLCALL TTF_GetGlyphScript(Uint32 ch, char *script, siz
  */
 extern SDL_DECLSPEC bool TTF_SetFontLanguage(TTF_Font *font, const char *language_bcp47);

+/**
+ * Subpixel rendering mode
+ *
+ * \since This enum is available since SDL_ttf 3.0.0.
+ *
+ * \sa TTF_GetSubpixelMode
+ * \sa TTF_SetLCDGeometry
+ * \sa TTF_SetLCDFilter
+ * \sa TTF_SetLCDFilterWeights
+ */
+typedef enum
+{
+  TTF_SUBPIXEL_MODE_UNKNOWN,    /**< Unknown */
+  TTF_SUBPIXEL_MODE_HARMONY,    /**< Harmony LCD rendering */
+  TTF_SUBPIXEL_MODE_CLEARTYPE,  /**< ClearType-style LCD rendering */
+} TTF_SubpixelMode;
+
+/**
+ * LCD filter, for ClearType-style LCD rendering mapping to FreeType FT_LcdFilter
+ *
+ * \since This enum is available since SDL_ttf 3.0.0.
+ */
+typedef enum
+{
+    TTF_LCD_FILTER_NONE,
+    TTF_LCD_FILTER_DEFAULT,
+    TTF_LCD_FILTER_LIGHT,
+    TTF_LCD_FILTER_LEGACY,
+} TTF_LCDFilter;
+
+/**
+ * Detect which subpixel rendering mode FreeType uses internally when LCD functions are used.
+ *
+ * \returns subpixel rendering mode
+ *
+ * \since This function is available since SDL_ttf 3.0.0
+ *
+ * \sa TTF_SetLCDGeometry
+ * \sa TTF_SetLCDFilter
+ * \sa TTF_SetLCDFilterWeights
+ */
+extern DECLSPEC TTF_SubpixelMode SDLCALL TTF_GetSubpixelMode(void);
+
+/**
+ * Set parameters for Harmony LCD rendering.
+ *
+ * See FreeType function FT_Library_SetLcdGeometry for more details
+ * Remark: FT_Library_SetLcdGeometry's y coordinates are in reverse from the usual SDL notation (larger = upper as opposed to larger = lower).
+ *
+ * \param font the font to configure
+ * \param pixel_coordinates an array of 6 positions of color subpixels
+ * \returns true on success or false on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL_ttf 3.0.0
+ *
+ * \sa TTF_GetSubpixelMode
+ */
+extern DECLSPEC int SDLCALL TTF_SetLCDGeometry(TTF_Font *font, const int *pixel_coordinates);
+
+/**
+ * Set a filter for ClearType-style LCD rendering.
+ *
+ * See FreeType function FT_Library_SetLcdFilter for more details
+ *
+ * \param font the font to configure
+ * \param filter filter to use
+ * \returns true on success or false on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL_ttf 3.0.0
+ *
+ * \sa TTF_GetSubpixelMode
+ * \sa TTF_SetLCDFilterWeights
+ */
+extern DECLSPEC bool SDLCALL TTF_SetLCDFilter(TTF_Font *font, TTF_LCDFilter filter);
+
+/**
+ * Set a custom filter for ClearType-style LCD rendering.
+ *
+ * See FreeType function FT_Library_SetLcdFilterWeights for more details
+ *
+ * \param font the font to configure
+ * \param weights an array of five bytes used as the filter weights in 1/256 units.
+ * \returns true on success or false on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL_ttf 3.0.0
+ *
+ * \sa TTF_GetSubpixelMode
+ * \sa TTF_SetLCDFilter
+ */
+extern DECLSPEC bool SDLCALL TTF_SetLCDFilterWeights(TTF_Font *font, const Uint8 *weights);
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

[1bsyl]

@slouken do you want this PR ? if so I can update to latest version

[slouken]

I'm just confused because it looks like the functions we're calling/exposing just aren't available in default builds of FreeType. If that's true, then we probably shouldn't add them.

[1bsyl]

Anyway, I wonder if people really needs this ...
https://freetype.org/freetype2/docs/reference/ft2-lcd_rendering.html
that should for specific LCD boards/development.

Current FreeType version 2.13.3
and the functions are from 2.3.0 and 2.4.0, but the also need FT_CONFIG_OPTION_SUBPIXEL_RENDERING

FT_Library_SetLcdFilter
This function does nothing but returns FT_Err_Unimplemented_Feature if the configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not defined in your build of the library.
since 2.3.0
https://freetype.org/freetype2/docs/reference/ft2-lcd_rendering.html#ft_library_setlcdfilter

and FT_Library_SetLcdFilterWeights, same, but since 2.4.0

[slouken]

Yeah, let's not add this for now. Nice work on the patch though!