[freetype2] master 64cdee7 1/9: Add new function `FT_Face_Properties'.

[Werner LEMBERG]

branch: master
commit 64cdee73480587352fb45402b771077be05c1715
Author: Nikolaus Waxweiler <address@hidden>
Commit: Werner Lemberg <address@hidden>

    Add new function `FT_Face_Properties'.
    
    This commit provides the framework, to be filled with something
    useful in the next commits.
    
    * include/freetype/freetype.h (FT_Face_Properties): Declare.
    
    * src/base/ftobjs.c (FT_Face_Properties): New function.
---
 ChangeLog                   | 12 ++++++++++++
 include/freetype/freetype.h | 39 ++++++++++++++++++++++++++++++++++++++-
 src/base/ftobjs.c           | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index 5fa1201..9008b6b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2017-02-14  Nikolaus Waxweiler  <address@hidden>
+           Werner Lemberg  <address@hidden>
+
+       Add new function `FT_Face_Properties'.
+
+       This commit provides the framework, to be filled with something
+       useful in the next commits.
+
+       * include/freetype/freetype.h (FT_Face_Properties): Declare.
+
+       * src/base/ftobjs.c (FT_Face_Properties): New function.
+
 2017-02-13  Werner Lemberg  <address@hidden>
 
        [autofit] Prevent overlapping blue zones.
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 568a588..fd7d445 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -175,6 +175,7 @@ FT_BEGIN_HEADER
   /*    FT_Done_Face                                                       */
   /*    FT_Reference_Face                                                  */
   /*    FT_New_Memory_Face                                                 */
+  /*    FT_Face_Properties                                                 */
   /*    FT_Open_Face                                                       */
   /*    FT_Open_Args                                                       */
   /*    FT_Parameter                                                       */
@@ -1925,7 +1926,7 @@ FT_BEGIN_HEADER
   /*                                                                       */
   /* <Description>                                                         */
   /*    A simple structure to pass more or less generic parameters to      */
-  /*    @FT_Open_Face.                                                     */
+  /*    @FT_Open_Face and @FT_Face_Properties.                             */
   /*                                                                       */
   /* <Fields>                                                              */
   /*    tag  :: A four-byte identification tag.                            */
@@ -3612,6 +3613,42 @@ FT_BEGIN_HEADER
                     FT_UInt   *agindex );
 
 
+  /*************************************************************************
+   *
+   * @function:
+   *   FT_Face_Properties
+   *
+   * @description:
+   *   Set or override certain (library or module-wide) properties on a
+   *   face-by-face basis.  Useful for finer-grained control and avoiding
+   *   locks on shared structures (threads can modify their own faces as
+   *   they see fit).
+   *
+   *   Contrary to @FT_Property_Set, this function uses @FT_Parameter so
+   *   that you can pass multiple properties to the target face in one call.
+   *   Note that only a subset of the available properties can be
+   *   controlled.
+   *
+   * @input:
+   *   face ::
+   *     A handle to the source face object.
+   *
+   *   num_properties ::
+   *     The number of properties that follow.
+   *
+   *   properties ::
+   *     A handle to an @FT_Parameter array with `num_properties' elements.
+   *
+   * @return:
+   *   FreeType error code.  0~means success.
+   *
+   */
+  FT_EXPORT( FT_Error )
+  FT_Face_Properties( FT_Face        face,
+                      FT_UInt        num_properties,
+                      FT_Parameter*  properties );
+
+
   /*************************************************************************/
   /*                                                                       */
   /* <Function>                                                            */
diff --git a/src/base/ftobjs.c b/src/base/ftobjs.c
index 59d65e2..c2ab2d1 100644
--- a/src/base/ftobjs.c
+++ b/src/base/ftobjs.c
@@ -3591,6 +3591,38 @@
 
   /* documentation is in freetype.h */
 
+  FT_EXPORT_DEF( FT_Error )
+  FT_Face_Properties( FT_Face        face,
+                      FT_UInt        num_properties,
+                      FT_Parameter*  properties )
+  {
+    FT_Error  error = FT_Err_Ok;
+
+
+    if ( num_properties > 0 && !properties )
+    {
+      error = FT_THROW( Invalid_Argument );
+      goto Exit;
+    }
+
+    for ( ; num_properties > 0; num_properties-- )
+    {
+      error = FT_THROW( Invalid_Argument );
+      goto Exit;
+
+      if ( error )
+        break;
+
+      properties++;
+    }
+
+  Exit:
+    return error;
+  }
+
+
+  /* documentation is in freetype.h */
+
   FT_EXPORT_DEF( FT_UInt )
   FT_Face_GetCharVariantIndex( FT_Face   face,
                                FT_ULong  charcode,