New `ftcolor.h' draft.

1 files changed, 53 insertions, 147 deletions

diff --git a/include/freetype/ftcolor.h b/include/freetype/ftcolor.h
index 4c326c394..c11998111 100644
--- a/include/freetype/ftcolor.h
+++ b/include/freetype/ftcolor.h
@@ -41,7 +41,7 @@ FT_BEGIN_HEADER
    *   Glyph Color Management
    *
    * @abstract:
-   *   Retrieving and manipulating OpenType's `CPAL' table entries.
+   *   Retrieving and manipulating OpenType's `CPAL' table data.
    *
    * @description:
    *   The functions described here allow access and manipulation of color
@@ -88,89 +88,13 @@ FT_BEGIN_HEADER
 
   /**************************************************************************
    *
-   * @func:
-   *   FT_Palette_Get_Size
-   *
-   * @description:
-   *   Get the number of palettes in the `CPAL' table and the number of
-   *   entries in a palette (all palettes have the same number of entries).
-   *
-   * @input:
-   *   face ::
-   *     The source face handle.
-   *
-   * @output:
-   *   anum_palettes ::
-   *     The number of palettes.
-   *
-   *   anum_palette_entries ::
-   *     The number of entries in a single palette.
-   *
-   * @return:
-   *   FreeType error code.  0~means success.
-   *
-   * @note:
-   *   This function always returns an error if the config macro
-   *   `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'.
-   *
-   * @since:
-   *   2.10
-   */
-  FT_EXPORT( FT_Error )
-  FT_Palette_Get_Size( FT_Face     face,
-                       FT_UShort*  anum_palettes,
-                       FT_UShort*  anum_palette_entries );
-
-
-  /**************************************************************************
-   *
-   * @func:
-   *   FT_Palette_Get_Name_IDs
-   *
-   * @description:
-   *   Get the palette name IDs, which correspond to entries like `dark' or
-   *   `light' in the font's `name' table.
-   *
-   * @input:
-   *   face ::
-   *     The source face handle.
-   *
-   * @output:
-   *   palette_name_ids ::
-   *     A read-only array of palette name IDs.  NULL if the font's `CPAL'
-   *     table doesn't contain appropriate data.
-   *
-   *     Use function @FT_Get_Sfnt_Name to map name IDs to a name strings.
-   *
-   * @return:
-   *   FreeType error code.  0~means success.
-   *
-   * @note:
-   *   The number of palettes can be retrieved with @FT_Palette_Get_Size.
-   *
-   *   An empty name ID in the `CPAL' table gets represented as value
-   *   0xFFFF.
-   *
-   *   This function always returns an error if the config macro
-   *   `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'.
-   *
-   * @since:
-   *   2.10
-   */
-  FT_EXPORT( FT_Error )
-  FT_Palette_Get_Name_IDs( FT_Face           face,
-                           const FT_UShort*  palette_name_ids );
-
-
-  /**************************************************************************
-   *
    * @enum:
    *   FT_PALETTE_XXX
    *
    * @description:
-   *   A list of bit field constants returned by function
-   *   @FT_Palette_Get_Types to indicate for which background a given
-   *   palette is usable.
+   *   A list of bit field constants used in the `palette_types' array of
+   *   the @FT_Palette structure to indicate for which background a palette
+   *   with a given index is usable.
    *
    * @values:
    *   FT_PALETTE_USABLE_WITH_LIGHT_BACKGROUND ::
@@ -181,10 +105,6 @@ FT_BEGIN_HEADER
    *     The palette is appropriate to use when displaying the font on a
    *     dark background such as black.
    *
-   * @note:
-   *   The number of palette types can be retrieved with
-   *   @FT_Palette_Get_Size.
-   *
    * @since:
    *   2.10
    */
