More documentation on handling OT-SVG.
diff --git a/docs/CHANGES b/docs/CHANGES
index 3c6cb59..32a6465 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 4f32cc8..6a9733a 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 69ff90b..0dc91e8 100644
--- a/include/freetype/ftdriver.h
+++ b/include/freetype/ftdriver.h
@@ -212,16 +212,14 @@
* @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.
+ * and @FT_Property_Get.
*
- * The TrueType driver's module name is 'truetype'.
+ * The TrueType driver's module name is 'truetype'; a single property
+ * @interpreter-version is available, as documented in the @properties
+ * section.
*
- * 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 @@
/**************************************************************************
*
* @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 @@
/**************************************************************************
*
* @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 8748249..2b3c00f 100644
--- a/include/freetype/otsvg.h
+++ b/include/freetype/otsvg.h
@@ -33,6 +33,29 @@
/**************************************************************************
*
+ * @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 @@
* 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 @@
* 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 @@
*
* @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 @@
* 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 @@
* 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 @@
* 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 @@
*
* @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 @@
* 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 @@
/**************************************************************************
*
* @struct:
- * FT_SVG_DocumentRec_
+ * FT_SVG_DocumentRec
*
* @description:
* A structure that models one SVG document.
@@ -276,12 +285,12 @@
* 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
