[freetype2] master ca1486c 6/9: [cff] Introduce `random-seed' property (1/2).

[Werner LEMBERG]

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

    [cff] Introduce `random-seed' property (1/2).
    
    We need this for support of the `random' operator.
    
    * include/freetype/ftcffdrv.h (FT_PARAM_TAG_RANDOM_SEED): New macro.
    
    * include/freetype/internal/ftobjs.h (FT_Face_InternalRec): New
    field `random_seed'.
    
    * src/cff/cffobjs.h (CFF_DriverRec): New field `random_seed'.
---
 ChangeLog                          | 13 ++++++++++++
 include/freetype/freetype.h        | 21 +++++++++++++++----
 include/freetype/ftcffdrv.h        | 43 ++++++++++++++++++++++++++++++++++++++
 include/freetype/internal/ftobjs.h |  6 ++++++
 src/cff/cffobjs.h                  |  1 +
 5 files changed, 80 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f442167..9ec0b1f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2017-02-20  Werner Lemberg  <address@hidden>
+
+       [cff] Introduce `random-seed' property (1/2).
+
+       We need this for support of the `random' operator.
+
+       * include/freetype/ftcffdrv.h (FT_PARAM_TAG_RANDOM_SEED): New macro.
+
+       * include/freetype/internal/ftobjs.h (FT_Face_InternalRec): New
+       field `random_seed'.
+
+       * src/cff/cffobjs.h (CFF_DriverRec): New field `random_seed'.
+
 2017-02-17  Werner Lemberg  <address@hidden>
 
        Remove clang warnings.
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 814e605..d351a06 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -3631,11 +3631,16 @@ FT_BEGIN_HEADER
    *
    *   * Stem darkening (@FT_PARAM_TAG_STEM_DARKENING, corresponding to the
    *     property `no-stem-darkening' provided by the `autofit' and `cff'
-   *     modules; see @auto_hinter and @cff_driver).
+   *     modules; see @no-stem-darkening[autofit] and
+   *     @no-stem-darkening[cff]).
    *
    *   * LCD filter weights (@FT_PARAM_TAG_LCD_FILTER_WEIGHTS, corresponding
    *     to function @FT_Library_SetLcdFilterWeights).
    *
+   *   * Seed value for the CFF `random' operator
+   *     (@FT_PARAM_TAG_RANDOM_SEED, corresponding to the `random-seed'
+   *     property provided by the `cff' module; see @random-seed).
+   *
    *   Pass NULL as `data' in @FT_Parameter for a given tag to reset the
    *   option and use the library or module default again.
    *
@@ -3653,7 +3658,7 @@ FT_BEGIN_HEADER
    *   FreeType error code.  0~means success.
    *
    * @note:
-   *   Here an example that sets two properties.  You must define
+   *   Here an example that sets three properties.  You must define
    *   FT_CONFIG_OPTION_SUBPIXEL_RENDERING to make the LCD filter examples
    *   work.
    *
@@ -3665,7 +3670,12 @@ FT_BEGIN_HEADER
    *     FT_LcdFiveTapFilter  custom_weight =
    *                            { 0x10, 0x40, 0x70, 0x40, 0x10 };
    *
-   *     FT_Parameter         properties[2] = { property1, property2 };
+   *     FT_Parameter         property3;
+   *     FT_Int32             random_seed = 314159265;
+   *
+   *     FT_Parameter         properties[3] = { property1,
+   *                                            property2,
+   *                                            property3 };
    *
    *
    *     property1.tag  = FT_PARAM_TAG_STEM_DARKENING;
@@ -3674,7 +3684,10 @@ FT_BEGIN_HEADER
    *     property2.tag  = FT_PARAM_TAG_LCD_FILTER_WEIGHTS;
    *     property2.data = custom_weight;
    *
-   *     FT_Face_Properties( face, 2, properties );
+   *     property3.tag  = FT_PARAM_TAG_RANDOM_SEED;
+   *     property3.data = &random_seed;
+   *
+   *     FT_Face_Properties( face, 3, properties );
    *   }
    *
    *   The next example resets a single property to its default value.
diff --git a/include/freetype/ftcffdrv.h b/include/freetype/ftcffdrv.h
index a473389..c55b591 100644
--- a/include/freetype/ftcffdrv.h
+++ b/include/freetype/ftcffdrv.h
@@ -113,6 +113,7 @@ FT_BEGIN_HEADER
    *   hinting-engine[cff]
    *   no-stem-darkening[cff]
    *   darkening-parameters[cff]
+   *   random-seed
    *
    */
 
@@ -265,6 +266,48 @@ FT_BEGIN_HEADER
    *   }
    */
 
+
+  /**************************************************************************
+   *
+   * @property:
+   *   random-seed
+   *
+   * @description:
+   *   By default, the seed value for the CFF `random' operator is set to a
+   *   random value.  However, mainly for debugging purposes, it is often
+   *   necessary to use a known value as a seed so that the pseudo-random
+   *   number sequences generated by `random' are repeatable.
+   *
+   *   The `random-seed' property does that.  Its argument is a signed 32bit
+   *   integer; if the value is zero or negative, the seed given by the
+   *   `intitialRandomSeed' private DICT operator in a CFF file gets used
+   *   (or a default value if there is no such operator).  If the value is
+   *   positive, use it instead of `initialRandomSeed', which is
+   *   consequently ignored.
+   *
+   * @note:
+   *   This property can be set via the `FREETYPE_PROPERTIES' environment
+   *   variable.  It can also be set per face using @FT_Face_Properties with
+   *   @FT_PARAM_TAG_RANDOM_SEED.
+   *
+   */
+
+
+  /*
+   * @constant:
+   *   FT_PARAM_TAG_RANDOM_SEED
+   *
+   * @description:
+   *   An @FT_Parameter tag to be used with @FT_Face_Properties.  The
+   *   corresponding 32bit signed integer argument overrides the CFF
+   *   module's random seed value with a face-specific one; see
+   *   @random-seed.
+   *
+   */
+#define FT_PARAM_TAG_RANDOM_SEED \
+          FT_MAKE_TAG( 's', 'e', 'e', 'd' )
+
+
   /* */
 
 
diff --git a/include/freetype/internal/ftobjs.h 
b/include/freetype/internal/ftobjs.h
index 16385fa..2f18d07 100644
--- a/include/freetype/internal/ftobjs.h
+++ b/include/freetype/internal/ftobjs.h
@@ -347,6 +347,11 @@ FT_BEGIN_HEADER
   /*      for example.  FALSE and TRUE toggle stem darkening on and off,   */
   /*      respectively, value~-1 means to use the module/driver default.   */
   /*                                                                       */
+  /*    random_seed ::                                                     */
+  /*      If positive, override the seed value for the CFF `random'        */
+  /*      operator.  Value~0 means to use the font's value.  Value~-1      */
+  /*      means to use the CFF driver's default.                           */
+  /*                                                                       */
   /*    lcd_weights ::                                                     */
   /*      Overrides the library default with custom weights for the 5-tap  */
   /*      FIR filter.  `{0, 0, 0, 0, 0}' means to use the library default. */
@@ -370,6 +375,7 @@ FT_BEGIN_HEADER
 #endif
 
     FT_Char              no_stem_darkening;
+    FT_Int32             random_seed;
 #ifdef FT_CONFIG_OPTION_SUBPIXEL_RENDERING
     FT_LcdFiveTapFilter  lcd_weights;  /* preset or custom filter weights */
 #endif
diff --git a/src/cff/cffobjs.h b/src/cff/cffobjs.h
index 2b88e0e..1dba694 100644
--- a/src/cff/cffobjs.h
+++ b/src/cff/cffobjs.h
@@ -121,6 +121,7 @@ FT_BEGIN_HEADER
     FT_UInt   hinting_engine;
     FT_Bool   no_stem_darkening;
     FT_Int    darken_params[8];
+    FT_Int32  random_seed;
 
   } CFF_DriverRec;