@@ -194,85 +114,68 @@ FT_BEGIN_HEADER
 
   /**************************************************************************
    *
-   * @func:
-   *   FT_Palette_Get_Types
+   * @struct:
+   *   FT_Palette
    *
    * @description:
-   *   Get the palette types.  Possible values are an ORed combination of
-   *   @FT_PALETTE_USABLE_WITH_LIGHT_BACKGROUND and
-   *   @FT_PALETTE_USABLE_WITH_DARK_BACKGROUND.
-   *
-   * @input:
-   *   face ::
-   *     The source face handle.
+   *   This structure holds the data of the `CPAL' table.
    *
-   * @output:
-   *   apalette_types ::
-   *     A read-only array of palette types.  NULL if the font's `CPAL'
-   *     table doesn't contain appropriate data.
-   *
-   * @return:
-   *   FreeType error code.  0~means success.
+   * @fields:
+   *   num_palettes ::
+   *     The number of palettes.
    *
-   * @note:
-   *   The number of palette types can be retrieved with
-   *   @FT_Palette_Get_Size.
+   *   palette_name_ids ::
+   *     A read-only array of palette name IDs with `num_palettes' elements,
+   *     corresponding to entries like `dark' or `light' in the font's
+   *     `name' table.
    *
-   *   This function always returns an error if the config macro
-   *   `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'.
+   *     An empty name ID in the `CPAL' table gets represented as value
+   *     0xFFFF.
    *
-   * @since:
-   *   2.10
-   */
-  FT_EXPORT( FT_Error )
-  FT_Palette_Get_Types( FT_Face           face,
-                        const FT_UShort*  apalette_types );
-
-
-  /**************************************************************************
+   *     NULL if the font's `CPAL' table doesn't contain appropriate data.
    *
-   * @func:
-   *   FT_Palette_Get_Entry_Name_IDs
+   *   palette_types ::
+   *     A read-only array of palette types with `num_palettes' elements. 
+   *     Possible values are an ORed combination of
+   *     @FT_PALETTE_USABLE_WITH_LIGHT_BACKGROUND and
+   *     @FT_PALETTE_USABLE_WITH_DARK_BACKGROUND.
    *
-   * @description:
-   *   Get the palette entry name IDs.  In each palette, entries with the
-   *   same index have the same function.  For example, index~0 might
-   *   correspond to string `outline' in the font's `name' table to indicate
-   *   that this palette entry is used for outlines, index~1 might
-   *   correspond to `fill' to indicate the filling color palette entry,
-   *   etc.
+   *     NULL if the font's `CPAL' table doesn't contain appropriate data.
    *
-   * @input:
-   *   face ::
-   *     The source face handle.
+   *   num_palette_entries ::
+   *     The number of entries in a single palette.  All palettes have the
+   *     same size.
    *
-   * @output:
-   *   aentry_names ::
-   *     A read-only array of palette entry name IDs.  NULL if the font's
-   *     `CPAL' table doesn't contain appropriate data.
+   *   palette_entry_name_ids ::
+   *     A read-only array of palette entry name IDs with
+   *     `num_palette_entries'.  In each palette, entries with the same
+   *     index have the same function.  For example, index~0 might
+   *     correspond to string `outline' in the font's `name' table to
+   *     indicate that this palette entry is used for outlines, index~1
+   *     might correspond to `fill' to indicate the filling color palette
+   *     entry, etc.
    *
-   *     Use function @FT_Get_Sfnt_Name to map entry name IDs to a name
-   *     strings.
+   *     An empty entry name ID in the `CPAL' table gets represented as
+   *     value 0xFFFF.
    *
-   * @return:
-   *   FreeType error code.  0~means success.
+   *     NULL if the font's `CPAL' table doesn't contain appropriate data.
    *
    * @note:
-   *   The number of palette entries can be retrieved with
-   *   @FT_Palette_Get_Size.
-   *
-   *   An empty entry name ID in the `CPAL' table gets represented as value
-   *   0xFFFF.
-   *
-   *   This function always returns an error if the config macro
-   *   `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'.
+   *   Use function @FT_Get_Sfnt_Name to map name IDs and entry name IDs to
+   *   name strings.
    *
    * @since:
    *   2.10
    */
-  FT_EXPORT( FT_Error )
-  FT_Palette_Get_Entry_Name_IDs( FT_Face           face,
-                                 const FT_UShort*  palette_entry_name_ids );
+  typedef FT_Palette_ {
+    FT_UShort         num_palettes;
+    const FT_UShort*  palette_name_ids;
+    const FT_UShort*  palette_types;
+
+    FT_UShort         num_palette_entries;
+    const FT_UShort*  palette_entry_name_ids;
+
+  } FT_Palette;
 
 
   /**************************************************************************
@@ -311,8 +214,8 @@ FT_BEGIN_HEADER
    *   FreeType error code.  0~means success.
    *
    * @note:
-   *   The number of color entries can be retrieved with
-   *   @FT_Palette_Get_Size.
+   *   The number of color entries is given by the `num_palette_entries'
+   *   field in the @FT_Palette structure.
    *
    *   The array pointed to by `apalette_entries' is owned and managed by
    *   FreeType.
@@ -349,6 +252,9 @@ FT_BEGIN_HEADER
    *   FreeType error code.  0~means success.
    *
    * @note:
+   *   If this function isn't called, the text foreground color is set to
+   *   black (BGRA value 0xFFFFFFFF).
+   *
    *   This function always returns an error if the config macro
    *   `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'.
    *