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