[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[ft-devel] CPAL interface
From: |
Werner LEMBERG |
Subject: |
[ft-devel] CPAL interface |
Date: |
Tue, 15 May 2018 09:11:43 +0200 (CEST) |
Folks,
here is my draft for accessing the CPAL table. Please comment.
The header file is called `ftcolor.h', not `ftcpal.h' – I want to make
this generic, since there might be other color stuff (for other font
formats) in the future...
Werner
======================================================================
/***************************************************************************/
/* */
/* 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 <ft2build.h>
#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 );
/* */
FT_END_HEADER
#endif /* FTCOLOR_H_ */
/* END */
- [ft-devel] CPAL interface,
Werner LEMBERG <=
- Re: [ft-devel] CPAL interface, Alexei Podtelezhnikov, 2018/05/15
- Re: [ft-devel] CPAL interface, Werner LEMBERG, 2018/05/16
- Re: [ft-devel] CPAL interface, Alexei Podtelezhnikov, 2018/05/17
- Re: [ft-devel] CPAL interface, Werner LEMBERG, 2018/05/18
- Re: [ft-devel] CPAL interface, Alexei Podtelezhnikov, 2018/05/18
- Re: [ft-devel] CPAL interface, Werner LEMBERG, 2018/05/18
- Re: [ft-devel] CPAL interface, Alexei Podtelezhnikov, 2018/05/18
- Re: [ft-devel] CPAL interface, Werner LEMBERG, 2018/05/19