[freetype2] colr 138e0d4 2/8: Add new methods required for 'COLR' v1 to public API (#59703).

[Werner LEMBERG]

branch: colr
commit 138e0d4809cebda359c7519ddac0c57f0e9a28e8
Author: Dominik Röttsches <drott@chromium.org>
Commit: Werner Lemberg <wl@gnu.org>

    Add new methods required for 'COLR' v1 to public API (#59703).
    
    * include/freetype/freetype.h (FT_Get_Color_Glyph_Paint): New method
    for retrieving the root paint object for a color glyph by specifying
    a glyph ID.
    (FT_Get_Paint_Layers): New method for retrieving the layers of a
    `PaintColorGlyph`.
    (FT_Get_ColorLine_Stops): New method for retrieving the stops of a
    color.
    (FT_Get_Paint): New method for resolving an `FT_OpaquePaint` into an
    `FT_COLR_Paint` object.
---
 ChangeLog                   |  14 ++++
 include/freetype/freetype.h | 158 ++++++++++++++++++++++++++++++++++++++++++++
 src/base/ftobjs.c           |  36 ++++++++++
 3 files changed, 208 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index f8aa2c7..5126cf5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,19 @@
 2020-12-16  Dominik Röttsches  <drott@chromium.org>
 
+       Add new methods required for 'COLR' v1 to public API (#59703).
+
+       * include/freetype/freetype.h (FT_Get_Color_Glyph_Paint): New method
+       for retrieving the root paint object for a color glyph by specifying
+       a glyph ID.
+       (FT_Get_Paint_Layers): New method for retrieving the layers of a
+       `PaintColorGlyph`.
+       (FT_Get_ColorLine_Stops): New method for retrieving the stops of a
+       color.
+       (FT_Get_Paint): New method for resolving an `FT_OpaquePaint` into an
+       `FT_COLR_Paint` object.
+
+2020-12-16  Dominik Röttsches  <drott@chromium.org>
+
        Add types required for 'COLR' v1 to public API (#59703).
 
        * include/freetype/freetype.h (FT_PaintFormat, FT_ColorStopIterator,
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 57b0b37..31d1d63 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -4881,6 +4881,164 @@ FT_BEGIN_HEADER
 
   /**************************************************************************
    *
+   * @function:
+   *   FT_Get_Color_Glyph_Paint
+   *
+   * @description:
+   *   This is the starting point and interface to color gradient
+   *   information in a 'COLR' v1 table in OpenType fonts to recursively
+   *   retrieve the paint tables for the directed acyclic graph of a colored
+   *   glyph, given a glyph ID.
+   *
+   *     https://github.com/googlefonts/colr-gradients-spec
+   *
+   *   In a 'COLR' v1 font, each color glyph defines a directed acyclic
+   *   graph of nested paint tables, such as `PaintGlyph`, `PaintSolid`,
+   *   `PaintLinearGradient`, `PaintRadialGradient`, and so on.  Using this
+   *   function and specifying a glyph ID, one retrieves the root paint
+   *   table for this glyph ID.
+   *
+   * @input:
+   *   face ::
+   *     A handle to the parent face object.
+   *
+   *   base_glyph ::
+   *     The glyph index for which to retrieve the root paint table.
+   *
+   * @output:
+   *   paint ::
+   *     The @FT_OpaquePaint object that references the actual paint table.
+   *
+   *     The respective actual @FT_COLR_Paint object is retrieved via
+   *     @FT_Get_Paint.
+   *
+   * @return:
+   *   Value~1 if everything is OK.  If no color glyph is found, or the root
+   *   paint could not be retrieved, value~0 gets returned.  In case of an
+   *   error, value~0 is returned also.
+   */
+  FT_EXPORT( FT_Bool )
+  FT_Get_Color_Glyph_Paint( FT_Face          face,
+                            FT_UInt          base_glyph,
+                            FT_OpaquePaint*  paint );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Get_Paint_Layers
+   *
+   * @description:
+   *   Access the layers of a `PaintColrLayers` table.
+   *
+   *   If the root paint of a color glyph, or a nested paint of a 'COLR'
+   *   glyph is a `PaintColrLayers` table, this function retrieves the
+   *   layers of the `PaintColrLayers` table.
+   *
+   *   The @FT_PaintColrLayers object contains an @FT_LayerIterator, which
+   *   is used here to iterate over the layers.  Each layer is returned as
+   *   an @FT_OpaquePaint object, which then can be used with @FT_Get_Paint
+   *   to retrieve the actual paint object.
+   *
+   * @input:
+   *   face ::
+   *     A handle to the parent face object.
+   *
+   * @inout:
+   *   iterator ::
+   *     The @FT_LayerIterator from an @FT_PaintColrLayers object, for which
+   *     the layers are to be retrieved.  The internal state of the iterator
+   *     is incremented after one call to this function for retrieving one
+   *     layer.
+   *
+   * @output:
+   *   paint ::
+   *     The @FT_OpaquePaint object that references the actual paint table.
+   *     The respective actual @FT_COLR_Paint object is retrieved via
+   *     @FT_Get_Paint.
+   *
+   * @return:
+   *   Value~1 if everything is OK.  Value~0 gets returned when the paint
+   *   object can not be retrieved or any other error occurs.
+   */
+  FT_EXPORT( FT_Bool )
+  FT_Get_Paint_Layers( FT_Face            face,
+                       FT_LayerIterator*  iterator,
+                       FT_OpaquePaint*    paint );
+
+
+  /**************************************************************************
+   *
+   * @function:
+   *   FT_Get_Colorline_Stops
+   *
+   * @description:
+   *   This is an interface to color gradient information in a 'COLR' v1
+   *   table in OpenType fonts to iteratively retrieve the gradient and
+   *   solid fill information for colored glyph layers for a specified glyph
+   *   ID.
+   *
+   *     https://github.com/googlefonts/colr-gradients-spec
+   *
+   * @input:
+   *   face ::
+   *     A handle to the parent face object.
+   *
+   * @inout:
+   *   iterator ::
+   *     The @FT_ColorStopIterator retrieved configured on an @FT_ColorLine,
+   *     retrieved via paint information in
+   *     @FT_Get_Color_Glyph_Layer_Gradients.
+   *
+   * @output:
+   *   color_stop ::
+   *     Color index and alpha value for the retrieved color stop.
+   *
+   * @return:
+   *   Value~1 if everything is OK.  If there are no more color stops,
+   *   value~0 gets returned.  In case of an error, value~0 is returned
+   *   also.
+   */
+  FT_EXPORT( FT_Bool )
+  FT_Get_Colorline_Stops( FT_Face                face,
+                          FT_ColorStop*          color_stop,
+                          FT_ColorStopIterator*  iterator );
+
+
+  /**************************************************************************
+   * @function
+   *  FT_Get_Paint
+   *
+   * @description:
+   *   Access the details of a paint using an @FT_OpaquePaint opaque paint
+   *   object, which internally stores the offset to the respective `Paint`
+   *   object in the 'COLR' table.
+   *
+   * @input:
+   *   face ::
+   *     A handle to the parent face object.
+   *
+   *   opaque_paint ::
+   *     The opaque paint object for which the underlying @FT_COLR_Paint
+   *     data is to be retrieved.
+   *
+   * @output:
+   *   paint ::
+   *     The specific @FT_COLOR_Paint object containing information coming
+   *     from one of the font's `Paint*` tables.
+   *
+   * @return:
+   *   Value~1 if everything is OK.  Value~0 if no details can be found for
+   *   this paint or any other error occured.
+   */
+  FT_EXPORT( FT_Bool )
+  FT_Get_Paint( FT_Face         face,
+                FT_OpaquePaint  opaque_paint,
+                FT_COLR_Paint*  paint );
+
+
+  /**************************************************************************
+   *
    * @section:
    *   base_interface
    *
diff --git a/src/base/ftobjs.c b/src/base/ftobjs.c
index 65c37e1..c3e37f6 100644
--- a/src/base/ftobjs.c
+++ b/src/base/ftobjs.c
@@ -5568,4 +5568,40 @@
   }
 
 
+  FT_EXPORT_DEF ( FT_Bool )
+  FT_Get_Color_Glyph_Paint( FT_Face          face,
+                            FT_UInt          base_glyph,
+                            FT_OpaquePaint*  paint )
+  {
+    return 0;
+  }
+
+
+  FT_EXPORT_DEF ( FT_Bool )
+  FT_Get_Paint_Layers( FT_Face            face,
+                       FT_LayerIterator*  layer_iterator,
+                       FT_OpaquePaint*    paint )
+  {
+    return 0;
+  }
+
+
+  FT_EXPORT_DEF( FT_Bool )
+  FT_Get_Paint( FT_Face face,
+                FT_OpaquePaint  opaque_paint,
+                FT_COLR_Paint*  paint )
+  {
+    return 0;
+  }
+
+
+  FT_EXPORT_DEF ( FT_Bool )
+  FT_Get_Colorline_Stops ( FT_Face                face,
+                           FT_ColorStop *         color_stop,
+                           FT_ColorStopIterator  *iterator )
+  {
+    return 0;
+  }
+
+
 /* END */