ref: 7c7004d60cd5fee4675fd33bf2f5c422c802e0b8
parent: 172904ee3a3e0d14015595946d8988f847b09158
author: Werner Lemberg <[email protected]>
date: Wed Jun 6 13:37:51 EDT 2018
New `ftcolor.h' draft.
--- a/include/freetype/ftcolor.h
+++ b/include/freetype/ftcolor.h
@@ -41,7 +41,7 @@
* 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 @@
/**************************************************************************
*
- * @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 @@
* 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,87 +114,70 @@
/**************************************************************************
*
- * @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.
+ * This structure holds the data of the `CPAL' table.
*
- * @input:
- * face ::
- * The source face handle.
+ * @fields:
+ * num_palettes ::
+ * The number of palettes.
*
- * @output:
- * apalette_types ::
- * A read-only array of palette types. NULL if the font's `CPAL'
- * table doesn't contain appropriate data.
+ * 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.
*
- * @return:
- * FreeType error code. 0~means success.
+ * An empty name ID in the `CPAL' table gets represented as value
+ * 0xFFFF.
*
- * @note:
- * The number of palette types can be retrieved with
- * @FT_Palette_Get_Size.
+ * NULL if the font's `CPAL' table doesn't contain appropriate data.
*
- * This function always returns an error if the config macro
- * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'.
+ * 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.
*
- * @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
+ * num_palette_entries ::
+ * The number of entries in a single palette. All palettes have the
+ * same size.
*
- * @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.
+ * 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.
*
- * @input:
- * face ::
- * The source face handle.
+ * An empty entry name ID in the `CPAL' table gets represented as
+ * value 0xFFFF.
*
- * @output:
- * aentry_names ::
- * A read-only array of palette entry name IDs. NULL if the font's
- * `CPAL' table doesn't contain appropriate data.
+ * NULL if the font's `CPAL' table doesn't contain appropriate data.
*
- * Use function @FT_Get_Sfnt_Name to map entry name IDs to a name
- * strings.
- *
- * @return:
- * FreeType error code. 0~means success.
- *
* @note:
- * The number of palette entries can be retrieved with
- * @FT_Palette_Get_Size.
+ * Use function @FT_Get_Sfnt_Name to map name IDs and entry name IDs to
+ * name strings.
*
- * 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'.
- *
* @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;
+
+
/**************************************************************************
*
* @func:
@@ -311,8 +214,8 @@
* 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 @@
* 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'.
*