[freetype2] master 93363cd: * include/freetype/ftcolor.h: New file.

[Werner LEMBERG]

branch: master
commit 93363cd737a762fbc0e482eef386097b1ca04930
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>

    * 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(+)

diff --git a/ChangeLog b/ChangeLog
index 043712d..f5d676d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2018-05-20  Werner Lemberg  <address@hidden>
+
+       * include/freetype/ftcolor.h: New file.
+
+       This is an interface to the `CPAL' OpenType table.  No
+       implementation yet.
+
 2018-05-18  Alexei Podtelezhnikov  <address@hidden>
 
        * 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 0000000..91183b8
--- /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 <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 );
+
+
+  /**************************************************************************
+   *
+   * @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 */