More documentation updates.

In particular, mark the new behaviour of `FT_LOAD_COLOR' as experimental.
6 years ago · 4d51f78de9
parent 6ab36880ce
commit 4d51f78de9
6 changed files with 64 additions and 28 deletions
--- a/devel/ftoption.h
+++ b/devel/ftoption.h
@ -747,8 +747,8 @@ FT_BEGIN_HEADER
   * `T1_MAX_CHARSTRING_OPERANDS` is the charstring stack's capacity.  A
   * minimum of~16 is required.
   *
-   * The Chinese font 'MingTiEG-Medium' (covering a CNS 11643 character set)
-   * needs 256.
+   * The Chinese font 'MingTiEG-Medium' (covering the CNS 11643 character
+   * set) needs 256.
   */
 #define T1_MAX_CHARSTRINGS_OPERANDS  256

--- a/docs/CHANGES
+++ b/docs/CHANGES
@ -7,13 +7,29 @@ CHANGES BETWEEN 2.9.1 and 2.10
  II. IMPORTANT CHANGES

    - A bunch  of new functions has  been added to access  and process
-      COLR/CPAL data of OpenType fonts with coloured glyph layers.
+      COLR/CPAL data of OpenType fonts with color-layered glyphs.

        FT_Palette_Data_Get
+          Retrieve color palette data.
        FT_Palette_Select
+          Select and activate a color palette for color-layered
+          glyphs.
        FT_Palette_Set_Foreground_Color
+          Set text foreground color for palette index 0xFFFF.
+
        FT_Get_Color_Glyph_Layer
+          Get color layers for a given glyph (using an interator
+          object).
+
        FT_Bitmap_Blend
+          Blend one bitmap onto another with a given color.
+
+    - An   experimental  feature   is   the  new   behaviour  of   the
+      `FT_LOAD_COLOR' load  flag for color-layered  glyphs: Internally
+      it  sets a  flag so  that  if `FT_Render_Glyph'  is called  with
+      `FT_RENDER_MODE_NORMAL'      (or       `FT_Load_Glyph'      with
+      `FT_LOAD_RENDER'), a default blending  of the color glyph layers
+      will happen automatically for convenience.


  III. MISCELLANEOUS
@ -84,6 +100,27 @@ CHANGES BETWEEN 2.9.1 and 2.10
      removed.  [Compilation with modern compilers that use flags like
      `-fPIC' or `-fPIE' is not affected.]

+    - The  `ftdump' demo  program has  new  options `-c'  and `-C'  to
+      display charmaps  in compact and detailed  format, respectively.
+      Option `-V' has been removed.
+
+    - The `ftview', `ftstring',  and `ftgrid' demo programs  use a new
+      command line option `-d' to  specify the program window's width,
+      height, and color depth.
+
+    - The `ftview' demo program now  displays red boxes for zero-width
+      glyphs.
+
+    - `ftglyph'   has   limited   support  to   display   fonts   with
+      color-layered glyphs.  This will be improved later on.
+
+    - `ftgrid' can now display bitmap fonts also.
+
+    - The `ttdebug'  demo program has  a new  option `-f' to  select a
+      member of a TrueType collection (TTC).
+
+    - Other various improvements to the demo programs.
+

 ======================================================================

