1/****************************************************************************
2 *
3 * ftglyph.h
4 *
5 * FreeType convenience functions to handle glyphs (specification).
6 *
7 * Copyright (C) 1996-2021 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 @FT_Glyph fields.
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 * @function:
228 * FT_New_Glyph
229 *
230 * @description:
231 * A function used to create a new empty glyph image. Note that the
232 * created @FT_Glyph object must be released with @FT_Done_Glyph.
233 *
234 * @input:
235 * library ::
236 * A handle to the FreeType library object.
237 *
238 * format ::
239 * The format of the glyph's image.
240 *
241 * @output:
242 * aglyph ::
243 * A handle to the glyph object.
244 *
245 * @return:
246 * FreeType error code. 0~means success.
247 *
248 * @since:
249 * 2.10
250 */
251 FT_EXPORT( FT_Error )
252 FT_New_Glyph( FT_Library library,
253 FT_Glyph_Format format,
254 FT_Glyph *aglyph );
255
256
257 /**************************************************************************
258 *
259 * @function:
260 * FT_Get_Glyph
261 *
262 * @description:
263 * A function used to extract a glyph image from a slot. Note that the
264 * created @FT_Glyph object must be released with @FT_Done_Glyph.
265 *
266 * @input:
267 * slot ::
268 * A handle to the source glyph slot.
269 *
270 * @output:
271 * aglyph ::
272 * A handle to the glyph object.
273 *
274 * @return:
275 * FreeType error code. 0~means success.
276 *
277 * @note:
278 * Because `*aglyph->advance.x` and `*aglyph->advance.y` are 16.16
279 * fixed-point numbers, `slot->advance.x` and `slot->advance.y` (which
280 * are in 26.6 fixed-point format) must be in the range ]-32768;32768[.
281 */
282 FT_EXPORT( FT_Error )
283 FT_Get_Glyph( FT_GlyphSlot slot,
284 FT_Glyph *aglyph );
285
286
287 /**************************************************************************
288 *
289 * @function:
290 * FT_Glyph_Copy
291 *
292 * @description:
293 * A function used to copy a glyph image. Note that the created
294 * @FT_Glyph object must be released with @FT_Done_Glyph.
295 *
296 * @input:
297 * source ::
298 * A handle to the source glyph object.
299 *
300 * @output:
301 * target ::
302 * A handle to the target glyph object. 0~in case of error.
303 *
304 * @return:
305 * FreeType error code. 0~means success.
306 */
307 FT_EXPORT( FT_Error )
308 FT_Glyph_Copy( FT_Glyph source,
309 FT_Glyph *target );
310
311
312 /**************************************************************************
313 *
314 * @function:
315 * FT_Glyph_Transform
316 *
317 * @description:
318 * Transform a glyph image if its format is scalable.
319 *
320 * @inout:
321 * glyph ::
322 * A handle to the target glyph object.
323 *
324 * @input:
325 * matrix ::
326 * A pointer to a 2x2 matrix to apply.
327 *
328 * delta ::
329 * A pointer to a 2d vector to apply. Coordinates are expressed in
330 * 1/64th of a pixel.
331 *
332 * @return:
333 * FreeType error code (if not 0, the glyph format is not scalable).
334 *
335 * @note:
336 * The 2x2 transformation matrix is also applied to the glyph's advance
337 * vector.
338 */
339 FT_EXPORT( FT_Error )
340 FT_Glyph_Transform( FT_Glyph glyph,
341 const FT_Matrix* matrix,
342 const FT_Vector* delta );
343
344
345 /**************************************************************************
346 *
347 * @enum:
348 * FT_Glyph_BBox_Mode
349 *
350 * @description:
351 * The mode how the values of @FT_Glyph_Get_CBox are returned.
352 *
353 * @values:
354 * FT_GLYPH_BBOX_UNSCALED ::
355 * Return unscaled font units.
356 *
357 * FT_GLYPH_BBOX_SUBPIXELS ::
358 * Return unfitted 26.6 coordinates.
359 *
360 * FT_GLYPH_BBOX_GRIDFIT ::
361 * Return grid-fitted 26.6 coordinates.
362 *
363 * FT_GLYPH_BBOX_TRUNCATE ::
364 * Return coordinates in integer pixels.
365 *
366 * FT_GLYPH_BBOX_PIXELS ::
367 * Return grid-fitted pixel coordinates.
368 */
369 typedef enum FT_Glyph_BBox_Mode_
370 {
371 FT_GLYPH_BBOX_UNSCALED = 0,
372 FT_GLYPH_BBOX_SUBPIXELS = 0,
373 FT_GLYPH_BBOX_GRIDFIT = 1,
374 FT_GLYPH_BBOX_TRUNCATE = 2,
375 FT_GLYPH_BBOX_PIXELS = 3
376
377 } FT_Glyph_BBox_Mode;
378
379
380 /* these constants are deprecated; use the corresponding */
381 /* `FT_Glyph_BBox_Mode` values instead */
382#define ft_glyph_bbox_unscaled FT_GLYPH_BBOX_UNSCALED
383#define ft_glyph_bbox_subpixels FT_GLYPH_BBOX_SUBPIXELS
384#define ft_glyph_bbox_gridfit FT_GLYPH_BBOX_GRIDFIT
385#define ft_glyph_bbox_truncate FT_GLYPH_BBOX_TRUNCATE
386#define ft_glyph_bbox_pixels FT_GLYPH_BBOX_PIXELS
387
388
389 /**************************************************************************
390 *
391 * @function:
392 * FT_Glyph_Get_CBox
393 *
394 * @description:
395 * Return a glyph's 'control box'. The control box encloses all the
396 * outline's points, including Bezier control points. Though it
397 * coincides with the exact bounding box for most glyphs, it can be
398 * slightly larger in some situations (like when rotating an outline that
399 * contains Bezier outside arcs).
400 *
401 * Computing the control box is very fast, while getting the bounding box
402 * can take much more time as it needs to walk over all segments and arcs
403 * in the outline. To get the latter, you can use the 'ftbbox'
404 * component, which is dedicated to this single task.
405 *
406 * @input:
407 * glyph ::
408 * A handle to the source glyph object.
409 *
410 * mode ::
411 * The mode that indicates how to interpret the returned bounding box
412 * values.
413 *
414 * @output:
415 * acbox ::
416 * The glyph coordinate bounding box. Coordinates are expressed in
417 * 1/64th of pixels if it is grid-fitted.
418 *
419 * @note:
420 * Coordinates are relative to the glyph origin, using the y~upwards
421 * convention.
422 *
423 * If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode` must
424 * be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font units in 26.6
425 * pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS is another name for
426 * this constant.
427 *
428 * If the font is tricky and the glyph has been loaded with
429 * @FT_LOAD_NO_SCALE, the resulting CBox is meaningless. To get
430 * reasonable values for the CBox it is necessary to load the glyph at a
431 * large ppem value (so that the hinting instructions can properly shift
432 * and scale the subglyphs), then extracting the CBox, which can be
433 * eventually converted back to font units.
434 *
435 * Note that the maximum coordinates are exclusive, which means that one
436 * can compute the width and height of the glyph image (be it in integer
437 * or 26.6 pixels) as:
438 *
439 * ```
440 * width = bbox.xMax - bbox.xMin;
441 * height = bbox.yMax - bbox.yMin;
442 * ```
443 *
444 * Note also that for 26.6 coordinates, if `bbox_mode` is set to
445 * @FT_GLYPH_BBOX_GRIDFIT, the coordinates will also be grid-fitted,
446 * which corresponds to:
447 *
448 * ```
449 * bbox.xMin = FLOOR(bbox.xMin);
450 * bbox.yMin = FLOOR(bbox.yMin);
451 * bbox.xMax = CEILING(bbox.xMax);
452 * bbox.yMax = CEILING(bbox.yMax);
453 * ```
454 *
455 * To get the bbox in pixel coordinates, set `bbox_mode` to
456 * @FT_GLYPH_BBOX_TRUNCATE.
457 *
458 * To get the bbox in grid-fitted pixel coordinates, set `bbox_mode` to
459 * @FT_GLYPH_BBOX_PIXELS.
460 */
461 FT_EXPORT( void )
462 FT_Glyph_Get_CBox( FT_Glyph glyph,
463 FT_UInt bbox_mode,
464 FT_BBox *acbox );
465
466
467 /**************************************************************************
468 *
469 * @function:
470 * FT_Glyph_To_Bitmap
471 *
472 * @description:
473 * Convert a given glyph object to a bitmap glyph object.
474 *
475 * @inout:
476 * the_glyph ::
477 * A pointer to a handle to the target glyph.
478 *
479 * @input:
480 * render_mode ::
481 * An enumeration that describes how the data is rendered.
482 *
483 * origin ::
484 * A pointer to a vector used to translate the glyph image before
485 * rendering. Can be~0 (if no translation). The origin is expressed
486 * in 26.6 pixels.
487 *
488 * destroy ::
489 * A boolean that indicates that the original glyph image should be
490 * destroyed by this function. It is never destroyed in case of error.
491 *
492 * @return:
493 * FreeType error code. 0~means success.
494 *
495 * @note:
496 * This function does nothing if the glyph format isn't scalable.
497 *
498 * The glyph image is translated with the `origin` vector before
499 * rendering.
500 *
501 * The first parameter is a pointer to an @FT_Glyph handle, that will be
502 * _replaced_ by this function (with newly allocated data). Typically,
503 * you would use (omitting error handling):
504 *
505 * ```
506 * FT_Glyph glyph;
507 * FT_BitmapGlyph glyph_bitmap;
508 *
509 *
510 * // load glyph
511 * error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAULT );
512 *
513 * // extract glyph image
514 * error = FT_Get_Glyph( face->glyph, &glyph );
515 *
516 * // convert to a bitmap (default render mode + destroying old)
517 * if ( glyph->format != FT_GLYPH_FORMAT_BITMAP )
518 * {
519 * error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_NORMAL,
520 * 0, 1 );
521 * if ( error ) // `glyph' unchanged
522 * ...
523 * }
524 *
525 * // access bitmap content by typecasting
526 * glyph_bitmap = (FT_BitmapGlyph)glyph;
527 *
528 * // do funny stuff with it, like blitting/drawing
529 * ...
530 *
531 * // discard glyph image (bitmap or not)
532 * FT_Done_Glyph( glyph );
533 * ```
534 *
535 * Here is another example, again without error handling:
536 *
537 * ```
538 * FT_Glyph glyphs[MAX_GLYPHS]
539 *
540 *
541 * ...
542 *
543 * for ( idx = 0; i < MAX_GLYPHS; i++ )
544 * error = FT_Load_Glyph( face, idx, FT_LOAD_DEFAULT ) ||
545 * FT_Get_Glyph ( face->glyph, &glyphs[idx] );
546 *
547 * ...
548 *
549 * for ( idx = 0; i < MAX_GLYPHS; i++ )
550 * {
551 * FT_Glyph bitmap = glyphs[idx];
552 *
553 *
554 * ...
555 *
556 * // after this call, `bitmap' no longer points into
557 * // the `glyphs' array (and the old value isn't destroyed)
558 * FT_Glyph_To_Bitmap( &bitmap, FT_RENDER_MODE_MONO, 0, 0 );
559 *
560 * ...
561 *
562 * FT_Done_Glyph( bitmap );
563 * }
564 *
565 * ...
566 *
567 * for ( idx = 0; i < MAX_GLYPHS; i++ )
568 * FT_Done_Glyph( glyphs[idx] );
569 * ```
570 */
571 FT_EXPORT( FT_Error )
572 FT_Glyph_To_Bitmap( FT_Glyph* the_glyph,
573 FT_Render_Mode render_mode,
574 const FT_Vector* origin,
575 FT_Bool destroy );
576
577
578 /**************************************************************************
579 *
580 * @function:
581 * FT_Done_Glyph
582 *
583 * @description:
584 * Destroy a given glyph.
585 *
586 * @input:
587 * glyph ::
588 * A handle to the target glyph object.
589 */
590 FT_EXPORT( void )
591 FT_Done_Glyph( FT_Glyph glyph );
592
593 /* */
594
595
596 /* other helpful functions */
597
598 /**************************************************************************
599 *
600 * @section:
601 * computations
602 *
603 */
604
605
606 /**************************************************************************
607 *
608 * @function:
609 * FT_Matrix_Multiply
610 *
611 * @description:
612 * Perform the matrix operation `b = a*b`.
613 *
614 * @input:
615 * a ::
616 * A pointer to matrix `a`.
617 *
618 * @inout:
619 * b ::
620 * A pointer to matrix `b`.
621 *
622 * @note:
623 * The result is undefined if either `a` or `b` is zero.
624 *
625 * Since the function uses wrap-around arithmetic, results become
626 * meaningless if the arguments are very large.
627 */
628 FT_EXPORT( void )
629 FT_Matrix_Multiply( const FT_Matrix* a,
630 FT_Matrix* b );
631
632
633 /**************************************************************************
634 *
635 * @function:
636 * FT_Matrix_Invert
637 *
638 * @description:
639 * Invert a 2x2 matrix. Return an error if it can't be inverted.
640 *
641 * @inout:
642 * matrix ::
643 * A pointer to the target matrix. Remains untouched in case of error.
644 *
645 * @return:
646 * FreeType error code. 0~means success.
647 */
648 FT_EXPORT( FT_Error )
649 FT_Matrix_Invert( FT_Matrix* matrix );
650
651 /* */
652
653
654FT_END_HEADER
655
656#endif /* FTGLYPH_H_ */
657
658
659/* END */
660
661
662/* Local Variables: */
663/* coding: utf-8 */
664/* End: */
665