More documentation on handling OT-SVG.

4 files changed, 118 insertions, 33 deletions

diff --git a/docs/CHANGES b/docs/CHANGES
index 3c6cb594c..32a6465b7 100644
--- a/docs/CHANGES
+++ b/docs/CHANGES
@@ -1,3 +1,20 @@
+CHANGES BETWEEN 2.11.1 and 2.12.0
+
+  I. IMPORTANT CHANGES
+
+  - FreeType  now   handles  OT-SVG  fonts,  to   be  controlled  with
+    `FT_CONFIG_OPTION_SVG`  configuration macro.   By default,  it can
+    only load the 'SVG ' table of an OpenType font.  However, by using
+    the `svg-hooks` property of the new 'ot-svg' module it is possible
+    to register an  external SVG rendering engine.   The FreeType demo
+    programs  have been  set  up  to use  'librsvg'  as the  rendering
+    library.
+
+    This work was Moazin Kathri's GSoC 2019 project.
+
+
+======================================================================
+
 CHANGES BETWEEN 2.11.0 and 2.11.1
 
   I. IMPORTANT CHANGES
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index 4f32cc88c..6a9733ad7 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -62,6 +62,7 @@
    *   cid_fonts
    *   pfr_fonts
    *   winfnt_fonts
+   *   svg_fonts
    *   font_formats
    *   gasp_table
    *
@@ -82,6 +83,7 @@
    *   t1_cid_driver
    *   tt_driver
    *   pcf_driver
+   *   ot_svg_driver
    *   properties
    *   parameter_tags
    *   lcd_rendering
diff --git a/include/freetype/ftdriver.h b/include/freetype/ftdriver.h
index 69ff90bf6..0dc91e8b4 100644
--- a/include/freetype/ftdriver.h
+++ b/include/freetype/ftdriver.h
@@ -212,16 +212,14 @@ FT_BEGIN_HEADER
    * @description:
    *   While FreeType's TrueType driver doesn't expose API functions by
    *   itself, it is possible to control its behaviour with @FT_Property_Set
-   *   and @FT_Property_Get.  The following lists the available properties
-   *   together with the necessary macros and structures.
-   *
-   *   The TrueType driver's module name is 'truetype'.
+   *   and @FT_Property_Get.
    *
-   *   A single property @interpreter-version is available, as documented in
-   *   the @properties section.
+   *   The TrueType driver's module name is 'truetype'; a single property
+   *   @interpreter-version is available, as documented in the @properties
+   *   section.
    *
-   *   We start with a list of definitions, kindly provided by Greg
-   *   Hitchcock.
+   *   To help understand the differences between interpreter versions, we
+   *   introduce a list of definitions, kindly provided by Greg Hitchcock.
    *
    *   _Bi-Level Rendering_
    *
