More documentation on handling OT-SVG.

This commit is contained in:
Werner Lemberg 2022-01-23 12:03:44 +01:00
parent 9c1538525b
commit 21d0fa3742
4 changed files with 118 additions and 33 deletions

View File

@ -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 CHANGES BETWEEN 2.11.0 and 2.11.1
I. IMPORTANT CHANGES I. IMPORTANT CHANGES

View File

@ -62,6 +62,7 @@
* cid_fonts * cid_fonts
* pfr_fonts * pfr_fonts
* winfnt_fonts * winfnt_fonts
* svg_fonts
* font_formats * font_formats
* gasp_table * gasp_table
* *
@ -82,6 +83,7 @@
* t1_cid_driver * t1_cid_driver
* tt_driver * tt_driver
* pcf_driver * pcf_driver
* ot_svg_driver
* properties * properties
* parameter_tags * parameter_tags
* lcd_rendering * lcd_rendering

View File

@ -212,16 +212,14 @@ FT_BEGIN_HEADER
* @description: * @description:
* While FreeType's TrueType driver doesn't expose API functions by * While FreeType's TrueType driver doesn't expose API functions by
* itself, it is possible to control its behaviour with @FT_Property_Set * itself, it is possible to control its behaviour with @FT_Property_Set
* and @FT_Property_Get. The following lists the available properties * and @FT_Property_Get.
* together with the necessary macros and structures.
* *
* 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 * To help understand the differences between interpreter versions, we
* the @properties section. * introduce a list of definitions, kindly provided by Greg Hitchcock.
*
* We start with a list of definitions, kindly provided by Greg
* Hitchcock.
* *
* _Bi-Level Rendering_ * _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: * @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: * @property:

View File

@ -31,6 +31,29 @@
FT_BEGIN_HEADER 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: * @functype:
@ -42,9 +65,6 @@ FT_BEGIN_HEADER
* one would want to allocate a structure and point the `data_pointer` * one would want to allocate a structure and point the `data_pointer`
* to it and perform any library initializations that might be needed. * 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: * @inout:
* data_pointer :: * data_pointer ::
* The SVG rendering module stores a pointer variable that can be used * 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 * structure that was allocated in the init hook and perform any
* library-related closure that might be needed. * 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: * @inout:
* data_pointer :: * data_pointer ::
* The SVG rendering module stores a pointer variable that can be used * The SVG rendering module stores a pointer variable that can be used
@ -101,7 +118,7 @@ FT_BEGIN_HEADER
* *
* @description: * @description:
* A callback that is called to render an OT-SVG glyph. This callback * 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 * has been called with `cache` set to `TRUE`. The data necessary to
* render is available through the handle @FT_SVG_Document, which is set * render is available through the handle @FT_SVG_Document, which is set
* in the `other` field of @FT_GlyphSlotRec. * 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 * buffer that is allocated already at `slot->bitmap.buffer`. It also
* sets the `num_grays` value as well as `slot->format`. * 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: * @input:
* slot :: * slot ::
* The slot to render. * The slot to render.
@ -145,6 +159,7 @@ FT_BEGIN_HEADER
* two places. * two places.
* *
* 1. When `FT_Load_Glyph` needs to preset the glyph slot. * 1. When `FT_Load_Glyph` needs to preset the glyph slot.
*
* 2. Right before the `svg` module calls the render callback hook. * 2. Right before the `svg` module calls the render callback hook.
* *
* When it is the former, the argument `cache` is set to `FALSE`. When * 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 * matrices into the SVG coordinate system, as the original matrix is
* intended for the TTF/CFF coordinate system. * 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: * @input:
* slot :: * slot ::
* The glyph slot that has the SVG document loaded. * The glyph slot that has the SVG document loaded.
@ -201,8 +213,8 @@ FT_BEGIN_HEADER
* *
* @description: * @description:
* A structure that stores the four hooks needed to render OT-SVG glyphs * 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 * properly. The structure is publicly used to set the hooks via the
* properties. * @svg-hooks driver property.
* *
* The behavior of each hook is described in its documentation. One * 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 * 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 * 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. * 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: * @fields:
* init_svg :: * init_svg ::
* The initialization hook. * The initialization hook.
@ -244,7 +253,7 @@ FT_BEGIN_HEADER
/************************************************************************** /**************************************************************************
* *
* @struct: * @struct:
* FT_SVG_DocumentRec_ * FT_SVG_DocumentRec
* *
* @description: * @description:
* A structure that models one SVG document. * A structure that models one SVG document.
@ -276,12 +285,12 @@ FT_BEGIN_HEADER
* The translation to apply to the glyph while rendering. * The translation to apply to the glyph while rendering.
* *
* @note: * @note:
* When the slot is passed down to a renderer, the renderer can only * When an @FT_GlyphSlot object `slot` is passed down to a renderer, the
* access the `metrics` and `units_per_EM` fields via `slot->face`. * renderer can only access the `metrics` and `units_per_EM` fields via
* However, when `FT_Glyph_To_Bitmap` sets up a dummy object, it has no * `slot->face`. However, when @FT_Glyph_To_Bitmap sets up a dummy
* way to set a `face` object. Thus, metrics information and * object, it has no way to set a `face` object. Thus, metrics
* `units_per_EM` (which is necessary for OT-SVG) has to be stored * information and `units_per_EM` (which is necessary for OT-SVG) has to
* separately. * be stored separately.
* *
* @since: * @since:
* 2.12 * 2.12