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 45 FT_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 740 FT_END_HEADER 741 742 #endif /* FTGLYPH_H_ */ 743 744 745 /* END */ 746 747 748 /* Local Variables: */ 749 /* coding: utf-8 */ 750 /* End: */ 751