1 /***************************************************************************/ 2 /* */ 3 /* ftglyph.h */ 4 /* */ 5 /* FreeType convenience functions to handle glyphs (specification). */ 6 /* */ 7 /* Copyright 1996-2015 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 FT_EXPORT( FT_Error ) 235 FT_Get_Glyph( FT_GlyphSlot slot, 236 FT_Glyph *aglyph ); 237 238 239 /*************************************************************************/ 240 /* */ 241 /* <Function> */ 242 /* FT_Glyph_Copy */ 243 /* */ 244 /* <Description> */ 245 /* A function used to copy a glyph image. Note that the created */ 246 /* @FT_Glyph object must be released with @FT_Done_Glyph. */ 247 /* */ 248 /* <Input> */ 249 /* source :: A handle to the source glyph object. */ 250 /* */ 251 /* <Output> */ 252 /* target :: A handle to the target glyph object. 0~in case of */ 253 /* error. */ 254 /* */ 255 /* <Return> */ 256 /* FreeType error code. 0~means success. */ 257 /* */ 258 FT_EXPORT( FT_Error ) 259 FT_Glyph_Copy( FT_Glyph source, 260 FT_Glyph *target ); 261 262 263 /*************************************************************************/ 264 /* */ 265 /* <Function> */ 266 /* FT_Glyph_Transform */ 267 /* */ 268 /* <Description> */ 269 /* Transform a glyph image if its format is scalable. */ 270 /* */ 271 /* <InOut> */ 272 /* glyph :: A handle to the target glyph object. */ 273 /* */ 274 /* <Input> */ 275 /* matrix :: A pointer to a 2x2 matrix to apply. */ 276 /* */ 277 /* delta :: A pointer to a 2d vector to apply. Coordinates are */ 278 /* expressed in 1/64th of a pixel. */ 279 /* */ 280 /* <Return> */ 281 /* FreeType error code (if not 0, the glyph format is not scalable). */ 282 /* */ 283 /* <Note> */ 284 /* The 2x2 transformation matrix is also applied to the glyph's */ 285 /* advance vector. */ 286 /* */ 287 FT_EXPORT( FT_Error ) 288 FT_Glyph_Transform( FT_Glyph glyph, 289 FT_Matrix* matrix, 290 FT_Vector* delta ); 291 292 293 /*************************************************************************/ 294 /* */ 295 /* <Enum> */ 296 /* FT_Glyph_BBox_Mode */ 297 /* */ 298 /* <Description> */ 299 /* The mode how the values of @FT_Glyph_Get_CBox are returned. */ 300 /* */ 301 /* <Values> */ 302 /* FT_GLYPH_BBOX_UNSCALED :: */ 303 /* Return unscaled font units. */ 304 /* */ 305 /* FT_GLYPH_BBOX_SUBPIXELS :: */ 306 /* Return unfitted 26.6 coordinates. */ 307 /* */ 308 /* FT_GLYPH_BBOX_GRIDFIT :: */ 309 /* Return grid-fitted 26.6 coordinates. */ 310 /* */ 311 /* FT_GLYPH_BBOX_TRUNCATE :: */ 312 /* Return coordinates in integer pixels. */ 313 /* */ 314 /* FT_GLYPH_BBOX_PIXELS :: */ 315 /* Return grid-fitted pixel coordinates. */ 316 /* */ 317 typedef enum FT_Glyph_BBox_Mode_ 318 { 319 FT_GLYPH_BBOX_UNSCALED = 0, 320 FT_GLYPH_BBOX_SUBPIXELS = 0, 321 FT_GLYPH_BBOX_GRIDFIT = 1, 322 FT_GLYPH_BBOX_TRUNCATE = 2, 323 FT_GLYPH_BBOX_PIXELS = 3 324 325 } FT_Glyph_BBox_Mode; 326 327 328 /* these constants are deprecated; use the corresponding */ 329 /* `FT_Glyph_BBox_Mode' values instead */ 330 #define ft_glyph_bbox_unscaled FT_GLYPH_BBOX_UNSCALED 331 #define ft_glyph_bbox_subpixels FT_GLYPH_BBOX_SUBPIXELS 332 #define ft_glyph_bbox_gridfit FT_GLYPH_BBOX_GRIDFIT 333 #define ft_glyph_bbox_truncate FT_GLYPH_BBOX_TRUNCATE 334 #define ft_glyph_bbox_pixels FT_GLYPH_BBOX_PIXELS 335 336 337 /*************************************************************************/ 338 /* */ 339 /* <Function> */ 340 /* FT_Glyph_Get_CBox */ 341 /* */ 342 /* <Description> */ 343 /* Return a glyph's `control box'. The control box encloses all the */ 344 /* outline's points, including Bézier control points. Though it */ 345 /* coincides with the exact bounding box for most glyphs, it can be */ 346 /* slightly larger in some situations (like when rotating an outline */ 347 /* that contains Bézier outside arcs). */ 348 /* */ 349 /* Computing the control box is very fast, while getting the bounding */ 350 /* box can take much more time as it needs to walk over all segments */ 351 /* and arcs in the outline. To get the latter, you can use the */ 352 /* `ftbbox' component, which is dedicated to this single task. */ 353 /* */ 354 /* <Input> */ 355 /* glyph :: A handle to the source glyph object. */ 356 /* */ 357 /* mode :: The mode that indicates how to interpret the returned */ 358 /* bounding box values. */ 359 /* */ 360 /* <Output> */ 361 /* acbox :: The glyph coordinate bounding box. Coordinates are */ 362 /* expressed in 1/64th of pixels if it is grid-fitted. */ 363 /* */ 364 /* <Note> */ 365 /* Coordinates are relative to the glyph origin, using the y~upwards */ 366 /* convention. */ 367 /* */ 368 /* If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode' */ 369 /* must be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font */ 370 /* units in 26.6 pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS */ 371 /* is another name for this constant. */ 372 /* */ 373 /* If the font is tricky and the glyph has been loaded with */ 374 /* @FT_LOAD_NO_SCALE, the resulting CBox is meaningless. To get */ 375 /* reasonable values for the CBox it is necessary to load the glyph */ 376 /* at a large ppem value (so that the hinting instructions can */ 377 /* properly shift and scale the subglyphs), then extracting the CBox, */ 378 /* which can be eventually converted back to font units. */ 379 /* */ 380 /* Note that the maximum coordinates are exclusive, which means that */ 381 /* one can compute the width and height of the glyph image (be it in */ 382 /* integer or 26.6 pixels) as: */ 383 /* */ 384 /* { */ 385 /* width = bbox.xMax - bbox.xMin; */ 386 /* height = bbox.yMax - bbox.yMin; */ 387 /* } */ 388 /* */ 389 /* Note also that for 26.6 coordinates, if `bbox_mode' is set to */ 390 /* @FT_GLYPH_BBOX_GRIDFIT, the coordinates will also be grid-fitted, */ 391 /* which corresponds to: */ 392 /* */ 393 /* { */ 394 /* bbox.xMin = FLOOR(bbox.xMin); */ 395 /* bbox.yMin = FLOOR(bbox.yMin); */ 396 /* bbox.xMax = CEILING(bbox.xMax); */ 397 /* bbox.yMax = CEILING(bbox.yMax); */ 398 /* } */ 399 /* */ 400 /* To get the bbox in pixel coordinates, set `bbox_mode' to */ 401 /* @FT_GLYPH_BBOX_TRUNCATE. */ 402 /* */ 403 /* To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' */ 404 /* to @FT_GLYPH_BBOX_PIXELS. */ 405 /* */ 406 FT_EXPORT( void ) 407 FT_Glyph_Get_CBox( FT_Glyph glyph, 408 FT_UInt bbox_mode, 409 FT_BBox *acbox ); 410 411 412 /*************************************************************************/ 413 /* */ 414 /* <Function> */ 415 /* FT_Glyph_To_Bitmap */ 416 /* */ 417 /* <Description> */ 418 /* Convert a given glyph object to a bitmap glyph object. */ 419 /* */ 420 /* <InOut> */ 421 /* the_glyph :: A pointer to a handle to the target glyph. */ 422 /* */ 423 /* <Input> */ 424 /* render_mode :: An enumeration that describes how the data is */ 425 /* rendered. */ 426 /* */ 427 /* origin :: A pointer to a vector used to translate the glyph */ 428 /* image before rendering. Can be~0 (if no */ 429 /* translation). The origin is expressed in */ 430 /* 26.6 pixels. */ 431 /* */ 432 /* destroy :: A boolean that indicates that the original glyph */ 433 /* image should be destroyed by this function. It is */ 434 /* never destroyed in case of error. */ 435 /* */ 436 /* <Return> */ 437 /* FreeType error code. 0~means success. */ 438 /* */ 439 /* <Note> */ 440 /* This function does nothing if the glyph format isn't scalable. */ 441 /* */ 442 /* The glyph image is translated with the `origin' vector before */ 443 /* rendering. */ 444 /* */ 445 /* The first parameter is a pointer to an @FT_Glyph handle, that will */ 446 /* be _replaced_ by this function (with newly allocated data). */ 447 /* Typically, you would use (omitting error handling): */ 448 /* */ 449 /* */ 450 /* { */ 451 /* FT_Glyph glyph; */ 452 /* FT_BitmapGlyph glyph_bitmap; */ 453 /* */ 454 /* */ 455 /* // load glyph */ 456 /* error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT ); */ 457 /* */ 458 /* // extract glyph image */ 459 /* error = FT_Get_Glyph( face->glyph, &glyph ); */ 460 /* */ 461 /* // convert to a bitmap (default render mode + destroying old) */ 462 /* if ( glyph->format != FT_GLYPH_FORMAT_BITMAP ) */ 463 /* { */ 464 /* error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_NORMAL, */ 465 /* 0, 1 ); */ 466 /* if ( error ) // `glyph' unchanged */ 467 /* ... */ 468 /* } */ 469 /* */ 470 /* // access bitmap content by typecasting */ 471 /* glyph_bitmap = (FT_BitmapGlyph)glyph; */ 472 /* */ 473 /* // do funny stuff with it, like blitting/drawing */ 474 /* ... */ 475 /* */ 476 /* // discard glyph image (bitmap or not) */ 477 /* FT_Done_Glyph( glyph ); */ 478 /* } */ 479 /* */ 480 /* */ 481 /* Here another example, again without error handling: */ 482 /* */ 483 /* */ 484 /* { */ 485 /* FT_Glyph glyphs[MAX_GLYPHS] */ 486 /* */ 487 /* */ 488 /* ... */ 489 /* */ 490 /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ 491 /* error = FT_Load_Glyph( face, idx, FT_LOAD_DEFAULT ) || */ 492 /* FT_Get_Glyph ( face->glyph, &glyph[idx] ); */ 493 /* */ 494 /* ... */ 495 /* */ 496 /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ 497 /* { */ 498 /* FT_Glyph bitmap = glyphs[idx]; */ 499 /* */ 500 /* */ 501 /* ... */ 502 /* */ 503 /* // after this call, `bitmap' no longer points into */ 504 /* // the `glyphs' array (and the old value isn't destroyed) */ 505 /* FT_Glyph_To_Bitmap( &bitmap, FT_RENDER_MODE_MONO, 0, 0 ); */ 506 /* */ 507 /* ... */ 508 /* */ 509 /* FT_Done_Glyph( bitmap ); */ 510 /* } */ 511 /* */ 512 /* ... */ 513 /* */ 514 /* for ( idx = 0; i < MAX_GLYPHS; i++ ) */ 515 /* FT_Done_Glyph( glyphs[idx] ); */ 516 /* } */ 517 /* */ 518 FT_EXPORT( FT_Error ) 519 FT_Glyph_To_Bitmap( FT_Glyph* the_glyph, 520 FT_Render_Mode render_mode, 521 FT_Vector* origin, 522 FT_Bool destroy ); 523 524 525 /*************************************************************************/ 526 /* */ 527 /* <Function> */ 528 /* FT_Done_Glyph */ 529 /* */ 530 /* <Description> */ 531 /* Destroy a given glyph. */ 532 /* */ 533 /* <Input> */ 534 /* glyph :: A handle to the target glyph object. */ 535 /* */ 536 FT_EXPORT( void ) 537 FT_Done_Glyph( FT_Glyph glyph ); 538 539 /* */ 540 541 542 /* other helpful functions */ 543 544 /*************************************************************************/ 545 /* */ 546 /* <Section> */ 547 /* computations */ 548 /* */ 549 /*************************************************************************/ 550 551 552 /*************************************************************************/ 553 /* */ 554 /* <Function> */ 555 /* FT_Matrix_Multiply */ 556 /* */ 557 /* <Description> */ 558 /* Perform the matrix operation `b = a*b'. */ 559 /* */ 560 /* <Input> */ 561 /* a :: A pointer to matrix `a'. */ 562 /* */ 563 /* <InOut> */ 564 /* b :: A pointer to matrix `b'. */ 565 /* */ 566 /* <Note> */ 567 /* The result is undefined if either `a' or `b' is zero. */ 568 /* */ 569 FT_EXPORT( void ) 570 FT_Matrix_Multiply( const FT_Matrix* a, 571 FT_Matrix* b ); 572 573 574 /*************************************************************************/ 575 /* */ 576 /* <Function> */ 577 /* FT_Matrix_Invert */ 578 /* */ 579 /* <Description> */ 580 /* Invert a 2x2 matrix. Return an error if it can't be inverted. */ 581 /* */ 582 /* <InOut> */ 583 /* matrix :: A pointer to the target matrix. Remains untouched in */ 584 /* case of error. */ 585 /* */ 586 /* <Return> */ 587 /* FreeType error code. 0~means success. */ 588 /* */ 589 FT_EXPORT( FT_Error ) 590 FT_Matrix_Invert( FT_Matrix* matrix ); 591 592 /* */ 593 594 595 FT_END_HEADER 596 597 #endif /* __FTGLYPH_H__ */ 598 599 600 /* END */ 601 602 603 /* Local Variables: */ 604 /* coding: utf-8 */ 605 /* End: */ 606