Skip to content

FreeType » Docs » Format-Specific API » OpenType SVG Fonts

# OpenType SVG Fonts

## Synopsis

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 repository.

## SVG_Lib_Init_Func

Defined in FT_OTSVG_H (freetype/otsvg.h).

      typedef FT_Error
      (*SVG_Lib_Init_Func)( FT_Pointer  *data_pointer );

A callback that is called when the first OT-SVG glyph is rendered in the lifetime of an `FT_Library` object. In a typical implementation, one would want to allocate a structure and point the `data_pointer` to it and perform any library initializations that might be needed.

#### inout

data_pointer | The SVG rendering module stores a pointer variable that can be used by clients to store any data that needs to be shared across different hooks. `data_pointer` is essentially a pointer to that pointer such that it can be written to as well as read from.

#### return

FreeType error code. 0 means success.

#### since

2.12

## SVG_Lib_Free_Func

Defined in FT_OTSVG_H (freetype/otsvg.h).

      typedef void
      (*SVG_Lib_Free_Func)( FT_Pointer  *data_pointer );

A callback that is called when the `ot-svg` module is being freed. It is only called if the init hook was called earlier. This means that neither the init nor the free hook is called if no OT-SVG glyph is rendered.

In a typical implementation, one would want to free any state structure that was allocated in the init hook and perform any library-related closure that might be needed.

#### inout

data_pointer | The SVG rendering module stores a pointer variable that can be used by clients to store any data that needs to be shared across different hooks. `data_pointer` is essentially a pointer to that pointer such that it can be written to as well as read from.

#### since

2.12

## SVG_Lib_Render_Func

Defined in FT_OTSVG_H (freetype/otsvg.h).

      typedef FT_Error
      (*SVG_Lib_Render_Func)( FT_GlyphSlot  slot,
                              FT_Pointer   *data_pointer );

A callback that is called to render an OT-SVG glyph. This callback 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`.

The render hook is expected to render the SVG glyph to the bitmap buffer that is allocated already at `slot->bitmap.buffer`. It also sets the `num_grays` value as well as `slot->format`.

#### input

slot | The slot to render.

#### inout

data_pointer | The SVG rendering module stores a pointer variable that can be used by clients to store any data that needs to be shared across different hooks. `data_pointer` is essentially a pointer to that pointer such that it can be written to as well as read from.

#### return

FreeType error code. 0 means success.

#### since

2.12

## SVG_Lib_Preset_Slot_Func

Defined in FT_OTSVG_H (freetype/otsvg.h).

      typedef FT_Error
      (*SVG_Lib_Preset_Slot_Func)( FT_GlyphSlot  slot,
                                   FT_Bool       cache,
                                   FT_Pointer   *state );

A callback that is called to preset the glyph slot. It is called from 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 it is the latter, the argument `cache` is set to `TRUE`. This distinction has been made because many calculations that are necessary for presetting a glyph slot are the same needed later for the render callback hook. Thus, if `cache` is `TRUE`, the hook can cache those calculations in a memory block referenced by the state pointer.

This hook is expected to preset the slot by setting parameters such as `bitmap_left`, `bitmap_top`, `width`, `rows`, `pitch`, and `pixel_mode`. It is also expected to set all the metrics for the slot including the vertical advance if it is not already set. Typically, fonts have horizontal advances but not vertical ones. If those are available, they had already been set, otherwise they have to be estimated and set manually. The hook must take into account the transformations that have been set, and translate the transformation matrices into the SVG coordinate system, as the original matrix is intended for the TTF/CFF coordinate system.

#### input

slot | The glyph slot that has the SVG document loaded.
cache | See description.

#### inout

data_pointer | The SVG rendering module stores a pointer variable that can be used by clients to store any data that needs to be shared across different hooks. `data_pointer` is essentially a pointer to that pointer such that it can be written to as well as read from.

#### return

FreeType error code. 0 means success.

#### since

2.12

## SVG_RendererHooks

Defined in FT_OTSVG_H (freetype/otsvg.h).

      typedef struct SVG_RendererHooks_
      {
        SVG_Lib_Init_Func    init_svg;
        SVG_Lib_Free_Func    free_svg;
        SVG_Lib_Render_Func  render_svg;

        SVG_Lib_Preset_Slot_Func  preset_slot;

      } SVG_RendererHooks;

A structure that stores the four hooks needed to render OT-SVG glyphs 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 to do the same operations; therefore, it's better to cache the intermediate data in a state structure to avoid calculating it twice. 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.

All four hooks must be non-NULL.

#### fields

init_svg | The initialization hook.
free_svg | The cleanup hook.
render_hook | The render hook.
preset_slot | The preset hook.

#### since

2.12

## FT_SVG_DocumentRec

Defined in FT_OTSVG_H (freetype/otsvg.h).

      typedef struct  FT_SVG_DocumentRec_
      {
        FT_Byte*  svg_document;
        FT_ULong  svg_document_length;

        FT_Size_Metrics  metrics;
        FT_UShort        units_per_EM;

        FT_UShort  start_glyph_id;
        FT_UShort  end_glyph_id;

        FT_Matrix  transform;
        FT_Vector  delta;

      } FT_SVG_DocumentRec;

A structure that models one SVG document.

#### fields

svg_document | A pointer to the SVG document.
svg_document_length | The length of `svg_document`.
metrics | A metrics object storing the size information.
units_per_EM | The size of the EM square.
start_glyph_id | The first glyph ID in the glyph range covered by this document.
end_glyph_id | The last glyph ID in the glyph range covered by this document.
transform | A 2x2 transformation matrix to apply to the glyph while rendering it.
delta | The translation to apply to the glyph while rendering.

#### note

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

## FT_SVG_Document

Defined in FT_OTSVG_H (freetype/otsvg.h).

      typedef struct FT_SVG_DocumentRec_*  FT_SVG_Document;

    FT_END_HEADER

    #endif /* OTSVG_H_ */

    /* END */

A handle to an `FT_SVG_DocumentRec` object.

#### since

2.12