freetype2/freetype/otsvg.h

0001 /****************************************************************************
0002  *
0003  * otsvg.h
0004  *
0005  *   Interface for OT-SVG support related things (specification).
0006  *
0007  * Copyright (C) 2022-2023 by
0008  * David Turner, Robert Wilhelm, Werner Lemberg, and Moazin Khatti.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef OTSVG_H_
0020 #define OTSVG_H_
0021
0022 #include <freetype/freetype.h>
0023
0024 #ifdef FREETYPE_H
0025 #error "freetype.h of FreeType 1 has been loaded!"
0026 #error "Please fix the directory search order for header files"
0027 #error "so that freetype.h of FreeType 2 is found first."
0028 #endif
0029
0030
0031 FT_BEGIN_HEADER
0032
0033
0034   /**************************************************************************
0035    *
0036    * @section:
0037    *   svg_fonts
0038    *
0039    * @title:
0040    *   OpenType SVG Fonts
0041    *
0042    * @abstract:
0043    *   OT-SVG API between FreeType and an external SVG rendering library.
0044    *
0045    * @description:
0046    *   This section describes the four hooks necessary to render SVG
0047    *   'documents' that are contained in an OpenType font's 'SVG~' table.
0048    *
0049    *   For more information on the implementation, see our standard hooks
0050    *   based on 'librsvg' in the [FreeType Demo
0051    *   Programs](https://gitlab.freedesktop.org/freetype/freetype-demos)
0052    *   repository.
0053    *
0054    */
0055
0056
0057   /**************************************************************************
0058    *
0059    * @functype:
0060    *   SVG_Lib_Init_Func
0061    *
0062    * @description:
0063    *   A callback that is called when the first OT-SVG glyph is rendered in
0064    *   the lifetime of an @FT_Library object.  In a typical implementation,
0065    *   one would want to allocate a structure and point the `data_pointer`
0066    *   to it and perform any library initializations that might be needed.
0067    *
0068    * @inout:
0069    *   data_pointer ::
0070    *     The SVG rendering module stores a pointer variable that can be used
0071    *     by clients to store any data that needs to be shared across
0072    *     different hooks.  `data_pointer` is essentially a pointer to that
0073    *     pointer such that it can be written to as well as read from.
0074    *
0075    * @return:
0076    *   FreeType error code.  0 means success.
0077    *
0078    * @since:
0079    *   2.12
0080    */
0081   typedef FT_Error
0082   (*SVG_Lib_Init_Func)( FT_Pointer  *data_pointer );
0083
0084
0085   /**************************************************************************
0086    *
0087    * @functype:
0088    *   SVG_Lib_Free_Func
0089    *
0090    * @description:
0091    *   A callback that is called when the `ot-svg` module is being freed.
0092    *   It is only called if the init hook was called earlier.  This means
0093    *   that neither the init nor the free hook is called if no OT-SVG glyph
0094    *   is rendered.
0095    *
0096    *   In a typical implementation, one would want to free any state
0097    *   structure that was allocated in the init hook and perform any
0098    *   library-related closure that might be needed.
0099    *
0100    * @inout:
0101    *   data_pointer ::
0102    *     The SVG rendering module stores a pointer variable that can be used
0103    *     by clients to store any data that needs to be shared across
0104    *     different hooks.  `data_pointer` is essentially a pointer to that
0105    *     pointer such that it can be written to as well as read from.
0106    *
0107    * @since:
0108    *   2.12
0109    */
0110   typedef void
0111   (*SVG_Lib_Free_Func)( FT_Pointer  *data_pointer );
0112
0113
0114   /**************************************************************************
0115    *
0116    * @functype:
0117    *   SVG_Lib_Render_Func
0118    *
0119    * @description:
0120    *   A callback that is called to render an OT-SVG glyph.  This callback
0121    *   hook is called right after the preset hook @SVG_Lib_Preset_Slot_Func
0122    *   has been called with `cache` set to `TRUE`.  The data necessary to
0123    *   render is available through the handle @FT_SVG_Document, which is set
0124    *   in the `other` field of @FT_GlyphSlotRec.
0125    *
0126    *   The render hook is expected to render the SVG glyph to the bitmap
0127    *   buffer that is allocated already at `slot->bitmap.buffer`.  It also
0128    *   sets the `num_grays` value as well as `slot->format`.
0129    *
0130    * @input:
0131    *   slot ::
0132    *     The slot to render.
0133    *
0134    * @inout:
0135    *   data_pointer ::
0136    *     The SVG rendering module stores a pointer variable that can be used
0137    *     by clients to store any data that needs to be shared across
0138    *     different hooks.  `data_pointer` is essentially a pointer to that
0139    *     pointer such that it can be written to as well as read from.
0140    *
0141    * @return:
0142    *   FreeType error code.  0 means success.
0143    *
0144    * @since:
0145    *   2.12
0146    */
0147   typedef FT_Error
0148   (*SVG_Lib_Render_Func)( FT_GlyphSlot  slot,
0149                           FT_Pointer   *data_pointer );
0150
0151
0152   /**************************************************************************
0153    *
0154    * @functype:
0155    *   SVG_Lib_Preset_Slot_Func
0156    *
0157    * @description:
0158    *   A callback that is called to preset the glyph slot.  It is called from
0159    *   two places.
0160    *
0161    *   1. When `FT_Load_Glyph` needs to preset the glyph slot.
0162    *
0163    *   2. Right before the `svg` module calls the render callback hook.
0164    *
0165    *   When it is the former, the argument `cache` is set to `FALSE`.  When
0166    *   it is the latter, the argument `cache` is set to `TRUE`.  This
0167    *   distinction has been made because many calculations that are necessary
0168    *   for presetting a glyph slot are the same needed later for the render
0169    *   callback hook.  Thus, if `cache` is `TRUE`, the hook can _cache_ those
0170    *   calculations in a memory block referenced by the state pointer.
0171    *
0172    *   This hook is expected to preset the slot by setting parameters such as
0173    *   `bitmap_left`, `bitmap_top`, `width`, `rows`, `pitch`, and
0174    *   `pixel_mode`.  It is also expected to set all the metrics for the slot
0175    *   including the vertical advance if it is not already set.  Typically,
0176    *   fonts have horizontal advances but not vertical ones.  If those are
0177    *   available, they had already been set, otherwise they have to be
0178    *   estimated and set manually.  The hook must take into account the
0179    *   transformations that have been set, and translate the transformation
0180    *   matrices into the SVG coordinate system, as the original matrix is
0181    *   intended for the TTF/CFF coordinate system.
0182    *
0183    * @input:
0184    *   slot ::
0185    *     The glyph slot that has the SVG document loaded.
0186    *
0187    *   cache ::
0188    *     See description.
0189    *
0190    * @inout:
0191    *   data_pointer ::
0192    *     The SVG rendering module stores a pointer variable that can be used
0193    *     by clients to store any data that needs to be shared across
0194    *     different hooks.  `data_pointer` is essentially a pointer to that
0195    *     pointer such that it can be written to as well as read from.
0196    *
0197    * @return:
0198    *   FreeType error code.  0 means success.
0199    *
0200    * @since:
0201    *   2.12
0202    */
0203   typedef FT_Error
0204   (*SVG_Lib_Preset_Slot_Func)( FT_GlyphSlot  slot,
0205                                FT_Bool       cache,
0206                                FT_Pointer   *state );
0207
0208
0209   /**************************************************************************
0210    *
0211    * @struct:
0212    *   SVG_RendererHooks
0213    *
0214    * @description:
0215    *   A structure that stores the four hooks needed to render OT-SVG glyphs
0216    *   properly.  The structure is publicly used to set the hooks via the
0217    *   @svg-hooks driver property.
0218    *
0219    *   The behavior of each hook is described in its documentation.  One
0220    *   thing to note is that the preset hook and the render hook often need
0221    *   to do the same operations; therefore, it's better to cache the
0222    *   intermediate data in a state structure to avoid calculating it twice.
0223    *   For example, in the preset hook one can draw the glyph on a recorder
0224    *   surface and later create a bitmap surface from it in the render hook.
0225    *
0226    *   All four hooks must be non-NULL.
0227    *
0228    * @fields:
0229    *   init_svg ::
0230    *     The initialization hook.
0231    *
0232    *   free_svg ::
0233    *     The cleanup hook.
0234    *
0235    *   render_hook ::
0236    *     The render hook.
0237    *
0238    *   preset_slot ::
0239    *     The preset hook.
0240    *
0241    * @since:
0242    *   2.12
0243    */
0244   typedef struct SVG_RendererHooks_
0245   {
0246     SVG_Lib_Init_Func    init_svg;
0247     SVG_Lib_Free_Func    free_svg;
0248     SVG_Lib_Render_Func  render_svg;
0249
0250     SVG_Lib_Preset_Slot_Func  preset_slot;
0251
0252   } SVG_RendererHooks;
0253
0254
0255   /**************************************************************************
0256    *
0257    * @struct:
0258    *   FT_SVG_DocumentRec
0259    *
0260    * @description:
0261    *   A structure that models one SVG document.
0262    *
0263    * @fields:
0264    *   svg_document ::
0265    *     A pointer to the SVG document.
0266    *
0267    *   svg_document_length ::
0268    *     The length of `svg_document`.
0269    *
0270    *   metrics ::
0271    *     A metrics object storing the size information.
0272    *
0273    *   units_per_EM ::
0274    *     The size of the EM square.
0275    *
0276    *   start_glyph_id ::
0277    *     The first glyph ID in the glyph range covered by this document.
0278    *
0279    *   end_glyph_id ::
0280    *     The last glyph ID in the glyph range covered by this document.
0281    *
0282    *   transform ::
0283    *     A 2x2 transformation matrix to apply to the glyph while rendering
0284    *     it.
0285    *
0286    *   delta ::
0287    *     The translation to apply to the glyph while rendering.
0288    *
0289    * @note:
0290    *   When an @FT_GlyphSlot object `slot` is passed down to a renderer, the
0291    *   renderer can only access the `metrics` and `units_per_EM` fields via
0292    *   `slot->face`.  However, when @FT_Glyph_To_Bitmap sets up a dummy
0293    *   object, it has no way to set a `face` object.  Thus, metrics
0294    *   information and `units_per_EM` (which is necessary for OT-SVG) has to
0295    *   be stored separately.
0296    *
0297    * @since:
0298    *   2.12
0299    */
0300   typedef struct  FT_SVG_DocumentRec_
0301   {
0302     FT_Byte*  svg_document;
0303     FT_ULong  svg_document_length;
0304
0305     FT_Size_Metrics  metrics;
0306     FT_UShort        units_per_EM;
0307
0308     FT_UShort  start_glyph_id;
0309     FT_UShort  end_glyph_id;
0310
0311     FT_Matrix  transform;
0312     FT_Vector  delta;
0313
0314   } FT_SVG_DocumentRec;
0315
0316
0317   /**************************************************************************
0318    *
0319    * @type:
0320    *   FT_SVG_Document
0321    *
0322    * @description:
0323    *   A handle to an @FT_SVG_DocumentRec object.
0324    *
0325    * @since:
0326    *   2.12
0327    */
0328   typedef struct FT_SVG_DocumentRec_*  FT_SVG_Document;
0329
0330
0331 FT_END_HEADER
0332
0333 #endif /* OTSVG_H_ */
0334
0335
0336 /* END */