From 93363cd737a762fbc0e482eef386097b1ca04930 Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Sun, 20 May 2018 22:50:00 +0200 Subject: [PATCH] * include/freetype/ftcolor.h: New file. This is an interface to the `CPAL' OpenType table. No implementation yet. --- ChangeLog | 7 + include/freetype/ftcolor.h | 365 +++++++++++++++++++++++++++++++++++++ 2 files changed, 372 insertions(+) create mode 100644 include/freetype/ftcolor.h diff --git a/ChangeLog b/ChangeLog index 043712d47..f5d676df3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2018-05-20 Werner Lemberg + + * include/freetype/ftcolor.h: New file. + + This is an interface to the `CPAL' OpenType table. No + implementation yet. + 2018-05-18 Alexei Podtelezhnikov * include/freetype/internal/ftcalc.h (FT_MSB): Verified `_MSC_VER'. diff --git a/include/freetype/ftcolor.h b/include/freetype/ftcolor.h new file mode 100644 index 000000000..91183b8e4 --- /dev/null +++ b/include/freetype/ftcolor.h @@ -0,0 +1,365 @@ +/***************************************************************************/ +/* */ +/* ftcolor.h */ +/* */ +/* FreeType's glyph color management (specification). */ +/* */ +/* Copyright 2018 by */ +/* David Turner, Robert Wilhelm, and Werner Lemberg. */ +/* */ +/* This file is part of the FreeType project, and may only be used, */ +/* modified, and distributed under the terms of the FreeType project */ +/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ +/* this file you indicate that you have read the license and */ +/* understand and accept it fully. */ +/* */ +/***************************************************************************/ + + +#ifndef FTCOLOR_H_ +#define FTCOLOR_H_ + +#include +#include FT_FREETYPE_H + +#ifdef FREETYPE_H +#error "freetype.h of FreeType 1 has been loaded!" +#error "Please fix the directory search order for header files" +#error "so that freetype.h of FreeType 2 is found first." +#endif + + +FT_BEGIN_HEADER + + + /************************************************************************** + * + * @section: + * color_management + * + * @title: + * Glyph Color Management + * + * @abstract: + * Retrieving and manipulating OpenType's `CPAL' table entries. + * + * @description: + * The functions described here allow access and manipulation of color + * palette entries in OpenType's `CPAL' table. + */ + + + /************************************************************************** + * + * @struct: + * FT_Color + * + * @description: + * This structure models a BGRA color value of a `CPAL' palette entry. + * + * The used color space is sRGB; the colors are not pre-multiplied, and + * alpha values must be explicitly set. + * + * @fields: + * blue :: + * Blue value. + * + * green :: + * Green value. + * + * red :: + * Red value. + * + * alpha :: + * Alpha value, giving the red, green, and blue color's opacity. + * + * @since: + * 2.10.0 + */ + typedef struct FT_Color_ + { + FT_Byte blue; + FT_Byte green; + FT_Byte red; + FT_Byte alpha; + + } 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.0 + */ + FT_EXPORT( FT_Error ) + FT_Palette_Get_Size( FT_Face face, + FT_UShort* anum_palettes, + FT_UShort* anum_palette_entries ); + + + /************************************************************************** + * + * @func: + * FT_Palette_Get_Names + * + * @description: + * Get the palette names, for example `dark' or `light'. + * + * @input: + * face :: + * The source face handle. + * + * @output: + * apalette_names :: + * A read-only array of palette names, taken from the font's `name' + * table. NULL if the font's `CPAL' table doesn't contain appropriate + * data. + * + * @return: + * FreeType error code. 0~means success. + * + * @note: + * The number of palettes can be retrieved with @FT_Palette_Get_Size. + * + * An empty name entry in the `CPAL' table gets represented as an empty + * string. + * + * This function always returns an error if the config macro + * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. + * + * @since: + * 2.10.0 + */ + FT_EXPORT( FT_Error ) + FT_Palette_Get_Names( FT_Face face, + const FT_String* const* apalette_names ); + + + /************************************************************************** + * + * @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. + * + * @values: + * FT_PALETTE_USABLE_WITH_LIGHT_BACKGROUND :: + * The palette is appropriate to use when displaying the font on a + * light background such as white. + * + * FT_PALETTE_USABLE_WITH_DARK_BACKGROUND :: + * 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.0 + */ +#define FT_PALETTE_USABLE_WITH_LIGHT_BACKGROUND 0x01 +#define FT_PALETTE_USABLE_WITH_DARK_BACKGROUND 0x02 + + + /************************************************************************** + * + * @func: + * FT_Palette_Get_Types + * + * @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. + * + * @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. + * + * @note: + * The number of palette types can be retrieved with + * @FT_Palette_Get_Size. + * + * This function always returns an error if the config macro + * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. + * + * @since: + * 2.10.0 + */ + FT_EXPORT( FT_Error ) + FT_Palette_Get_Types( FT_Face face, + const FT_UShort* apalette_types ); + + + /************************************************************************** + * + * @func: + * FT_Palette_Get_Entry_Names + * + * @description: + * Get the palette entry names. In each palette, entries with the same + * index have the same function. For example, index~0 might be the + * string `outline' to indicate that this palette entry is used for + * outlines, index~1 might be `fill' to indicate the filling color + * palette entry, etc. + * + * @input: + * face :: + * The source face handle. + * + * @output: + * aentry_names :: + * A read-only array of palette entry names, taken from the font's + * `name' table. NULL if the font's `CPAL' table doesn't contain + * appropriate data. + * + * @return: + * FreeType error code. 0~means success. + * + * @note: + * The number of palette entries can be retrieved with + * @FT_Palette_Get_Size. + * + * An empty name entry in the `CPAL' table gets represented as an empty + * string. + * + * This function always returns an error if the config macro + * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. + * + * @since: + * 2.10.0 + */ + FT_EXPORT( FT_Error ) + FT_Palette_Get_Entry_Names( FT_Face face, + const FT_String* const* aentry_names ); + + + /************************************************************************** + * + * @func: + * FT_Palette_Select + * + * @description: + * This function has two purposes. + * + * (1) It activates a palette for rendering color glyphs, and + * + * (2) it retrieves all (unmodified) color entries of this palette. This + * function returns a read-write array, which means that a calling + * application can modify the palette entries on demand. + * + * A corollary of (2) is that calling the function, then modifying some + * values, then calling the function again with the same arguments resets + * all color entries to the original `CPAL' values; all user modifications + * are lost. + * + * @input: + * face :: + * The source face handle. + * + * palette_index :: + * The palette index. + * + * @output: + * apalette_entries :: + * An array of color entries for a palette with index `palette_index'. + * If `apalette_entries' is set to NULL, no array gets returned (and + * no color entries can be modified). + * + * @return: + * FreeType error code. 0~means success. + * + * @note: + * The number of color entries can be retrieved with + * @FT_Palette_Get_Size. + * + * The array pointed to by `apalette_entries' is owned and managed by + * FreeType. + * + * This function always returns an error if the config macro + * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. + * + * @since: + * 2.10.0 + */ + FT_EXPORT( FT_Error ) + FT_Palette_Select( FT_Face face, + FT_UShort palette_index, + FT_Color* *apalette_entries ); + + + /************************************************************************** + * + * @func: + * FT_Palette_Set_Foreground_Color + * + * @description: + * `CPAL' uses color index 0xFFFF to indicate a `text foreground color'. + * This function sets this value. + * + * @input: + * face :: + * The source face handle. + * + * foreground_color :: + * An `FT_Color' structure to define the text foreground color. + * + * @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.0 + */ + FT_EXPORT( FT_Error ) + FT_Palette_Set_Foreground_COlor( FT_Face face, + FT_Color foreground_color ); + + /* */ + + +FT_END_HEADER + +#endif /* FTCOLOR_H_ */ + + +/* END */