ftglyph.h revision 049d6fea481044fcc000e7782e5bc7046fc70844
1/***************************************************************************/ 2/* */ 3/* ftglyph.h */ 4/* */ 5/* FreeType convenience functions to handle glyphs (specification). */ 6/* */ 7/* Copyright 1996-2001, 2002, 2003, 2006 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 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 float 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 a @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. */ 223 /* */ 224 /* <Input> */ 225 /* slot :: A handle to the source glyph slot. */ 226 /* */ 227 /* <Output> */ 228 /* aglyph :: A handle to the glyph object. */ 229 /* */ 230 /* <Return> */ 231 /* FreeType error code. 0 means success. */ 232 /* */ 233 FT_EXPORT( FT_Error ) 234 FT_Get_Glyph( FT_GlyphSlot slot, 235 FT_Glyph *aglyph ); 236 237 238 /*************************************************************************/ 239 /* */ 240 /* <Function> */ 241 /* FT_Glyph_Copy */ 242 /* */ 243 /* <Description> */ 244 /* A function used to copy a glyph image. Note that the created */ 245 /* @FT_Glyph object must be released with @FT_Done_Glyph. */ 246 /* */ 247 /* <Input> */ 248 /* source :: A handle to the source glyph object. */ 249 /* */ 250 /* <Output> */ 251 /* target :: A handle to the target glyph object. 0 in case of */ 252 /* error. */ 253 /* */ 254 /* <Return> */ 255 /* FreeType error code. 0 means success. */ 256 /* */ 257 FT_EXPORT( FT_Error ) 258 FT_Glyph_Copy( FT_Glyph source, 259 FT_Glyph *target ); 260 261 262 /*************************************************************************/ 263 /* */ 264 /* <Function> */ 265 /* FT_Glyph_Transform */ 266 /* */ 267 /* <Description> */ 268 /* Transforms a glyph image if its format is scalable. */ 269 /* */ 270 /* <InOut> */ 271 /* glyph :: A handle to the target glyph object. */ 272 /* */ 273 /* <Input> */ 274 /* matrix :: A pointer to a 2x2 matrix to apply. */ 275 /* */ 276 /* delta :: A pointer to a 2d vector to apply. Coordinates are */ 277 /* expressed in 1/64th of a pixel. */ 278 /* */ 279 /* <Return> */ 280 /* FreeType error code (if not 0, the glyph format is not scalable). */ 281 /* */ 282 /* <Note> */ 283 /* The 2x2 transformation matrix is also applied to the glyph's */ 284 /* advance vector. */ 285 /* */ 286 FT_EXPORT( FT_Error ) 287 FT_Glyph_Transform( FT_Glyph glyph, 288 FT_Matrix* matrix, 289 FT_Vector* delta ); 290 291 292 /*************************************************************************/ 293 /* */ 294 /* <Enum> */ 295 /* FT_Glyph_BBox_Mode */ 296 /* */ 297 /* <Description> */ 298 /* The mode how the values of @FT_Glyph_Get_CBox are returned. */ 299 /* */ 300 /* <Values> */ 301 /* FT_GLYPH_BBOX_UNSCALED :: */ 302 /* Return unscaled font units. */ 303 /* */ 304 /* FT_GLYPH_BBOX_SUBPIXELS :: */ 305 /* Return unfitted 26.6 coordinates. */ 306 /* */ 307 /* FT_GLYPH_BBOX_GRIDFIT :: */ 308 /* Return grid-fitted 26.6 coordinates. */ 309 /* */ 310 /* FT_GLYPH_BBOX_TRUNCATE :: */ 311 /* Return coordinates in integer pixels. */ 312 /* */ 313 /* FT_GLYPH_BBOX_PIXELS :: */ 314 /* Return grid-fitted pixel coordinates. */ 315 /* */ 316 typedef enum FT_Glyph_BBox_Mode_ 317 { 318 FT_GLYPH_BBOX_UNSCALED = 0, 319 FT_GLYPH_BBOX_SUBPIXELS = 0, 320 FT_GLYPH_BBOX_GRIDFIT = 1, 321 FT_GLYPH_BBOX_TRUNCATE = 2, 322 FT_GLYPH_BBOX_PIXELS = 3 323 324 } FT_Glyph_BBox_Mode; 325 326 327 /*************************************************************************/ 328 /* */ 329 /* <Enum> */ 330 /* ft_glyph_bbox_xxx */ 331 /* */ 332 /* <Description> */ 333 /* These constants are deprecated. Use the corresponding */ 334 /* @FT_Glyph_BBox_Mode values instead. */ 335 /* */ 336 /* <Values> */ 337 /* ft_glyph_bbox_unscaled :: See @FT_GLYPH_BBOX_UNSCALED. */ 338 /* ft_glyph_bbox_subpixels :: See @FT_GLYPH_BBOX_SUBPIXELS. */ 339 /* ft_glyph_bbox_gridfit :: See @FT_GLYPH_BBOX_GRIDFIT. */ 340 /* ft_glyph_bbox_truncate :: See @FT_GLYPH_BBOX_TRUNCATE. */ 341 /* ft_glyph_bbox_pixels :: See @FT_GLYPH_BBOX_PIXELS. */ 342 /* */ 343#define ft_glyph_bbox_unscaled FT_GLYPH_BBOX_UNSCALED 344#define ft_glyph_bbox_subpixels FT_GLYPH_BBOX_SUBPIXELS 345#define ft_glyph_bbox_gridfit FT_GLYPH_BBOX_GRIDFIT 346#define ft_glyph_bbox_truncate FT_GLYPH_BBOX_TRUNCATE 347#define ft_glyph_bbox_pixels FT_GLYPH_BBOX_PIXELS 348 349 350 /*************************************************************************/ 351 /* */ 352 /* <Function> */ 353 /* FT_Glyph_Get_CBox */ 354 /* */ 355 /* <Description> */ 356 /* Return a glyph's `control box'. The control box encloses all the */ 357 /* outline's points, including Bézier control points. Though it */ 358 /* coincides with the exact bounding box for most glyphs, it can be */ 359 /* slightly larger in some situations (like when rotating an outline */ 360 /* which contains Bézier outside arcs). */ 361 /* */ 362 /* Computing the control box is very fast, while getting the bounding */ 363 /* box can take much more time as it needs to walk over all segments */ 364 /* and arcs in the outline. To get the latter, you can use the */ 365 /* `ftbbox' component which is dedicated to this single task. */ 366 /* */ 367 /* <Input> */ 368 /* glyph :: A handle to the source glyph object. */ 369 /* */ 370 /* mode :: The mode which indicates how to interpret the returned */ 371 /* bounding box values. */ 372 /* */ 373 /* <Output> */ 374 /* acbox :: The glyph coordinate bounding box. Coordinates are */ 375 /* expressed in 1/64th of pixels if it is grid-fitted. */ 376 /* */ 377 /* <Note> */ 378 /* Coordinates are relative to the glyph origin, using the Y-upwards */ 379 /* convention. */ 380 /* */ 381 /* If the glyph has been loaded with @FT_LOAD_NO_SCALE, `bbox_mode' */ 382 /* must be set to @FT_GLYPH_BBOX_UNSCALED to get unscaled font */ 383 /* units in 26.6 pixel format. The value @FT_GLYPH_BBOX_SUBPIXELS */ 384 /* is another name for this constant. */ 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 /* Converts 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 describe 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 /* The glyph image is translated with the `origin' vector before */ 447 /* rendering. */ 448 /* */ 449 /* The first parameter is a pointer to an @FT_Glyph handle, that will */ 450 /* be replaced by this function. Typically, you would use (omitting */ 451 /* error handling): */ 452 /* */ 453 /* */ 454 /* { */ 455 /* FT_Glyph glyph; */ 456 /* FT_BitmapGlyph glyph_bitmap; */ 457 /* */ 458 /* */ 459 /* // load glyph */ 460 /* error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT ); */ 461 /* */ 462 /* // extract glyph image */ 463 /* error = FT_Get_Glyph( face->glyph, &glyph ); */ 464 /* */ 465 /* // convert to a bitmap (default render mode + destroy old) */ 466 /* if ( glyph->format != FT_GLYPH_FORMAT_BITMAP ) */ 467 /* { */ 468 /* error = FT_Glyph_To_Bitmap( &glyph, FT_RENDER_MODE_DEFAULT, */ 469 /* 0, 1 ); */ 470 /* if ( error ) // glyph unchanged */ 471 /* ... */ 472 /* } */ 473 /* */ 474 /* // access bitmap content by typecasting */ 475 /* glyph_bitmap = (FT_BitmapGlyph)glyph; */ 476 /* */ 477 /* // do funny stuff with it, like blitting/drawing */ 478 /* ... */ 479 /* */ 480 /* // discard glyph image (bitmap or not) */ 481 /* FT_Done_Glyph( glyph ); */ 482 /* } */ 483 /* */ 484 /* */ 485 /* This function does nothing if the glyph format isn't scalable. */ 486 /* */ 487 FT_EXPORT( FT_Error ) 488 FT_Glyph_To_Bitmap( FT_Glyph* the_glyph, 489 FT_Render_Mode render_mode, 490 FT_Vector* origin, 491 FT_Bool destroy ); 492 493 494 /*************************************************************************/ 495 /* */ 496 /* <Function> */ 497 /* FT_Done_Glyph */ 498 /* */ 499 /* <Description> */ 500 /* Destroys a given glyph. */ 501 /* */ 502 /* <Input> */ 503 /* glyph :: A handle to the target glyph object. */ 504 /* */ 505 FT_EXPORT( void ) 506 FT_Done_Glyph( FT_Glyph glyph ); 507 508 /* */ 509 510 511 /* other helpful functions */ 512 513 /*************************************************************************/ 514 /* */ 515 /* <Section> */ 516 /* computations */ 517 /* */ 518 /*************************************************************************/ 519 520 521 /*************************************************************************/ 522 /* */ 523 /* <Function> */ 524 /* FT_Matrix_Multiply */ 525 /* */ 526 /* <Description> */ 527 /* Performs the matrix operation `b = a*b'. */ 528 /* */ 529 /* <Input> */ 530 /* a :: A pointer to matrix `a'. */ 531 /* */ 532 /* <InOut> */ 533 /* b :: A pointer to matrix `b'. */ 534 /* */ 535 /* <Note> */ 536 /* The result is undefined if either `a' or `b' is zero. */ 537 /* */ 538 FT_EXPORT( void ) 539 FT_Matrix_Multiply( const FT_Matrix* a, 540 FT_Matrix* b ); 541 542 543 /*************************************************************************/ 544 /* */ 545 /* <Function> */ 546 /* FT_Matrix_Invert */ 547 /* */ 548 /* <Description> */ 549 /* Inverts a 2x2 matrix. Returns an error if it can't be inverted. */ 550 /* */ 551 /* <InOut> */ 552 /* matrix :: A pointer to the target matrix. Remains untouched in */ 553 /* case of error. */ 554 /* */ 555 /* <Return> */ 556 /* FreeType error code. 0 means success. */ 557 /* */ 558 FT_EXPORT( FT_Error ) 559 FT_Matrix_Invert( FT_Matrix* matrix ); 560 561 562 /* */ 563 564 565FT_END_HEADER 566 567#endif /* __FTGLYPH_H__ */ 568 569 570/* END */ 571 572 573/* Local Variables: */ 574/* coding: utf-8 */ 575/* End: */ 576