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: */ 666