include/freetype/otsvg.h

   1 /****************************************************************************
   2  *
   3  * otsvg.h
   4  *
   5  *   Interface for OT-SVG support related things (specification).
   6  *
   7  * Copyright (C) 2022-2023 by
   8  * David Turner, Robert Wilhelm, Werner Lemberg, and Moazin Khatti.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17
  18
  19 #ifndef OTSVG_H_
  20 #define OTSVG_H_
  21
  22 #include <freetype/freetype.h>
  23
  24 #ifdef FREETYPE_H
  25 #error "freetype.h of FreeType 1 has been loaded!"
  26 #error "Please fix the directory search order for header files"
  27 #error "so that freetype.h of FreeType 2 is found first."
  28 #endif
  29
  30
  31 FT_BEGIN_HEADER
  32
  33
  34   /**************************************************************************
  35    *
  36    * @section:
  37    *   svg_fonts
  38    *
  39    * @title:
  40    *   OpenType SVG Fonts
  41    *
  42    * @abstract:
  43    *   OT-SVG API between FreeType and an external SVG rendering library.
  44    *
  45    * @description:
  46    *   This section describes the four hooks necessary to render SVG
  47    *   'documents' that are contained in an OpenType font's 'SVG~' table.
  48    *
  49    *   For more information on the implementation, see our standard hooks
  50    *   based on 'librsvg' in the [FreeType Demo
  51    *   Programs](https://gitlab.freedesktop.org/freetype/freetype-demos)
  52    *   repository.
  53    *
  54    */
  55
  56
  57   /**************************************************************************
  58    *
  59    * @functype:
  60    *   SVG_Lib_Init_Func
  61    *
  62    * @description:
  63    *   A callback that is called when the first OT-SVG glyph is rendered in
  64    *   the lifetime of an @FT_Library object.  In a typical implementation,
  65    *   one would want to allocate a structure and point the `data_pointer`
  66    *   to it and perform any library initializations that might be needed.
  67    *
  68    * @inout:
  69    *   data_pointer ::
  70    *     The SVG rendering module stores a pointer variable that can be used
  71    *     by clients to store any data that needs to be shared across
  72    *     different hooks.  `data_pointer` is essentially a pointer to that
  73    *     pointer such that it can be written to as well as read from.
  74    *
  75    * @return:
  76    *   FreeType error code.  0 means success.
  77    *
  78    * @since:
  79    *   2.12
  80    */
  81   typedef FT_Error
  82   (*SVG_Lib_Init_Func)( FT_Pointer  *data_pointer );
  83
  84
  85   /**************************************************************************
  86    *
  87    * @functype:
  88    *   SVG_Lib_Free_Func
  89    *
  90    * @description:
  91    *   A callback that is called when the `ot-svg` module is being freed.
  92    *   It is only called if the init hook was called earlier.  This means
  93    *   that neither the init nor the free hook is called if no OT-SVG glyph
  94    *   is rendered.
  95    *
  96    *   In a typical implementation, one would want to free any state
  97    *   structure that was allocated in the init hook and perform any
  98    *   library-related closure that might be needed.
  99    *
 100    * @inout:
 101    *   data_pointer ::
 102    *     The SVG rendering module stores a pointer variable that can be used
 103    *     by clients to store any data that needs to be shared across
 104    *     different hooks.  `data_pointer` is essentially a pointer to that
 105    *     pointer such that it can be written to as well as read from.
 106    *
 107    * @since:
 108    *   2.12
 109    */
 110   typedef void
 111   (*SVG_Lib_Free_Func)( FT_Pointer  *data_pointer );
 112
 113
 114   /**************************************************************************
 115    *
 116    * @functype:
 117    *   SVG_Lib_Render_Func
 118    *
 119    * @description:
 120    *   A callback that is called to render an OT-SVG glyph.  This callback
 121    *   hook is called right after the preset hook @SVG_Lib_Preset_Slot_Func
 122    *   has been called with `cache` set to `TRUE`.  The data necessary to
 123    *   render is available through the handle @FT_SVG_Document, which is set
 124    *   in the `other` field of @FT_GlyphSlotRec.
 125    *
 126    *   The render hook is expected to render the SVG glyph to the bitmap
 127    *   buffer that is allocated already at `slot->bitmap.buffer`.  It also
 128    *   sets the `num_grays` value as well as `slot->format`.
 129    *
 130    * @input:
 131    *   slot ::
 132    *     The slot to render.
 133    *
 134    * @inout:
 135    *   data_pointer ::
 136    *     The SVG rendering module stores a pointer variable that can be used
 137    *     by clients to store any data that needs to be shared across
 138    *     different hooks.  `data_pointer` is essentially a pointer to that
 139    *     pointer such that it can be written to as well as read from.
 140    *
 141    * @return:
 142    *   FreeType error code.  0 means success.
 143    *
 144    * @since:
 145    *   2.12
 146    */
 147   typedef FT_Error
 148   (*SVG_Lib_Render_Func)( FT_GlyphSlot  slot,
 149                           FT_Pointer   *data_pointer );
 150
 151
 152   /**************************************************************************
 153    *
 154    * @functype:
 155    *   SVG_Lib_Preset_Slot_Func
 156    *
 157    * @description:
 158    *   A callback that is called to preset the glyph slot.  It is called from
 159    *   two places.
 160    *
 161    *   1. When `FT_Load_Glyph` needs to preset the glyph slot.
 162    *
 163    *   2. Right before the `svg` module calls the render callback hook.
 164    *
 165    *   When it is the former, the argument `cache` is set to `FALSE`.  When
 166    *   it is the latter, the argument `cache` is set to `TRUE`.  This
 167    *   distinction has been made because many calculations that are necessary
 168    *   for presetting a glyph slot are the same needed later for the render
 169    *   callback hook.  Thus, if `cache` is `TRUE`, the hook can _cache_ those
 170    *   calculations in a memory block referenced by the state pointer.
 171    *
 172    *   This hook is expected to preset the slot by setting parameters such as
 173    *   `bitmap_left`, `bitmap_top`, `width`, `rows`, `pitch`, and
 174    *   `pixel_mode`.  It is also expected to set all the metrics for the slot
 175    *   including the vertical advance if it is not already set.  Typically,
 176    *   fonts have horizontal advances but not vertical ones.  If those are
 177    *   available, they had already been set, otherwise they have to be
 178    *   estimated and set manually.  The hook must take into account the
 179    *   transformations that have been set, and translate the transformation
 180    *   matrices into the SVG coordinate system, as the original matrix is
 181    *   intended for the TTF/CFF coordinate system.
 182    *
 183    * @input:
 184    *   slot ::
 185    *     The glyph slot that has the SVG document loaded.
 186    *
 187    *   cache ::
 188    *     See description.
 189    *
 190    * @inout:
 191    *   data_pointer ::
 192    *     The SVG rendering module stores a pointer variable that can be used
 193    *     by clients to store any data that needs to be shared across
 194    *     different hooks.  `data_pointer` is essentially a pointer to that
 195    *     pointer such that it can be written to as well as read from.
 196    *
 197    * @return:
 198    *   FreeType error code.  0 means success.
 199    *
 200    * @since:
 201    *   2.12
 202    */
 203   typedef FT_Error
 204   (*SVG_Lib_Preset_Slot_Func)( FT_GlyphSlot  slot,
 205                                FT_Bool       cache,
 206                                FT_Pointer   *state );
 207
 208
 209   /**************************************************************************
 210    *
 211    * @struct:
 212    *   SVG_RendererHooks
 213    *
 214    * @description:
 215    *   A structure that stores the four hooks needed to render OT-SVG glyphs
 216    *   properly.  The structure is publicly used to set the hooks via the
 217    *   @svg-hooks driver property.
 218    *
 219    *   The behavior of each hook is described in its documentation.  One
 220    *   thing to note is that the preset hook and the render hook often need
 221    *   to do the same operations; therefore, it's better to cache the
 222    *   intermediate data in a state structure to avoid calculating it twice.
 223    *   For example, in the preset hook one can draw the glyph on a recorder
 224    *   surface and later create a bitmap surface from it in the render hook.
 225    *
 226    *   All four hooks must be non-NULL.
 227    *
 228    * @fields:
 229    *   init_svg ::
 230    *     The initialization hook.
 231    *
 232    *   free_svg ::
 233    *     The cleanup hook.
 234    *
 235    *   render_hook ::
 236    *     The render hook.
 237    *
 238    *   preset_slot ::
 239    *     The preset hook.
 240    *
 241    * @since:
 242    *   2.12
 243    */
 244   typedef struct SVG_RendererHooks_
 245   {
 246     SVG_Lib_Init_Func    init_svg;
 247     SVG_Lib_Free_Func    free_svg;
 248     SVG_Lib_Render_Func  render_svg;
 249
 250     SVG_Lib_Preset_Slot_Func  preset_slot;
 251
 252   } SVG_RendererHooks;
 253
 254
 255   /**************************************************************************
 256    *
 257    * @struct:
 258    *   FT_SVG_DocumentRec
 259    *
 260    * @description:
 261    *   A structure that models one SVG document.
 262    *
 263    * @fields:
 264    *   svg_document ::
 265    *     A pointer to the SVG document.
 266    *
 267    *   svg_document_length ::
 268    *     The length of `svg_document`.
 269    *
 270    *   metrics ::
 271    *     A metrics object storing the size information.
 272    *
 273    *   units_per_EM ::
 274    *     The size of the EM square.
 275    *
 276    *   start_glyph_id ::
 277    *     The first glyph ID in the glyph range covered by this document.
 278    *
 279    *   end_glyph_id ::
 280    *     The last glyph ID in the glyph range covered by this document.
 281    *
 282    *   transform ::
 283    *     A 2x2 transformation matrix to apply to the glyph while rendering
 284    *     it.
 285    *
 286    *   delta ::
 287    *     The translation to apply to the glyph while rendering.
 288    *
 289    * @note:
 290    *   When an @FT_GlyphSlot object `slot` is passed down to a renderer, the
 291    *   renderer can only access the `metrics` and `units_per_EM` fields via
 292    *   `slot->face`.  However, when @FT_Glyph_To_Bitmap sets up a dummy
 293    *   object, it has no way to set a `face` object.  Thus, metrics
 294    *   information and `units_per_EM` (which is necessary for OT-SVG) has to
 295    *   be stored separately.
 296    *
 297    * @since:
 298    *   2.12
 299    */
 300   typedef struct  FT_SVG_DocumentRec_
 301   {
 302     FT_Byte*  svg_document;
 303     FT_ULong  svg_document_length;
 304
 305     FT_Size_Metrics  metrics;
 306     FT_UShort        units_per_EM;
 307
 308     FT_UShort  start_glyph_id;
 309     FT_UShort  end_glyph_id;
 310
 311     FT_Matrix  transform;
 312     FT_Vector  delta;
 313
 314   } FT_SVG_DocumentRec;
 315
 316
 317   /**************************************************************************
 318    *
 319    * @type:
 320    *   FT_SVG_Document
 321    *
 322    * @description:
 323    *   A handle to an @FT_SVG_DocumentRec object.
 324    *
 325    * @since:
 326    *   2.12
 327    */
 328   typedef struct FT_SVG_DocumentRec_*  FT_SVG_Document;
 329
 330
 331 FT_END_HEADER
 332
 333 #endif /* OTSVG_H_ */
 334
 335
 336 /* END */