1 /**************************************************************************** 2 * 3 * ftglyph.h 4 * 5 * FreeType convenience functions to handle glyphs (specification). 6 * 7 * Copyright (C) 1996-2020 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 @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 FT_Matrix* matrix, 342 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 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 654 FT_END_HEADER 655 656 #endif /* FTGLYPH_H_ */ 657 658 659 /* END */ 660 661 662 /* Local Variables: */ 663 /* coding: utf-8 */ 664 /* End: */ 665