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