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