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

@@ -1,3 +1,15 @@
+2017-02-14  Nikolaus Waxweiler  <madigens@gmail.com>
+	    Werner Lemberg  <wl@gnu.org>
+
+	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  <wl@gnu.org>
 
 	[autofit] Prevent overlapping blue zones.

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>                                                            */

src/base/ftobjs.c

@@ -3589,6 +3589,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 )