337 lines
10 KiB
C
337 lines
10 KiB
C
/****************************************************************************
|
|
*
|
|
* otsvg.h
|
|
*
|
|
* Interface for OT-SVG support related things (specification).
|
|
*
|
|
* Copyright (C) 2022-2023 by
|
|
* David Turner, Robert Wilhelm, Werner Lemberg, and Moazin Khatti.
|
|
*
|
|
* This file is part of the FreeType project, and may only be used,
|
|
* modified, and distributed under the terms of the FreeType project
|
|
* license, LICENSE.TXT. By continuing to use, modify, or distribute
|
|
* this file you indicate that you have read the license and
|
|
* understand and accept it fully.
|
|
*
|
|
*/
|
|
|
|
|
|
#ifndef OTSVG_H_
|
|
#define OTSVG_H_
|
|
|
|
#include <freetype/freetype.h>
|
|
|
|
#ifdef FREETYPE_H
|
|
#error "freetype.h of FreeType 1 has been loaded!"
|
|
#error "Please fix the directory search order for header files"
|
|
#error "so that freetype.h of FreeType 2 is found first."
|
|
#endif
|
|
|
|
|
|
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
|
|
*
|
|
* @description:
|
|
* 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
|
|
*/
|
|
typedef FT_Error
|
|
(*SVG_Lib_Init_Func)( FT_Pointer *data_pointer );
|
|
|
|
|
|
/**************************************************************************
|
|
*
|
|
* @functype:
|
|
* SVG_Lib_Free_Func
|
|
*
|
|
* @description:
|
|
* 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
|
|
*/
|
|
typedef void
|
|
(*SVG_Lib_Free_Func)( FT_Pointer *data_pointer );
|
|
|
|
|
|
/**************************************************************************
|
|
*
|
|
* @functype:
|
|
* SVG_Lib_Render_Func
|
|
*
|
|
* @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_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
|
|
*/
|
|
typedef FT_Error
|
|
(*SVG_Lib_Render_Func)( FT_GlyphSlot slot,
|
|
FT_Pointer *data_pointer );
|
|
|
|
|
|
/**************************************************************************
|
|
*
|
|
* @functype:
|
|
* SVG_Lib_Preset_Slot_Func
|
|
*
|
|
* @description:
|
|
* 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
|
|
*/
|
|
typedef FT_Error
|
|
(*SVG_Lib_Preset_Slot_Func)( FT_GlyphSlot slot,
|
|
FT_Bool cache,
|
|
FT_Pointer *state );
|
|
|
|
|
|
/**************************************************************************
|
|
*
|
|
* @struct:
|
|
* SVG_RendererHooks
|
|
*
|
|
* @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 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
|
|
*/
|
|
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;
|
|
|
|
|
|
/**************************************************************************
|
|
*
|
|
* @struct:
|
|
* FT_SVG_DocumentRec
|
|
*
|
|
* @description:
|
|
* 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
|
|
*/
|
|
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;
|
|
|
|
|
|
/**************************************************************************
|
|
*
|
|
* @type:
|
|
* FT_SVG_Document
|
|
*
|
|
* @description:
|
|
* A handle to an @FT_SVG_DocumentRec object.
|
|
*
|
|
* @since:
|
|
* 2.12
|
|
*/
|
|
typedef struct FT_SVG_DocumentRec_* FT_SVG_Document;
|
|
|
|
|
|
FT_END_HEADER
|
|
|
|
#endif /* OTSVG_H_ */
|
|
|
|
|
|
/* END */
|