[ft-devel] controlling FreeType modules

[Werner LEMBERG]

Toshiya-san and I have met in Osaka, and we have enjoyed a great time
visiting the private museums of Motoya and Morizawa, two big font
companies in Japan.

While having a nice lunch, we've discussed how to control modules in
FreeType.  In FreeType's `autohinter-properties' branch, I've posted a
first draft of how an interface might look like.  However, this is far
from sufficient, and it is special to the auto-hinter only, while we
need a more generic solution to control any module.

So here is another proposal for an interface.


  Property service
  ----------------

  Properties get accessed with FreeType services.  For example, to
  make the module `foo' listen to property changes, add a
  `foo-properties' service to the module, with two functions to get
  and set values.


  Default properties
  ------------------

  Internally, we use an `FT_Property' structure to collect all
  properties in a linked list:

    typedef FT_Property_
    {
      FT_String*    module_name;
      FT_String*    property_name;
      void*         value;

      FT_Property*  next;

    } FT_Property;

  The list is located in the `FT_Library' object:

    FT_Property*  properties;

  Allocation and deallocation of `properties' is handled by FreeType.

  As soon as a new `FT_Face' object gets created, the corresponding
  modules check the `properties' list and use it for initialization.
  There might be properties which are not suitable for global
  initialization; such cases are to be ignored (with a debugging
  warning probably).

  Already existing `FT_Face' objects are not affected.

    FT_Error
    FT_Library_SetProperty( FT_Library        library,
                            const FT_String*  module_name,
                            const FT_String*  property_name,
                            void*             value );

    FT_Error
    FT_Library_RemoveProperty( FT_Library        library,
                               const FT_String*  module_name,
                               const FT_String*  property_name );

    FT_Error
    FT_Library_GetProperty( FT_Library        library,
                            const FT_String*  module_name,
                            const FT_String*  property_name,
                            void*             avalue );

  The generic pointer `value' gets typecast to a pointer of the real
  value variable or structure.  Maybe not the most convenient, it
  guarantees flexibility and extensibility, however.


  Local properties
  ----------------

  These are located in an FT_Face object.  Existing values for
  properties get overwritten.

    FT_Error
    FT_Face_SetProperty( FT_Face           face,
                         const FT_String*  module_name,
                         const FT_String*  property_name,
                         void*             value );

    FT_Error
    FT_Face_RemoveProperty( FT_Face           face,
                            const FT_String*  module_name,
                            const FT_String*  property_name );

    FT_Error
    FT_Face_GetProperty( FT_Face           face,
                         const FT_String*  module_name,
                         const FT_String*  property_name,
                         void*             avalue );


  Examples
  --------

    /***************************************************************/
    /* Set property `bar' in module `foo' to value 1.              */

    FT_UInt  bar;


    bar = 1;
    FT_Face_SetProperty( face, "foo", "bar", &bar );


    /***************************************************************/
    /* Get property `baz', which consists of a minimum and maximum */
    /* value.                                                      */

    typedef range_
    {
      FT_Int32  min;
      FT_Int32  max;

    } range;

    range baz;


    FT_Face_GetProperty( face, "foo", "baz", &baz );



      Werner