From 7c7004d60cd5fee4675fd33bf2f5c422c802e0b8 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Wed, 6 Jun 2018 17:37:51 +0200 Subject: [PATCH] New `ftcolor.h' draft. --- include/freetype/ftcolor.h | 200 ++++++++++--------------------------- 1 file 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 @@ -86,91 +86,15 @@ FT_BEGIN_HEADER } FT_Color; - /************************************************************************** - * - * @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'. *