@@ -303,6 +301,31 @@ FT_BEGIN_HEADER
   /**************************************************************************
    *
    * @section:
+   *   ot_svg_driver
+   *
+   * @title:
+   *   The SVG driver
+   *
+   * @abstract:
+   *   Controlling the external rendering of OT-SVG glyphs.
+   *
+   * @description:
+   *   By default, FreeType can only load the 'SVG~' table of OpenType fonts
+   *   if configuration macro `FT_CONFIG_OPTION_SVG` is defined.  To make it
+   *   render SVG glyphs, an external SVG rendering library is needed.  All
+   *   details on the interface between FreeType and the external library
+   *   via function hooks can be found in section @svg_fonts.
+   *
+   *   The OT-SVG driver's module name is 'ot-svg'; it supports a single
+   *   property called @svg-hooks, documented below in the @properties
+   *   section.
+   *
+   */
+
+
+  /**************************************************************************
+   *
+   * @section:
    *   properties
    *
    * @title:
@@ -801,6 +824,40 @@ FT_BEGIN_HEADER
   /**************************************************************************
    *
    * @property:
+   *   svg-hooks
+   *
+   * @description:
+   *   Set up the interface between FreeType and an extern SVG rendering
+   *   library like 'librsvg'.  All details on the function hooks can be
+   *   found in section @svg_fonts.
+   *
+   * @example:
+   *   The following example code expects that the four hook functions
+   *   `svg_*` are defined elsewhere.  Error handling is omitted, too.
+   *
+   *   ```
+   *     FT_Library  library;
+   *     SVG_RendererHooks  hooks = {
+   *                          (SVG_Lib_Init_Func)svg_init,
+   *                          (SVG_Lib_Free_Func)svg_free,
+   *                          (SVG_Lib_Render_Func)svg_render,
+   *                          (SVG_Lib_Preset_Slot_Func)svg_preset_slot };
+   *
+   *
+   *     FT_Init_FreeType( &library );
+   *
+   *     FT_Property_Set( library, "ot-svg",
+   *                               "svg-hooks", &hooks );
+   *   ```
+   *
+   * @since:
+   *   2.12
+   */
+
+
+  /**************************************************************************
+   *
+   * @property:
    *   glyph-to-script-map
    *
    * @description:
diff --git a/include/freetype/otsvg.h b/include/freetype/otsvg.h
index 87482491c..2b3c00f29 100644
--- a/include/freetype/otsvg.h
+++ b/include/freetype/otsvg.h
@@ -33,6 +33,29 @@ FT_BEGIN_HEADER
 
   /**************************************************************************
    *
+   * @section:
+   *   svg_fonts
+   *
+   * @title:
+   *   OpenType SVG Fonts
+   *
+   * @abstract:
+   *   OT-SVG API between FreeType and an external SVG rendering library.
+   *
+   * @description:
+   *   This section describes the four hooks necessary to render SVG
+   *   'documents' that are contained in an OpenType font's 'SVG~' table.
+   *
+   *   For more information on the implementation, see our standard hooks
+   *   based on 'librsvg' in the [FreeType Demo
+   *   Programs](https://gitlab.freedesktop.org/freetype/freetype-demos)
+   *   repository.
+   *
+   */
+
+
+  /**************************************************************************
+   *
    * @functype:
    *   SVG_Lib_Init_Func
    *
@@ -42,9 +65,6 @@ FT_BEGIN_HEADER
    *   one would want to allocate a structure and point the `data_pointer`
    *   to it and perform any library initializations that might be needed.
    *
-   *   For more information on the implementation, see our standard hooks
-   *   based on Librsvg in the 'FreeType Demo Programs' repository.
-   *
    * @inout:
    *   data_pointer ::
    *     The SVG rendering module stores a pointer variable that can be used
@@ -77,9 +97,6 @@ FT_BEGIN_HEADER
    *   structure that was allocated in the init hook and perform any
    *   library-related closure that might be needed.
    *
-   *   For more information on the implementation, see our standard hooks
-   *   based on Librsvg in the 'FreeType Demo Programs' repository.
-   *
    * @inout:
    *   data_pointer ::
    *     The SVG rendering module stores a pointer variable that can be used
@@ -101,7 +118,7 @@ FT_BEGIN_HEADER
    *
    * @description:
    *   A callback that is called to render an OT-SVG glyph.  This callback
-   *   hook is called right after the preset hook @SVG_Lib_Preset_SlotFunc
+   *   hook is called right after the preset hook @SVG_Lib_Preset_Slot_Func
    *   has been called with `cache` set to `TRUE`.  The data necessary to
    *   render is available through the handle @FT_SVG_Document, which is set
    *   in the `other` field of @FT_GlyphSlotRec.
@@ -110,9 +127,6 @@ FT_BEGIN_HEADER
    *   buffer that is allocated already at `slot->bitmap.buffer`.  It also
    *   sets the `num_grays` value as well as `slot->format`.
    *
-   *   For more information on the implementation, see our standard hooks
-   *   based on Librsvg in the 'FreeType Demo Programs' repository.
-   *
    * @input:
    *   slot ::
    *     The slot to render.
@@ -145,6 +159,7 @@ FT_BEGIN_HEADER
    *   two places.
    *
    *   1. When `FT_Load_Glyph` needs to preset the glyph slot.
+   *
    *   2. Right before the `svg` module calls the render callback hook.
    *
    *   When it is the former, the argument `cache` is set to `FALSE`.  When
@@ -165,9 +180,6 @@ FT_BEGIN_HEADER
    *   matrices into the SVG coordinate system, as the original matrix is
    *   intended for the TTF/CFF coordinate system.
    *
-   *   For more information on the implementation, see our standard hooks
-   *   based on Librsvg in the 'FreeType Demo Programs' repository.
-   *
    * @input:
    *   slot ::
    *     The glyph slot that has the SVG document loaded.
@@ -201,8 +213,8 @@ FT_BEGIN_HEADER
    *
    * @description:
    *   A structure that stores the four hooks needed to render OT-SVG glyphs
-   *   properly.  The structure is publicly used to set the hooks via driver
-   *   properties.
+   *   properly.  The structure is publicly used to set the hooks via the
+   *   @svg-hooks driver property.
    *
    *   The behavior of each hook is described in its documentation.  One
    *   thing to note is that the preset hook and the render hook often need
@@ -211,9 +223,6 @@ FT_BEGIN_HEADER
    *   For example, in the preset hook one can draw the glyph on a recorder
    *   surface and later create a bitmap surface from it in the render hook.
    *
-   *   For more information on the implementation, see our standard hooks
-   *   based on Librsvg in the 'FreeType Demo Programs' repository.
-   *
    * @fields:
    *   init_svg ::
    *     The initialization hook.
@@ -244,7 +253,7 @@ FT_BEGIN_HEADER
   /**************************************************************************
    *
    * @struct:
-   *   FT_SVG_DocumentRec_
+   *   FT_SVG_DocumentRec
    *
    * @description:
    *   A structure that models one SVG document.
@@ -276,12 +285,12 @@ FT_BEGIN_HEADER
    *     The translation to apply to the glyph while rendering.
    *
    * @note:
-   *   When the slot is passed down to a renderer, the renderer can only
-   *   access the `metrics` and `units_per_EM` fields via `slot->face`.
-   *   However, when `FT_Glyph_To_Bitmap` sets up a dummy object, it has no
-   *   way to set a `face` object.  Thus, metrics information and
-   *   `units_per_EM` (which is necessary for OT-SVG) has to be stored
-   *   separately.
+   *   When an @FT_GlyphSlot object `slot` is passed down to a renderer, the
+   *   renderer can only access the `metrics` and `units_per_EM` fields via
+   *   `slot->face`.  However, when @FT_Glyph_To_Bitmap sets up a dummy
+   *   object, it has no way to set a `face` object.  Thus, metrics
+   *   information and `units_per_EM` (which is necessary for OT-SVG) has to
+   *   be stored separately.
    *
    * @since:
    *   2.12