[ft-devel] CPAL interface

[Werner LEMBERG]

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 */