[freetype2] master 4d51f78 2/2: More documentation updates.

[Werner LEMBERG]

branch: master
commit 4d51f78de9b26de3d182f17b7aa47eb644a708d4
Author: Werner Lemberg <address@hidden>
Commit: Werner Lemberg <address@hidden>

    More documentation updates.
    
    In particular, mark the new behaviour of `FT_LOAD_COLOR' as experimental.
---
 devel/ftoption.h                   |  4 ++--
 docs/CHANGES                       | 47 ++++++++++++++++++++++++++++++++++----
 include/freetype/config/ftoption.h |  4 ++--
 include/freetype/freetype.h        | 32 ++++++++++++++------------
 include/freetype/ftcolor.h         |  3 ---
 src/base/ftbitmap.c                |  2 +-
 6 files changed, 64 insertions(+), 28 deletions(-)

diff --git a/devel/ftoption.h b/devel/ftoption.h
index 94e4cc8..16cf4e1 100644
--- 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
 
diff --git a/docs/CHANGES b/docs/CHANGES
index f9c5a1e..7f66eed 100644
--- 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).
diff --git a/include/freetype/config/ftoption.h 
b/include/freetype/config/ftoption.h
index d73a7f6..12f47a8 100644
--- 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
 
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 42cf0d8..e45b311 100644
--- 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:
    *   ```
diff --git a/include/freetype/ftcolor.h b/include/freetype/ftcolor.h
index ab9422c..cf18021 100644
--- 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.
    *
diff --git a/src/base/ftbitmap.c b/src/base/ftbitmap.c
index 3617beb..1bdcd9e 100644
--- 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 );