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