2018-06-03 22:00:42 +02:00
|
|
|
/****************************************************************************
|
|
|
|
*
|
|
|
|
* ftcolor.h
|
|
|
|
*
|
|
|
|
* FreeType's glyph color management (specification).
|
|
|
|
*
|
2021-01-17 07:18:48 +01:00
|
|
|
* Copyright (C) 2018-2021 by
|
2018-06-03 22:00:42 +02:00
|
|
|
* 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.
|
|
|
|
*
|
|
|
|
*/
|
2018-05-20 22:50:00 +02:00
|
|
|
|
|
|
|
|
|
|
|
#ifndef FTCOLOR_H_
|
|
|
|
#define FTCOLOR_H_
|
|
|
|
|
2020-06-08 13:31:55 +02:00
|
|
|
#include <freetype/freetype.h>
|
2018-05-20 22:50:00 +02:00
|
|
|
|
|
|
|
#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:
|
2019-02-21 09:19:09 +01:00
|
|
|
* Retrieving and manipulating OpenType's 'CPAL' table data.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @description:
|
|
|
|
* The functions described here allow access and manipulation of color
|
2019-02-21 09:19:09 +01:00
|
|
|
* palette entries in OpenType's 'CPAL' tables.
|
2018-05-20 22:50:00 +02:00
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/**************************************************************************
|
|
|
|
*
|
|
|
|
* @struct:
|
|
|
|
* FT_Color
|
|
|
|
*
|
|
|
|
* @description:
|
2019-02-21 09:19:09 +01:00
|
|
|
* This structure models a BGRA color value of a 'CPAL' palette entry.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* 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:
|
2018-05-30 09:34:57 +02:00
|
|
|
* 2.10
|
2018-05-20 22:50:00 +02:00
|
|
|
*/
|
|
|
|
typedef struct FT_Color_
|
|
|
|
{
|
|
|
|
FT_Byte blue;
|
|
|
|
FT_Byte green;
|
|
|
|
FT_Byte red;
|
|
|
|
FT_Byte alpha;
|
|
|
|
|
|
|
|
} FT_Color;
|
|
|
|
|
|
|
|
|
|
|
|
/**************************************************************************
|
|
|
|
*
|
|
|
|
* @enum:
|
|
|
|
* FT_PALETTE_XXX
|
|
|
|
*
|
|
|
|
* @description:
|
2018-08-24 18:52:30 +02:00
|
|
|
* A list of bit field constants used in the `palette_flags` array of the
|
|
|
|
* @FT_Palette_Data structure to indicate for which background a palette
|
|
|
|
* with a given index is usable.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @values:
|
2018-06-21 00:21:09 +02:00
|
|
|
* FT_PALETTE_FOR_LIGHT_BACKGROUND ::
|
2018-05-20 22:50:00 +02:00
|
|
|
* The palette is appropriate to use when displaying the font on a
|
|
|
|
* light background such as white.
|
|
|
|
*
|
2018-06-21 00:21:09 +02:00
|
|
|
* FT_PALETTE_FOR_DARK_BACKGROUND ::
|
2018-08-24 18:52:30 +02:00
|
|
|
* The palette is appropriate to use when displaying the font on a dark
|
|
|
|
* background such as black.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @since:
|
2018-05-30 09:34:57 +02:00
|
|
|
* 2.10
|
2018-05-20 22:50:00 +02:00
|
|
|
*/
|
2018-06-21 00:21:09 +02:00
|
|
|
#define FT_PALETTE_FOR_LIGHT_BACKGROUND 0x01
|
|
|
|
#define FT_PALETTE_FOR_DARK_BACKGROUND 0x02
|
2018-05-20 22:50:00 +02:00
|
|
|
|
|
|
|
|
|
|
|
/**************************************************************************
|
|
|
|
*
|
2018-06-06 17:37:51 +02:00
|
|
|
* @struct:
|
2018-06-10 21:37:15 +02:00
|
|
|
* FT_Palette_Data
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @description:
|
2019-02-21 09:19:09 +01:00
|
|
|
* This structure holds the data of the 'CPAL' table.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2018-06-06 17:37:51 +02:00
|
|
|
* @fields:
|
|
|
|
* num_palettes ::
|
|
|
|
* The number of palettes.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2018-06-06 17:37:51 +02:00
|
|
|
* palette_name_ids ::
|
2019-08-06 20:38:17 +02:00
|
|
|
* An optional read-only array of palette name IDs with `num_palettes`
|
|
|
|
* elements, corresponding to entries like 'dark' or 'light' in the
|
|
|
|
* font's 'name' table.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2019-02-21 09:19:09 +01:00
|
|
|
* An empty name ID in the 'CPAL' table gets represented as value
|
2018-06-06 17:37:51 +02:00
|
|
|
* 0xFFFF.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2019-02-21 09:19:09 +01:00
|
|
|
* `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2018-07-02 11:50:04 +02:00
|
|
|
* palette_flags ::
|
2019-08-06 20:38:17 +02:00
|
|
|
* An optional read-only array of palette flags with `num_palettes`
|
|
|
|
* elements. Possible values are an ORed combination of
|
2018-06-21 00:21:09 +02:00
|
|
|
* @FT_PALETTE_FOR_LIGHT_BACKGROUND and
|
|
|
|
* @FT_PALETTE_FOR_DARK_BACKGROUND.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2019-02-21 09:19:09 +01:00
|
|
|
* `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2018-06-06 17:37:51 +02:00
|
|
|
* num_palette_entries ::
|
|
|
|
* The number of entries in a single palette. All palettes have the
|
|
|
|
* same size.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2018-06-06 17:37:51 +02:00
|
|
|
* palette_entry_name_ids ::
|
2019-08-06 20:38:17 +02:00
|
|
|
* An optional read-only array of palette entry name IDs with
|
2018-08-24 18:52:30 +02:00
|
|
|
* `num_palette_entries`. In each palette, entries with the same index
|
|
|
|
* have the same function. For example, index~0 might correspond to
|
2019-02-21 09:19:09 +01:00
|
|
|
* string 'outline' in the font's 'name' table to indicate that this
|
2018-08-24 18:52:30 +02:00
|
|
|
* palette entry is used for outlines, index~1 might correspond to
|
|
|
|
* 'fill' to indicate the filling color palette entry, etc.
|
2018-05-30 21:21:19 +02:00
|
|
|
*
|
2019-02-21 09:19:09 +01:00
|
|
|
* An empty entry name ID in the 'CPAL' table gets represented as value
|
2018-08-24 18:52:30 +02:00
|
|
|
* 0xFFFF.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2019-02-21 09:19:09 +01:00
|
|
|
* `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @note:
|
2018-06-06 17:37:51 +02:00
|
|
|
* Use function @FT_Get_Sfnt_Name to map name IDs and entry name IDs to
|
|
|
|
* name strings.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2019-08-05 10:00:41 +02:00
|
|
|
* Use function @FT_Palette_Select to get the colors associated with a
|
|
|
|
* palette entry.
|
|
|
|
*
|
2018-05-20 22:50:00 +02:00
|
|
|
* @since:
|
2018-05-30 09:34:57 +02:00
|
|
|
* 2.10
|
2018-05-20 22:50:00 +02:00
|
|
|
*/
|
2018-06-10 21:37:15 +02:00
|
|
|
typedef struct FT_Palette_Data_ {
|
2018-06-06 17:37:51 +02:00
|
|
|
FT_UShort num_palettes;
|
|
|
|
const FT_UShort* palette_name_ids;
|
2018-07-02 11:50:04 +02:00
|
|
|
const FT_UShort* palette_flags;
|
2018-06-06 17:37:51 +02:00
|
|
|
|
|
|
|
FT_UShort num_palette_entries;
|
|
|
|
const FT_UShort* palette_entry_name_ids;
|
|
|
|
|
2018-06-10 21:37:15 +02:00
|
|
|
} FT_Palette_Data;
|
2018-05-20 22:50:00 +02:00
|
|
|
|
|
|
|
|
2018-06-06 17:49:17 +02:00
|
|
|
/**************************************************************************
|
|
|
|
*
|
2018-06-17 11:22:37 +02:00
|
|
|
* @function:
|
2018-06-10 21:37:15 +02:00
|
|
|
* FT_Palette_Data_Get
|
2018-06-06 17:49:17 +02:00
|
|
|
*
|
|
|
|
* @description:
|
|
|
|
* Retrieve the face's color palette data.
|
|
|
|
*
|
|
|
|
* @input:
|
|
|
|
* face ::
|
|
|
|
* The source face handle.
|
|
|
|
*
|
|
|
|
* @output:
|
|
|
|
* apalette ::
|
2018-06-10 21:37:15 +02:00
|
|
|
* A pointer to an @FT_Palette_Data structure.
|
2018-06-06 17:49:17 +02:00
|
|
|
*
|
|
|
|
* @return:
|
|
|
|
* FreeType error code. 0~means success.
|
|
|
|
*
|
|
|
|
* @note:
|
2018-06-10 21:37:15 +02:00
|
|
|
* All arrays in the returned @FT_Palette_Data structure are read-only.
|
2018-06-06 17:49:17 +02:00
|
|
|
*
|
|
|
|
* This function always returns an error if the config macro
|
2018-08-24 18:52:30 +02:00
|
|
|
* `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
|
2018-06-06 17:49:17 +02:00
|
|
|
*
|
|
|
|
* @since:
|
|
|
|
* 2.10
|
|
|
|
*/
|
|
|
|
FT_EXPORT( FT_Error )
|
2018-06-10 21:37:15 +02:00
|
|
|
FT_Palette_Data_Get( FT_Face face,
|
|
|
|
FT_Palette_Data *apalette );
|
2018-06-06 17:49:17 +02:00
|
|
|
|
|
|
|
|
2018-05-20 22:50:00 +02:00
|
|
|
/**************************************************************************
|
|
|
|
*
|
2018-06-17 11:22:37 +02:00
|
|
|
* @function:
|
2018-05-20 22:50:00 +02:00
|
|
|
* 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
|
2019-02-21 09:19:09 +01:00
|
|
|
* all color entries to the original 'CPAL' values; all user modifications
|
2018-05-20 22:50:00 +02:00
|
|
|
* are lost.
|
|
|
|
*
|
|
|
|
* @input:
|
|
|
|
* face ::
|
|
|
|
* The source face handle.
|
|
|
|
*
|
|
|
|
* palette_index ::
|
|
|
|
* The palette index.
|
|
|
|
*
|
|
|
|
* @output:
|
2018-06-11 09:02:06 +02:00
|
|
|
* apalette ::
|
2019-02-20 16:04:48 +01:00
|
|
|
* An array of color entries for a palette with index `palette_index`,
|
|
|
|
* having `num_palette_entries` elements (as found in the
|
2019-02-20 16:18:40 +01:00
|
|
|
* `FT_Palette_Data` structure). If `apalette` is set to `NULL`, no
|
2019-02-20 16:04:48 +01:00
|
|
|
* array gets returned (and no color entries can be modified).
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
2019-02-20 16:18:40 +01:00
|
|
|
* In case the font doesn't support color palettes, `NULL` is returned.
|
2018-06-10 21:37:15 +02:00
|
|
|
*
|
2018-05-20 22:50:00 +02:00
|
|
|
* @return:
|
|
|
|
* FreeType error code. 0~means success.
|
|
|
|
*
|
|
|
|
* @note:
|
2018-08-24 18:52:30 +02:00
|
|
|
* The array pointed to by `apalette_entries` is owned and managed by
|
2018-05-20 22:50:00 +02:00
|
|
|
* FreeType.
|
|
|
|
*
|
|
|
|
* This function always returns an error if the config macro
|
2018-08-24 18:52:30 +02:00
|
|
|
* `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @since:
|
2018-05-30 09:34:57 +02:00
|
|
|
* 2.10
|
2018-05-20 22:50:00 +02:00
|
|
|
*/
|
|
|
|
FT_EXPORT( FT_Error )
|
|
|
|
FT_Palette_Select( FT_Face face,
|
|
|
|
FT_UShort palette_index,
|
2018-06-11 09:02:06 +02:00
|
|
|
FT_Color* *apalette );
|
2018-05-20 22:50:00 +02:00
|
|
|
|
|
|
|
|
|
|
|
/**************************************************************************
|
|
|
|
*
|
2018-06-17 11:22:37 +02:00
|
|
|
* @function:
|
2018-05-20 22:50:00 +02:00
|
|
|
* FT_Palette_Set_Foreground_Color
|
|
|
|
*
|
|
|
|
* @description:
|
2019-02-21 09:19:09 +01:00
|
|
|
* 'COLR' uses palette index 0xFFFF to indicate a 'text foreground
|
2018-06-11 09:02:06 +02:00
|
|
|
* color'. This function sets this value.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @input:
|
|
|
|
* face ::
|
|
|
|
* The source face handle.
|
|
|
|
*
|
|
|
|
* foreground_color ::
|
2018-08-24 18:52:30 +02:00
|
|
|
* An `FT_Color` structure to define the text foreground color.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @return:
|
|
|
|
* FreeType error code. 0~means success.
|
|
|
|
*
|
|
|
|
* @note:
|
2018-06-06 17:37:51 +02:00
|
|
|
* If this function isn't called, the text foreground color is set to
|
2018-06-07 06:49:44 +02:00
|
|
|
* white opaque (BGRA value 0xFFFFFFFF) if
|
2018-08-24 18:52:30 +02:00
|
|
|
* @FT_PALETTE_FOR_DARK_BACKGROUND is present for the current palette,
|
|
|
|
* and black opaque (BGRA value 0x000000FF) otherwise, including the case
|
2019-02-21 09:19:09 +01:00
|
|
|
* that no palette types are available in the 'CPAL' table.
|
2018-06-06 17:37:51 +02:00
|
|
|
*
|
2018-05-20 22:50:00 +02:00
|
|
|
* This function always returns an error if the config macro
|
2018-08-24 18:52:30 +02:00
|
|
|
* `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
|
2018-05-20 22:50:00 +02:00
|
|
|
*
|
|
|
|
* @since:
|
2018-05-30 09:34:57 +02:00
|
|
|
* 2.10
|
2018-05-20 22:50:00 +02:00
|
|
|
*/
|
|
|
|
FT_EXPORT( FT_Error )
|
2018-05-30 21:21:19 +02:00
|
|
|
FT_Palette_Set_Foreground_Color( FT_Face face,
|
2018-05-20 22:50:00 +02:00
|
|
|
FT_Color foreground_color );
|
|
|
|
|
|
|
|
/* */
|
|
|
|
|
|
|
|
|
|
|
|
FT_END_HEADER
|
|
|
|
|
|
|
|
#endif /* FTCOLOR_H_ */
|
|
|
|
|
|
|
|
|
|
|
|
/* END */
|