@ -321,7 +358,7 @@ CHANGES BETWEEN 2.7.1 and 2.8
      following properties can be  handled: stem darkening, LCD filter
      weights, and the random seed for the `random' CFF operator.

-    - The PCF change to show more `colourful' family names (introduced
+    - The PCF change to show more `colorful'  family names (introduced
      in version 2.7.1) was too radical; it can now be configured with
      PCF_CONFIG_OPTION_LONG_FAMILY_NAMES   at   compile   time.    If
      activated, it can  be switched off at run time  with the new pcf
@ -472,7 +509,7 @@ CHANGES BETWEEN 2.7 and 2.7.1
      and the number of CVT entries.  Please report if you encounter a
      font where the selected values are not adequate.

-    - PCF family names are made more `colourful'; they now include the
+    - PCF family names are made more `colorful';  they now include the
      foundry  and information  whether they contain  wide characters.
      For example,  you no longer get `Fixed' but  rather `Sony Fixed'
      or `Misc Fixed Wide'.
@ -756,8 +793,8 @@ CHANGES BETWEEN 2.6.1 and 2.6.2
    - The `ftstring' demo program now supports subpixel rendering; use
      key `l' to cycle through the LCD modes.

-    - The `ftstring'  demo program now supports  colour rendering; use
-      the `space' key to cycle through various colour combinations.
+    - The `ftstring'  demo program now supports  color rendering;  use
+      the `space' key to cycle through various color combinations.

    - The graphical demo programs now use a default gamma value of 1.8
      (instead of 1.2).
--- a/include/freetype/config/ftoption.h
+++ b/include/freetype/config/ftoption.h
@ -747,8 +747,8 @@ FT_BEGIN_HEADER
   * `T1_MAX_CHARSTRING_OPERANDS` is the charstring stack's capacity.  A
   * minimum of~16 is required.
   *
-   * The Chinese font 'MingTiEG-Medium' (covering a CNS 11643 character set)
-   * needs 256.
+   * The Chinese font 'MingTiEG-Medium' (covering the CNS 11643 character
+   * set) needs 256.
   */
 #define T1_MAX_CHARSTRINGS_OPERANDS  256

--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@ -2968,15 +2968,15 @@ FT_BEGIN_HEADER
   *     color bitmaps are found, they are converted to 256-level gray
   *     bitmaps, using the @FT_PIXEL_MODE_GRAY format.
   *
-   *     [Since 2.10] If the glyph index contains an entry in the face's
-   *     'COLR' table with a 'CPAL' palette table (as defined in the OpenType
-   *     specification), make @FT_Render_Glyph provide a default blending of
-   *     the color glyph layers associated with the glyph index, using the
-   *     same bitmap format as embedded color bitmap images.  This is mainly
-   *     for convenience; for full control of color layers use
+   *     [Since 2.10, experimental] If the glyph index contains an entry in
+   *     the face's 'COLR' table with a 'CPAL' palette table (as defined in
+   *     the OpenType specification), make @FT_Render_Glyph provide a default
+   *     blending of the color glyph layers associated with the glyph index,
+   *     using the same bitmap format as embedded color bitmap images.  This
+   *     is mainly for convenience; for full control of color layers use
   *     @FT_Get_Color_Glyph_Layer and FreeType's color functions like
-   *     @FT_Palette_Select instead of setting FT_LOAD_COLOR for rendering so
-   *     that the client application can handle blending by itself.
+   *     @FT_Palette_Select instead of setting @FT_LOAD_COLOR for rendering
+   *     so that the client application can handle blending by itself.
   *
   *   FT_LOAD_COMPUTE_METRICS ::
   *     [Since 2.6.1] Compute glyph metrics from the glyph data, without the
@ -3288,11 +3288,12 @@ FT_BEGIN_HEADER
   *     The render mode used to render the glyph image into a bitmap.  See
   *     @FT_Render_Mode for a list of possible values.
   *
-   *     If @FT_RENDER_MODE_NORMAL is used, the flag @FT_LOAD_COLOR can be
-   *     additionally set to make the function provide a default blending of
-   *     colored glyph layers associated with the current glyph slot
-   *     (provided the font contains such layers) instead of rendering the
-   *     glyph slot's outline.  See @FT_LOAD_COLOR for more information.
+   *     If @FT_RENDER_MODE_NORMAL is used, a previous call of @FT_Load_Glyph
+   *     with flag @FT_LOAD_COLOR makes the FT_Render_Glyph provide a default
+   *     blending of colored glyph layers associated with the current glyph
+   *     slot (provided the font contains such layers) instead of rendering
+   *     the glyph slot's outline.  This is an experimental feature; see
+   *     @FT_LOAD_COLOR for more information.
   *
   * @return:
   *   FreeType error code.  0~means success.
@ -4126,8 +4127,9 @@ FT_BEGIN_HEADER
   *   objects (like @FT_Get_Glyph or @FT_Glyph_To_Bitmap) don't have access
   *   to this information.
   *
-   *   @FT_Render_Glyph, however, handles colored glyph layers automatically
-   *   if the @FT_LOAD_COLOR flag is passed to it.
+   *   Note that @FT_Render_Glyph is able to handle colored glyph layers
+   *   automatically if the @FT_LOAD_COLOR flag is passed to a previous call
+   *   to @FT_Load_Glyph.  [This is an experimental feature.]
   *
   * @example:
   *   ```
--- a/include/freetype/ftcolor.h
+++ b/include/freetype/ftcolor.h
@ -249,9 +249,6 @@ FT_BEGIN_HEADER
   *   FreeType error code.  0~means success.
   *
   * @note:
-   *   The number of color entries is given by the `num_palette_entries`
-   *   field in the @FT_Palette_Data structure.
-   *
   *   The array pointed to by `apalette_entries` is owned and managed by
   *   FreeType.
   *
--- a/src/base/ftbitmap.c
+++ b/src/base/ftbitmap.c
@ -844,7 +844,7 @@
    if ( !( source_->width && source_->rows ) )
      return FT_Err_Ok;               /* nothing to do */

-    /* assure integer pixel offset s */
+    /* assure integer pixel offsets */
    source_offset.x = FT_PIX_FLOOR( source_offset_.x );
    source_offset.y = FT_PIX_FLOOR( source_offset_.y );
    target_offset.x = FT_PIX_FLOOR( atarget_offset->x );