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 */ 337