1/****************************************************************************
2 *
3 * ftglyph.h
4 *
5 * FreeType convenience functions to handle glyphs (specification).
6 *
7 * Copyright (C) 1996-2023 by
8 * David Turner, Robert Wilhelm, and Werner Lemberg.
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 /**************************************************************************
20 *
21 * This file contains the definition of several convenience functions that
22 * can be used by client applications to easily retrieve glyph bitmaps and
23 * outlines from a given face.
24 *
25 * These functions should be optional if you are writing a font server or
26 * text layout engine on top of FreeType. However, they are pretty handy
27 * for many other simple uses of the library.
28 *
29 */
30
31
32#ifndef FTGLYPH_H_
33#define FTGLYPH_H_
34
35
36#include <freetype/freetype.h>
37
38#ifdef FREETYPE_H
39#error "freetype.h of FreeType 1 has been loaded!"
40#error "Please fix the directory search order for header files"
41#error "so that freetype.h of FreeType 2 is found first."
42#endif
43
44
45FT_BEGIN_HEADER
46
47
48 /**************************************************************************
49 *
50 * @section:
51 * glyph_management
52 *
53 * @title:
54 * Glyph Management
55 *
56 * @abstract:
57 * Generic interface to manage individual glyph data.
58 *
59 * @description:
60 * This section contains definitions used to manage glyph data through
61 * generic @FT_Glyph objects. Each of them can contain a bitmap,
62 * a vector outline, or even images in other formats. These objects are
63 * detached from @FT_Face, contrary to @FT_GlyphSlot.
64 *
65 */
66
67
68 /* forward declaration to a private type */
69 typedef struct FT_Glyph_Class_ FT_Glyph_Class;
70
71
72 /**************************************************************************
73 *
74 * @type:
75 * FT_Glyph
76 *
77 * @description:
78 * Handle to an object used to model generic glyph images. It is a
79 * pointer to the @FT_GlyphRec structure and can contain a glyph bitmap
80 * or pointer.
81 *
82 * @note:
83 * Glyph objects are not owned by the library. You must thus release
84 * them manually (through @FT_Done_Glyph) _before_ calling
85 * @FT_Done_FreeType.
86 */
87 typedef struct FT_GlyphRec_* FT_Glyph;
88
89
90 /**************************************************************************
91 *
92 * @struct:
93 * FT_GlyphRec
94 *
95 * @description:
96 * The root glyph structure contains a given glyph image plus its advance
97 * width in 16.16 fixed-point format.
98 *
99 * @fields:
100 * library ::
101 * A handle to the FreeType library object.
102 *
103 * clazz ::
104 * A pointer to the glyph's class. Private.
105 *
106 * format ::
107 * The format of the glyph's image.
108 *
109 * advance ::
110 * A 16.16 vector that gives the glyph's advance width.
111 */
112 typedef struct FT_GlyphRec_
113 {
114 FT_Library library;
115 const FT_Glyph_Class* clazz;
116 FT_Glyph_Format format;
117 FT_Vector advance;
118
119 } FT_GlyphRec;
120
121
122 /**************************************************************************
123 *
124 * @type:
125 * FT_BitmapGlyph
126 *
127 * @description:
128 * A handle to an object used to model a bitmap glyph image. This is a
129 * 'sub-class' of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec.
130 */
131 typedef struct FT_BitmapGlyphRec_* FT_BitmapGlyph;
132
133
134 /**************************************************************************
135 *
136 * @struct:
137 * FT_BitmapGlyphRec
138 *
139 * @description:
140 * A structure used for bitmap glyph images. This really is a
141 * 'sub-class' of @FT_GlyphRec.
142 *
143 * @fields:
144 * root ::
145 * The root fields of @FT_Glyph.
146 *
147 * left ::
148 * The left-side bearing, i.e., the horizontal distance from the
149 * current pen position to the left border of the glyph bitmap.
150 *
151 * top ::
152 * The top-side bearing, i.e., the vertical distance from the current
153 * pen position to the top border of the glyph bitmap. This distance
154 * is positive for upwards~y!
155 *
156 * bitmap ::
157 * A descriptor for the bitmap.
158 *
159 * @note:
160 * You can typecast an @FT_Glyph to @FT_BitmapGlyph if you have
161 * `glyph->format == FT_GLYPH_FORMAT_BITMAP`. This lets you access the
162 * bitmap's contents easily.
163 *
164 * The corresponding pixel buffer is always owned by @FT_BitmapGlyph and
165 * is thus created and destroyed with it.
166 */
167 typedef struct FT_BitmapGlyphRec_
168 {
169 FT_GlyphRec root;
170 FT_Int left;
171 FT_Int top;
172 FT_Bitmap bitmap;
173
174 } FT_BitmapGlyphRec;
175
176
177 /**************************************************************************
178 *
179 * @type:
180 * FT_OutlineGlyph
181 *
182 * @description:
183 * A handle to an object used to model an outline glyph image. This is a
184 * 'sub-class' of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec.
185 */
186 typedef struct FT_OutlineGlyphRec_* FT_OutlineGlyph;
187
188
189 /**************************************************************************
190 *
191 * @struct:
192 * FT_OutlineGlyphRec
193 *
194 * @description:
195 * A structure used for outline (vectorial) glyph images. This really is
196 * a 'sub-class' of @FT_GlyphRec.
197 *
198 * @fields:
199 * root ::
200 * The root @FT_Glyph fields.
201 *
202 * outline ::
203 * A descriptor for the outline.
204 *
205 * @note:
206 * You can typecast an @FT_Glyph to @FT_OutlineGlyph if you have
207 * `glyph->format == FT_GLYPH_FORMAT_OUTLINE`. This lets you access the
208 * outline's content easily.
209 *
210 * As the outline is extracted from a glyph slot, its coordinates are
211 * expressed normally in 26.6 pixels, unless the flag @FT_LOAD_NO_SCALE
212 * was used in @FT_Load_Glyph or @FT_Load_Char.
213 *
214 * The outline's tables are always owned by the object and are destroyed
215 * with it.
216 */
217 typedef struct FT_OutlineGlyphRec_
218 {
219 FT_GlyphRec root;
220 FT_Outline outline;
221
222 } FT_OutlineGlyphRec;
223
224
225 /**************************************************************************
226 *
227 * @type:
228 * FT_SvgGlyph
229 *
230 * @description:
231 * A handle to an object used to model an SVG glyph. This is a
232 * 'sub-class' of @FT_Glyph, and a pointer to @FT_SvgGlyphRec.
233 *
234 * @since:
235 * 2.12
236 */
237 typedef struct FT_SvgGlyphRec_* FT_SvgGlyph;
238
239
240 /**************************************************************************
241 *
242 * @struct:
243 * FT_SvgGlyphRec
244 *
245 * @description:
246 * A structure used for OT-SVG glyphs. This is a 'sub-class' of
247 * @FT_GlyphRec.
248 *
249 * @fields:
250 * root ::
251 * The root @FT_GlyphRec fields.
252 *
253 * svg_document ::
254 * A pointer to the SVG document.
255 *
256 * svg_document_length ::
257 * The length of `svg_document`.
258 *
259 * glyph_index ::
260 * The index of the glyph to be rendered.
261 *
262 * metrics ::
263 * A metrics object storing the size information.
264 *
265 * units_per_EM ::
266 * The size of the EM square.
267 *
268 * start_glyph_id ::
269 * The first glyph ID in the glyph range covered by this document.
270 *
271 * end_glyph_id ::
272 * The last glyph ID in the glyph range covered by this document.
273 *
274 * transform ::
275 * A 2x2 transformation matrix to apply to the glyph while rendering
276 * it.
277 *
278 * delta ::
279 * Translation to apply to the glyph while rendering.
280 *
281 * @note:
282 * The Glyph Management API requires @FT_Glyph or its 'sub-class' to have
283 * all the information needed to completely define the glyph's rendering.
284 * Outline-based glyphs can directly apply transformations to the outline
285 * but this is not possible for an SVG document that hasn't been parsed.
286 * Therefore, the transformation is stored along with the document. In
287 * the absence of a 'ViewBox' or 'Width'/'Height' attribute, the size of
288 * the ViewPort should be assumed to be 'units_per_EM'.
289 */
290 typedef struct FT_SvgGlyphRec_
291 {
292 FT_GlyphRec root;
293
294 FT_Byte* svg_document;
295 FT_ULong svg_document_length;
296
297 FT_UInt glyph_index;
298
299 FT_Size_Metrics metrics;
300 FT_UShort units_per_EM;
301
302 FT_UShort start_glyph_id;
303 FT_UShort end_glyph_id;
304
305 FT_Matrix transform;
306 FT_Vector delta;
307
308 } FT_SvgGlyphRec;
309
310
311 /**************************************************************************
312 *
313 * @function:
314 * FT_New_Glyph
315 *
316 * @description:
317 * A function used to create a new empty glyph image. Note that the
318 * created @FT_Glyph object must be released with @FT_Done_Glyph.
319 *
320 * @input:
321 * library ::
322 * A handle to the FreeType library object.
323 *
324 * format ::
325 * The format of the glyph's image.
326 *
327 * @output:
328 * aglyph ::
329 * A handle to the glyph object.
330 *
331 * @return:
332 * FreeType error code. 0~means success.
333 *
334 * @since:
335 * 2.10
336 */
337 FT_EXPORT( FT_Error )
338 FT_New_Glyph( FT_Library library,
339 FT_Glyph_Format format,
340 FT_Glyph *aglyph );
341
342
343 /**************************************************************************
344 *
345 * @function:
346 * FT_Get_Glyph
347 *
348 * @description:
349 * A function used to extract a glyph image from a slot. Note that the
350 * created @FT_Glyph object must be released with @FT_Done_Glyph.
351 *
352 * @input:
353 * slot ::
354 * A handle to the source glyph slot.
355 *
356 * @output:
357 * aglyph ::
358 * A handle to the glyph object. `NULL` in case of error.
359 *
360 * @return:
361 * FreeType error code. 0~means success.
362 *
363 * @note:
364 * Because `*aglyph->advance.x` and `*aglyph->advance.y` are 16.16
365 * fixed-point numbers, `slot->advance.x` and `slot->advance.y` (which
366 * are in 26.6 fixed-point format) must be in the range ]-32768;32768[.
367 */
368 FT_EXPORT( FT_Error )
369 FT_Get_Glyph( FT_GlyphSlot slot,
370 FT_Glyph *aglyph );
371
372
373 /**************************************************************************
374 *
375 * @function:
376 * FT_Glyph_Copy
377 *
378 * @description:
379 * A function used to copy a glyph image. Note that the created
380 * @FT_Glyph object must be released with @FT_Done_Glyph.
381 *
382 * @input:
383 * source ::
384 * A handle to the source glyph object.
385 *
386 * @output:
387 * target ::
388 * A handle to the target glyph object. `NULL` in case of error.
389 *
390 * @return:
391 * FreeType error code. 0~means success.
392 */
393 FT_EXPORT( FT_Error )
394 FT_Glyph_Copy( FT_Glyph source,
395 FT_Glyph *target );
396
397
398 /**************************************************************************
399 *
400 * @function:
401 * FT_Glyph_Transform
402 *
403 * @description:
404 * Transform a glyph image if its format is scalable.
405 *
406 * @inout:
407 * glyph ::
408 * A handle to the target glyph object.
409 *
410 * @input:
411 * matrix ::
412 * A pointer to a 2x2 matrix to apply.
413 *
414 * delta ::
415 * A pointer to a 2d vector to apply. Coordinates are expressed in
416 * 1/64 of a pixel.
417 *
418 * @return:
419 * FreeType error code (if not 0, the glyph format is not scalable).
420 *
421 * @note:
422 * The 2x2 transformation matrix is also applied to the glyph's advance
423 * vector.
424 */
425 FT_EXPORT( FT_Error )
426 FT_Glyph_Transform( FT_Glyph glyph,
427 const FT_Matrix* matrix,
428 const FT_Vector* delta );
429
430
431 /**************************************************************************
432 *
433 * @enum:
434 * FT_Glyph_BBox_Mode
435 *
436 * @description:
437 * The mode how the values of @FT_Glyph_Get_CBox are returned.
438 *
439 * @values:
440 * FT_GLYPH_BBOX_UNSCALED ::
441 * Return unscaled font units.
442 *
443 * FT_GLYPH_BBOX_SUBPIXELS ::
444 * Return unfitted 26.6 coordinates.
445 *
446 * FT_GLYPH_BBOX_GRIDFIT ::
447 * Return grid-fitted 26.6 coordinates.
448 *
449 * FT_GLYPH_BBOX_TRUNCATE ::
450 * Return coordinates in integer pixels.
451 *
452 * FT_GLYPH_BBOX_PIXELS ::
453 * Return grid-fitted pixel coordinates.
454 */
455 typedef enum FT_Glyph_BBox_Mode_
456 {
457 FT_GLYPH_BBOX_UNSCALED = 0,
458 FT_GLYPH_BBOX_SUBPIXELS = 0,
459 FT_GLYPH_BBOX_GRIDFIT = 1,
460 FT_GLYPH_BBOX_TRUNCATE = 2,
461 FT_GLYPH_BBOX_PIXELS = 3
462
463 } FT_Glyph_BBox_Mode;
464
465
466 /* these constants are deprecated; use the corresponding */
467 /* `FT_Glyph_BBox_Mode` values instead */
468#define ft_glyph_bbox_unscaled FT_GLYPH_BBOX_UNSCALED
469#define ft_glyph_bbox_subpixels FT_GLYPH_BBOX_SUBPIXELS
470#define ft_glyph_bbox_gridfit FT_GLYPH_BBOX_GRIDFIT
471#define ft_glyph_bbox_truncate FT_GLYPH_BBOX_TRUNCATE
472#define ft_glyph_bbox_pixels FT_GLYPH_BBOX_PIXELS
473
474
475 /**************************************************************************
476 *
477 * @function:
478 * FT_Glyph_Get_CBox
479 *
480 * @description:
481 * Return a glyph's 'control box'. The control box encloses all the
482 * outline's points, including Bezier control points. Though it
483 * coincides with the exact bounding box for most glyphs, it can be
484 * slightly larger in some situations (like when rotating an outline that
485 * contains Bezier outside arcs).
486 *
487 * Computing the control box is very fast, while getting the bounding box
488 * can take much more time as it needs to walk over all segments and arcs
489 * in the outline. To get the latter, you can use the 'ftbbox'
490 * component, which is dedicated to this single task.
491 *
492 * @input:
493 * glyph ::
494 * A handle to the source glyph object.
495 *
496 * mode ::
497 * The mode that indicates how to interpret the returned bounding box
498 * values.
499 *
500 * @output:
501 * acbox ::
502 * The glyph coordinate bounding box. Coordinates are expressed in
503 * 1/64 of pixels if it is grid-fitted.
504 *
505 * @note:
506 * Coordinates are relative to the glyph origin, using the y~upwards
507 * convention.
508 *
509 * If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode` must
510 * be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font units in 26.6
511 * pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS is another name for
512 * this constant.
513 *
514 * If the font is tricky and the glyph has been loaded with
515 * @FT_LOAD_NO_SCALE, the resulting CBox is meaningless. To get
516 * reasonable values for the CBox it is necessary to load the glyph at a
517 * large ppem value (so that the hinting instructions can properly shift
518 * and scale the subglyphs), then extracting the CBox, which can be
519 * eventually converted back to font units.
520 *
521 * Note that the maximum coordinates are exclusive, which means that one
522 * can compute the width and height of the glyph image (be it in integer
523 * or 26.6 pixels) as:
524 *
525 * ```
526 * width = bbox.xMax - bbox.xMin;
527 * height = bbox.yMax - bbox.yMin;
528 * ```
529 *
530 * Note also that for 26.6 coordinates, if `bbox_mode` is set to
531 * @FT_GLYPH_BBOX_GRIDFIT, the coordinates will also be grid-fitted,
532 * which corresponds to:
533 *
534 * ```
535 * bbox.xMin = FLOOR(bbox.xMin);
536 * bbox.yMin = FLOOR(bbox.yMin);
537 * bbox.xMax = CEILING(bbox.xMax);
538 * bbox.yMax = CEILING(bbox.yMax);
539 * ```
540 *
541 * To get the bbox in pixel coordinates, set `bbox_mode` to
542 * @FT_GLYPH_BBOX_TRUNCATE.
543 *
544 * To get the bbox in grid-fitted pixel coordinates, set `bbox_mode` to
545 * @FT_GLYPH_BBOX_PIXELS.
546 */
547 FT_EXPORT( void )
548 FT_Glyph_Get_CBox( FT_Glyph glyph,
549 FT_UInt bbox_mode,
550 FT_BBox *acbox );
551
552
553 /**************************************************************************
554 *
555 * @function:
556 * FT_Glyph_To_Bitmap
557 *
558 * @description:
559 * Convert a given glyph object to a bitmap glyph object.
560 *
561 * @inout:
562 * the_glyph ::
563 * A pointer to a handle to the target glyph.
564 *
565 * @input:
566 * render_mode ::
567 * An enumeration that describes how the data is rendered.
568 *
569 * origin ::
570 * A pointer to a vector used to translate the glyph image before
571 * rendering. Can be~0 (if no translation). The origin is expressed
572 * in 26.6 pixels.
573 *
574 * destroy ::
575 * A boolean that indicates that the original glyph image should be
576 * destroyed by this function. It is never destroyed in case of error.
577 *
578 * @return:
579 * FreeType error code. 0~means success.
580 *
581 * @note:
582 * This function does nothing if the glyph format isn't scalable.
583 *
584 * The glyph image is translated with the `origin` vector before
585 * rendering.
586 *
587 * The first parameter is a pointer to an @FT_Glyph handle that will be
588 * _replaced_ by this function (with newly allocated data). Typically,
589 * you would do something like the following (omitting error handling).
590 *
591 * ```
592 * FT_Glyph glyph;
593 * FT_BitmapGlyph glyph_bitmap;
594 *
595 *
596 * // load glyph
597 * error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAULT );
598 *
599 * // extract glyph image
600 * error = FT_Get_Glyph( face->glyph, &glyph );
601 *
602 * // convert to a bitmap (default render mode + destroying old)
603 * if ( glyph->format != FT_GLYPH_FORMAT_BITMAP )
604 * {
605 * error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_NORMAL,
606 * 0, 1 );
607 * if ( error ) // `glyph' unchanged
608 * ...
609 * }
610 *
611 * // access bitmap content by typecasting
612 * glyph_bitmap = (FT_BitmapGlyph)glyph;
613 *
614 * // do funny stuff with it, like blitting/drawing
615 * ...
616 *
617 * // discard glyph image (bitmap or not)
618 * FT_Done_Glyph( glyph );
619 * ```
620 *
621 * Here is another example, again without error handling.
622 *
623 * ```
624 * FT_Glyph glyphs[MAX_GLYPHS]
625 *
626 *
627 * ...
628 *
629 * for ( idx = 0; i < MAX_GLYPHS; i++ )
630 * error = FT_Load_Glyph( face, idx, FT_LOAD_DEFAULT ) ||
631 * FT_Get_Glyph ( face->glyph, &glyphs[idx] );
632 *
633 * ...
634 *
635 * for ( idx = 0; i < MAX_GLYPHS; i++ )
636 * {
637 * FT_Glyph bitmap = glyphs[idx];
638 *
639 *
640 * ...
641 *
642 * // after this call, `bitmap' no longer points into
643 * // the `glyphs' array (and the old value isn't destroyed)
644 * FT_Glyph_To_Bitmap( &bitmap, FT_RENDER_MODE_MONO, 0, 0 );
645 *
646 * ...
647 *
648 * FT_Done_Glyph( bitmap );
649 * }
650 *
651 * ...
652 *
653 * for ( idx = 0; i < MAX_GLYPHS; i++ )
654 * FT_Done_Glyph( glyphs[idx] );
655 * ```
656 */
657 FT_EXPORT( FT_Error )
658 FT_Glyph_To_Bitmap( FT_Glyph* the_glyph,
659 FT_Render_Mode render_mode,
660 const FT_Vector* origin,
661 FT_Bool destroy );
662
663
664 /**************************************************************************
665 *
666 * @function:
667 * FT_Done_Glyph
668 *
669 * @description:
670 * Destroy a given glyph.
671 *
672 * @input:
673 * glyph ::
674 * A handle to the target glyph object. Can be `NULL`.
675 */
676 FT_EXPORT( void )
677 FT_Done_Glyph( FT_Glyph glyph );
678
679 /* */
680
681
682 /* other helpful functions */
683
684 /**************************************************************************
685 *
686 * @section:
687 * computations
688 *
689 */
690
691
692 /**************************************************************************
693 *
694 * @function:
695 * FT_Matrix_Multiply
696 *
697 * @description:
698 * Perform the matrix operation `b = a*b`.
699 *
700 * @input:
701 * a ::
702 * A pointer to matrix `a`.
703 *
704 * @inout:
705 * b ::
706 * A pointer to matrix `b`.
707 *
708 * @note:
709 * The result is undefined if either `a` or `b` is zero.
710 *
711 * Since the function uses wrap-around arithmetic, results become
712 * meaningless if the arguments are very large.
713 */
714 FT_EXPORT( void )
715 FT_Matrix_Multiply( const FT_Matrix* a,
716 FT_Matrix* b );
717
718
719 /**************************************************************************
720 *
721 * @function:
722 * FT_Matrix_Invert
723 *
724 * @description:
725 * Invert a 2x2 matrix. Return an error if it can't be inverted.
726 *
727 * @inout:
728 * matrix ::
729 * A pointer to the target matrix. Remains untouched in case of error.
730 *
731 * @return:
732 * FreeType error code. 0~means success.
733 */
734 FT_EXPORT( FT_Error )
735 FT_Matrix_Invert( FT_Matrix* matrix );
736
737 /* */
738
739
740FT_END_HEADER
741
742#endif /* FTGLYPH_H_ */
743
744
745/* END */
746
747
748/* Local Variables: */
749/* coding: utf-8 */
750/* End: */
751