API for Harmony LCD rendering.

This introduces `FT_Library_SetLcdGeometry' for setting up arbitrary
LCD subpixel geometry including non-striped patterns.

4 files changed, 88 insertions, 12 deletions

diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 008335cfa..7eece3f2a 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -3351,7 +3351,7 @@ FT_BEGIN_HEADER
   /*    with subpixel-rendered glyphs to prevent color-fringing!  A        */
   /*    subpixel-rendered glyph must first be filtered with a filter that  */
   /*    gives equal weight to the three color primaries and does not       */
-  /*    exceed a sum of 0x100, see section @lcd_filtering.  Then the       */
+  /*    exceed a sum of 0x100, see section @lcd_rendering.  Then the       */
   /*    only difference to gray linear blending is that subpixel-rendered  */
   /*    linear blending is done 3~times per pixel: red foreground subpixel */
   /*    to red background subpixel and so on for green and blue.           */
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 51257bb7c..68658db32 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -120,7 +120,7 @@
 /*    gzip                                                                 */
 /*    lzw                                                                  */
 /*    bzip2                                                                */
-/*    lcd_filtering                                                        */
+/*    lcd_rendering                                                        */
 /*                                                                         */
 /***************************************************************************/
 
diff --git a/include/freetype/ftlcdfil.h b/include/freetype/ftlcdfil.h
index 8e35e38d1..9b06c4e29 100644
--- a/include/freetype/ftlcdfil.h
+++ b/include/freetype/ftlcdfil.h
@@ -36,10 +36,10 @@ FT_BEGIN_HEADER
   /***************************************************************************
    *
    * @section:
-   *   lcd_filtering
+   *   lcd_rendering
    *
    * @title:
-   *   LCD Filtering
+   *   LCD Rendering
    *
    * @abstract:
    *   Reduce color fringes of subpixel-rendered bitmaps.
@@ -230,9 +230,10 @@ FT_BEGIN_HEADER
    *   @FT_LCD_FILTER_NONE in order to enable it.
    *
    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
-   *   do anything if FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not defined
-   *   in your build of the library, which should correspond to all default
-   *   builds of FreeType.
+   *   do anything except returning `FT_Err_Unimplemented_Feature' if the
+   *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
+   *   defined in your build of the library, which should correspond to all
+   *   default builds of FreeType.
    *
    * @since:
    *   2.3.0
@@ -264,9 +265,10 @@ FT_BEGIN_HEADER
    *
    * @note:
    *   Due to *PATENTS* covering subpixel rendering, this function doesn't
-   *   do anything if FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not defined
-   *   in your build of the library, which should correspond to all default
-   *   builds of FreeType.
+   *   do anything except returning `FT_Err_Unimplemented_Feature' if the
+   *   configuration macro FT_CONFIG_OPTION_SUBPIXEL_RENDERING is not
+   *   defined in your build of the library, which should correspond to all
+   *   default builds of FreeType.
    *
    *   LCD filter weights can also be set per face using @FT_Face_Properties
    *   with @FT_PARAM_TAG_LCD_FILTER_WEIGHTS.
@@ -296,6 +298,54 @@ FT_BEGIN_HEADER
   typedef FT_Byte  FT_LcdFiveTapFilter[FT_LCD_FILTER_FIVE_TAPS];
 
 
+  /**************************************************************************
+   *
+   * @func:
+   *   FT_Library_SetLcdGeometry
+   *
+   * @description:
+   *   This function can be used to modify default positions of color
+   *   subpixels, which controls Harmony LCD rendering.
+   *
+   * @input:
+   *   library ::
+   *     A handle to the target library instance.
+   *
+   *   sub ::
+   *     A pointer to an array of 3 vectors in 26.6 fractional pixel format;
+   *     the function modifies the default values, see the note below.
+   *
+   * @return:
+   *   FreeType error code.  0~means success.
+   *
+   * @note:
+   *   This function does nothing and returns `FT_Err_Unimplemented_Feature'
+   *   in the context of ClearType-style subpixel rendering when
+   *   FT_CONFIG_OPTION_SUBPIXEL_RENDERING is defined in your build of the
+   *   library.
+   *
+   *   Subpixel geometry examples:
+   *
+   *   - {{-21, 0}, {0, 0}, {21, 0}} is the default, corresponding 3 color
+   *   stripes shifted by a third of a pixel. This could be an RGB panel.
+   *
+   *   - {{21, 0}, {0, 0}, {-21, 0}} looks the same as the default but
+   *   offers you possibility to specify that this is a BGR panel instead,
+   *   while keeping the bitmap in the same RGB888 format.
+   *
+   *   - {{0, 21}, {0, 0}, {0, -21}} is the vertical RGB, but the bitmap
+   *   stays RGB888 as a result.
+   *
+   *   - {{32, -21}, {-32, -21}, {0, 42}} is a certain PenTile arrangement.
+   *
+   * @since:
+   *   2.9.x
+   */
+  FT_EXPORT( FT_Error )
+  FT_Library_SetLcdGeometry( FT_Library  library,
+                             FT_Vector*  sub );
+
+
   /* */
 
 
diff --git a/src/base/ftlcdfil.c b/src/base/ftlcdfil.c
index aab04d14b..6e9b4e46d 100644
--- a/src/base/ftlcdfil.c
+++ b/src/base/ftlcdfil.c
@@ -351,6 +351,16 @@
     return FT_Err_Ok;
   }
 
+  FT_EXPORT_DEF( FT_Error )
+  FT_Library_SetLcdGeometry( FT_Library  library,
+                             FT_Vector*  sub )
+  {
+    FT_UNUSED( library );
+    FT_UNUSED( sub );
+
+    return FT_THROW( Unimplemented_Feature );
+  }
+
 #else /* !FT_CONFIG_OPTION_SUBPIXEL_RENDERING */
 
   /* add padding to accommodate outline shifts */
@@ -379,13 +389,29 @@
 
 
   FT_EXPORT_DEF( FT_Error )
+  FT_Library_SetLcdGeometry( FT_Library  library,
+                             FT_Vector*  sub )
+  {
+    if ( !library )
+      return FT_THROW( Invalid_Library_Handle );
+
+    if ( !sub )
+      return FT_THROW( Invalid_Argument );
+
+    ft_memcpy( library->lcd_geometry, sub, 6 * sizeof( FT_Vector ) );
+
+    return FT_THROW( Unimplemented_Feature );
+  }
+
+
+  FT_EXPORT_DEF( FT_Error )
   FT_Library_SetLcdFilterWeights( FT_Library      library,
                                   unsigned char  *weights )
   {
     FT_UNUSED( library );
     FT_UNUSED( weights );
 
-    return FT_Err_Ok;
+    return FT_THROW( Unimplemented_Feature );
   }
 
 
@@ -396,7 +422,7 @@
     FT_UNUSED( library );
     FT_UNUSED( filter );
 
-    return FT_Err_Ok;
+    return FT_THROW( Unimplemented_Feature );
   }
 
 #endif /* !FT_CONFIG_OPTION_SUBPIXEL_RENDERING */