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