From 21d0fa374200aecc6605daf034a47167ea82ed6f Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Sun, 23 Jan 2022 12:03:44 +0100 Subject: [PATCH] More documentation on handling OT-SVG. --- docs/CHANGES | 17 ++++++++ include/freetype/ftchapters.h | 2 + include/freetype/ftdriver.h | 73 +++++++++++++++++++++++++++++++---- include/freetype/otsvg.h | 59 ++++++++++++++++------------ 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. + * 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_ * @@ -300,6 +298,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: @@ -798,6 +821,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: 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 @@ -31,6 +31,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: @@ -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