1 /***************************************************************************/ 2 /* */ 3 /* ftglyph.h */ 4 /* */ 5 /* FreeType convenience functions to handle glyphs (specification). */ 6 /* */ 7 /* Copyright 1996-2001 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 40 FT_BEGIN_HEADER 41 42 43 /*************************************************************************/ 44 /* */ 45 /* <Section> */ 46 /* glyph_management */ 47 /* */ 48 /* <Title> */ 49 /* Glyph Management */ 50 /* */ 51 /* <Abstract> */ 52 /* Generic interface to manage individual glyph data. */ 53 /* */ 54 /* <Description> */ 55 /* This section contains definitions used to manage glyph data */ 56 /* through generic FT_Glyph objects. Each of them can contain a */ 57 /* bitmap, a vector outline, or even images in other formats. */ 58 /* */ 59 /*************************************************************************/ 60 61 62 /* forward declaration to a private type */ 63 typedef struct FT_Glyph_Class_ FT_Glyph_Class; 64 65 66 /*************************************************************************/ 67 /* */ 68 /* <Type> */ 69 /* FT_Glyph */ 70 /* */ 71 /* <Description> */ 72 /* Handle to an object used to model generic glyph images. It is a */ 73 /* pointer to the @FT_GlyphRec structure and can contain a glyph */ 74 /* bitmap or pointer. */ 75 /* */ 76 /* <Note> */ 77 /* Glyph objects are not owned by the library. You must thus release */ 78 /* them manually (through @FT_Done_Glyph) _before_ calling */ 79 /* @FT_Done_FreeType. */ 80 /* */ 81 typedef struct FT_GlyphRec_* FT_Glyph; 82 83 84 /*************************************************************************/ 85 /* */ 86 /* <Struct> */ 87 /* FT_GlyphRec */ 88 /* */ 89 /* <Description> */ 90 /* The root glyph structure contains a given glyph image plus its */ 91 /* advance width in 16.16 fixed float format. */ 92 /* */ 93 /* <Fields> */ 94 /* library :: A handle to the FreeType library object. */ 95 /* */ 96 /* clazz :: A pointer to the glyph's class. Private. */ 97 /* */ 98 /* format :: The format of the glyph's image. */ 99 /* */ 100 /* advance :: A 16.16 vector that gives the glyph's advance width. */ 101 /* */ 102 typedef struct FT_GlyphRec_ 103 { 104 FT_Library library; 105 const FT_Glyph_Class* clazz; 106 FT_Glyph_Format format; 107 FT_Vector advance; 108 109 } FT_GlyphRec; 110 111 112 /*************************************************************************/ 113 /* */ 114 /* <Type> */ 115 /* FT_BitmapGlyph */ 116 /* */ 117 /* <Description> */ 118 /* A handle to an object used to model a bitmap glyph image. This is */ 119 /* a sub-class of @FT_Glyph, and a pointer to @FT_BitmapGlyphRec. */ 120 /* */ 121 typedef struct FT_BitmapGlyphRec_* FT_BitmapGlyph; 122 123 124 /*************************************************************************/ 125 /* */ 126 /* <Struct> */ 127 /* FT_BitmapGlyphRec */ 128 /* */ 129 /* <Description> */ 130 /* A structure used for bitmap glyph images. This really is a */ 131 /* `sub-class' of `FT_GlyphRec'. */ 132 /* */ 133 /* <Fields> */ 134 /* root :: The root FT_Glyph fields. */ 135 /* */ 136 /* left :: The left-side bearing, i.e., the horizontal distance */ 137 /* from the current pen position to the left border of the */ 138 /* glyph bitmap. */ 139 /* */ 140 /* top :: The top-side bearing, i.e., the vertical distance from */ 141 /* the current pen position to the top border of the glyph */ 142 /* bitmap. This distance is positive for upwards-y! */ 143 /* */ 144 /* bitmap :: A descriptor for the bitmap. */ 145 /* */ 146 /* <Note> */ 147 /* You can typecast FT_Glyph to FT_BitmapGlyph if you have */ 148 /* glyph->format == FT_GLYPH_FORMAT_BITMAP. This lets you access */ 149 /* the bitmap's contents easily. */ 150 /* */ 151 /* The corresponding pixel buffer is always owned by the BitmapGlyph */ 152 /* and is thus created and destroyed with it. */ 153 /* */ 154 typedef struct FT_BitmapGlyphRec_ 155 { 156 FT_GlyphRec root; 157 FT_Int left; 158 FT_Int top; 159 FT_Bitmap bitmap; 160 161 } FT_BitmapGlyphRec; 162 163 164 /*************************************************************************/ 165 /* */ 166 /* <Type> */ 167 /* FT_OutlineGlyph */ 168 /* */ 169 /* <Description> */ 170 /* A handle to an object used to model an outline glyph image. This */ 171 /* is a sub-class of @FT_Glyph, and a pointer to @FT_OutlineGlyphRec. */ 172 /* */ 173 typedef struct FT_OutlineGlyphRec_* FT_OutlineGlyph; 174 175 176 /*************************************************************************/ 177 /* */ 178 /* <Struct> */ 179 /* FT_OutlineGlyphRec */ 180 /* */ 181 /* <Description> */ 182 /* A structure used for outline (vectorial) glyph images. This */ 183 /* really is a `sub-class' of `FT_GlyphRec'. */ 184 /* */ 185 /* <Fields> */ 186 /* root :: The root FT_Glyph fields. */ 187 /* */ 188 /* outline :: A descriptor for the outline. */ 189 /* */ 190 /* <Note> */ 191 /* You can typecast FT_Glyph to FT_OutlineGlyph if you have */ 192 /* glyph->format == FT_GLYPH_FORMAT_OUTLINE. This lets you access */ 193 /* the outline's content easily. */ 194 /* */ 195 /* As the outline is extracted from a glyph slot, its coordinates are */ 196 /* expressed normally in 26.6 pixels, unless the flag */ 197 /* FT_LOAD_NO_SCALE was used in FT_Load_Glyph() or FT_Load_Char(). */ 198 /* */ 199 /* The outline's tables are always owned by the object and are */ 200 /* destroyed with it. */ 201 /* */ 202 typedef struct FT_OutlineGlyphRec_ 203 { 204 FT_GlyphRec root; 205 FT_Outline outline; 206 207 } FT_OutlineGlyphRec; 208 209 210 /*************************************************************************/ 211 /* */ 212 /* <Function> */ 213 /* FT_Get_Glyph */ 214 /* */ 215 /* <Description> */ 216 /* A function used to extract a glyph image from a slot. */ 217 /* */ 218 /* <Input> */ 219 /* slot :: A handle to the source glyph slot. */ 220 /* */ 221 /* <Output> */ 222 /* aglyph :: A handle to the glyph object. */ 223 /* */ 224 /* <Return> */ 225 /* FreeType error code. 0 means success. */ 226 /* */ 227 FT_EXPORT( FT_Error ) 228 FT_Get_Glyph( FT_GlyphSlot slot, 229 FT_Glyph *aglyph ); 230 231 232 /*************************************************************************/ 233 /* */ 234 /* <Function> */ 235 /* FT_Glyph_Copy */ 236 /* */ 237 /* <Description> */ 238 /* A function used to copy a glyph image. */ 239 /* */ 240 /* <Input> */ 241 /* source :: A handle to the source glyph object. */ 242 /* */ 243 /* <Output> */ 244 /* target :: A handle to the target glyph object. 0 in case of */ 245 /* error. */ 246 /* */ 247 /* <Return> */ 248 /* FreeType error code. 0 means success. */ 249 /* */ 250 FT_EXPORT( FT_Error ) 251 FT_Glyph_Copy( FT_Glyph source, 252 FT_Glyph *target ); 253 254 255 /*************************************************************************/ 256 /* */ 257 /* <Function> */ 258 /* FT_Glyph_Transform */ 259 /* */ 260 /* <Description> */ 261 /* Transforms a glyph image if its format is scalable. */ 262 /* */ 263 /* <InOut> */ 264 /* glyph :: A handle to the target glyph object. */ 265 /* */ 266 /* <Input> */ 267 /* matrix :: A pointer to a 2x2 matrix to apply. */ 268 /* */ 269 /* delta :: A pointer to a 2d vector to apply. Coordinates are */ 270 /* expressed in 1/64th of a pixel. */ 271 /* */ 272 /* <Return> */ 273 /* FreeType error code (the glyph format is not scalable if it is */ 274 /* not zero). */ 275 /* */ 276 /* <Note> */ 277 /* The 2x2 transformation matrix is also applied to the glyph's */ 278 /* advance vector. */ 279 /* */ 280 FT_EXPORT( FT_Error ) 281 FT_Glyph_Transform( FT_Glyph glyph, 282 FT_Matrix* matrix, 283 FT_Vector* delta ); 284 285 /* */ 286 287 /*************************************************************************/ 288 /* */ 289 /* <Function> */ 290 /* FT_Glyph_Get_CBox */ 291 /* */ 292 /* <Description> */ 293 /* Returns a glyph's `control box'. The control box encloses all the */ 294 /* outline's points, including Bezier control points. Though it */ 295 /* coincides with the exact bounding box for most glyphs, it can be */ 296 /* slightly larger in some situations (like when rotating an outline */ 297 /* which contains Bezier outside arcs). */ 298 /* */ 299 /* Computing the control box is very fast, while getting the bounding */ 300 /* box can take much more time as it needs to walk over all segments */ 301 /* and arcs in the outline. To get the latter, you can use the */ 302 /* `ftbbox' component which is dedicated to this single task. */ 303 /* */ 304 /* <Input> */ 305 /* glyph :: A handle to the source glyph object. */ 306 /* */ 307 /* mode :: The mode which indicates how to interpret the returned */ 308 /* bounding box values. */ 309 /* */ 310 /* <Output> */ 311 /* acbox :: The glyph coordinate bounding box. Coordinates are */ 312 /* expressed in 1/64th of pixels if it is grid-fitted. */ 313 /* */ 314 /* <Note> */ 315 /* Coordinates are relative to the glyph origin, using the Y-upwards */ 316 /* convention. */ 317 /* */ 318 /* If the glyph has been loaded with FT_LOAD_NO_SCALE, `bbox_mode' */ 319 /* must be set to `ft_glyph_bbox_unscaled' to get unscaled font */ 320 /* units. */ 321 /* */ 322 /* If `bbox_mode' is set to `ft_glyph_bbox_subpixels' the bbox */ 323 /* coordinates are returned in 26.6 pixels (i.e. 1/64th of pixels). */ 324 /* */ 325 /* Note that the maximum coordinates are exclusive, which means that */ 326 /* one can compute the width and height of the glyph image (be it in */ 327 /* integer or 26.6 pixels) as: */ 328 /* */ 329 /* width = bbox.xMax - bbox.xMin; */ 330 /* height = bbox.yMax - bbox.yMin; */ 331 /* */ 332 /* Note also that for 26.6 coordinates, if `bbox_mode' is set to */ 333 /* `ft_glyph_bbox_gridfit', the coordinates will also be grid-fitted, */ 334 /* which corresponds to: */ 335 /* */ 336 /* bbox.xMin = FLOOR(bbox.xMin); */ 337 /* bbox.yMin = FLOOR(bbox.yMin); */ 338 /* bbox.xMax = CEILING(bbox.xMax); */ 339 /* bbox.yMax = CEILING(bbox.yMax); */ 340 /* */ 341 /* To get the bbox in pixel coordinates, set `bbox_mode' to */ 342 /* `ft_glyph_bbox_truncate'. */ 343 /* */ 344 /* To get the bbox in grid-fitted pixel coordinates, set `bbox_mode' */ 345 /* to `ft_glyph_bbox_pixels'. */ 346 /* */ 347 /* The default value for `bbox_mode' is `ft_glyph_bbox_pixels'. */ 348 /* */ 349 enum 350 { 351 ft_glyph_bbox_unscaled = 0, /* return unscaled font units */ 352 ft_glyph_bbox_subpixels = 0, /* return unfitted 26.6 coordinates */ 353 ft_glyph_bbox_gridfit = 1, /* return grid-fitted 26.6 coordinates */ 354 ft_glyph_bbox_truncate = 2, /* return coordinates in integer pixels */ 355 ft_glyph_bbox_pixels = 3 /* return grid-fitted pixel coordinates */ 356 }; 357 358 359 FT_EXPORT( void ) 360 FT_Glyph_Get_CBox( FT_Glyph glyph, 361 FT_UInt bbox_mode, 362 FT_BBox *acbox ); 363 364 365 /*************************************************************************/ 366 /* */ 367 /* <Function> */ 368 /* FT_Glyph_To_Bitmap */ 369 /* */ 370 /* <Description> */ 371 /* Converts a given glyph object to a bitmap glyph object. */ 372 /* */ 373 /* <InOut> */ 374 /* the_glyph :: A pointer to a handle to the target glyph. */ 375 /* */ 376 /* <Input> */ 377 /* render_mode :: An enumeration that describe how the data is */ 378 /* rendered. */ 379 /* */ 380 /* origin :: A pointer to a vector used to translate the glyph */ 381 /* image before rendering. Can be 0 (if no */ 382 /* translation). The origin is expressed in */ 383 /* 26.6 pixels. */ 384 /* */ 385 /* destroy :: A boolean that indicates that the original glyph */ 386 /* image should be destroyed by this function. It is */ 387 /* never destroyed in case of error. */ 388 /* */ 389 /* <Return> */ 390 /* FreeType error code. 0 means success. */ 391 /* */ 392 /* <Note> */ 393 /* The glyph image is translated with the `origin' vector before */ 394 /* rendering. In case of error, it it translated back to its */ 395 /* original position and the glyph is left untouched. */ 396 /* */ 397 /* The first parameter is a pointer to a FT_Glyph handle, that will */ 398 /* be replaced by this function. Typically, you would use (omitting */ 399 /* error handling): */ 400 /* */ 401 /* */ 402 /* { */ 403 /* FT_Glyph glyph; */ 404 /* FT_BitmapGlyph glyph_bitmap; */ 405 /* */ 406 /* */ 407 /* // load glyph */ 408 /* error = FT_Load_Char( face, glyph_index, FT_LOAD_DEFAUT ); */ 409 /* */ 410 /* // extract glyph image */ 411 /* error = FT_Get_Glyph( face->glyph, &glyph ); */ 412 /* */ 413 /* // convert to a bitmap (default render mode + destroy old) */ 414 /* if ( glyph->format != FT_GLYPH_FORMAT_BITMAP ) */ 415 /* { */ 416 /* error = FT_Glyph_To_Bitmap( &glyph, ft_render_mode_default, */ 417 /* 0, 1 ); */ 418 /* if ( error ) // glyph unchanged */ 419 /* ... */ 420 /* } */ 421 /* */ 422 /* // access bitmap content by typecasting */ 423 /* glyph_bitmap = (FT_BitmapGlyph)glyph; */ 424 /* */ 425 /* // do funny stuff with it, like blitting/drawing */ 426 /* ... */ 427 /* */ 428 /* // discard glyph image (bitmap or not) */ 429 /* FT_Done_Glyph( glyph ); */ 430 /* } */ 431 /* */ 432 /* */ 433 /* This function will always fail if the glyph's format isn't */ 434 /* scalable. */ 435 /* */ 436 FT_EXPORT( FT_Error ) 437 FT_Glyph_To_Bitmap( FT_Glyph* the_glyph, 438 FT_Render_Mode render_mode, 439 FT_Vector* origin, 440 FT_Bool destroy ); 441 442 443 /*************************************************************************/ 444 /* */ 445 /* <Function> */ 446 /* FT_Done_Glyph */ 447 /* */ 448 /* <Description> */ 449 /* Destroys a given glyph. */ 450 /* */ 451 /* <Input> */ 452 /* glyph :: A handle to the target glyph object. */ 453 /* */ 454 FT_EXPORT( void ) 455 FT_Done_Glyph( FT_Glyph glyph ); 456 457 458 /* other helpful functions */ 459 460 /*************************************************************************/ 461 /* */ 462 /* <Section> */ 463 /* computations */ 464 /* */ 465 /*************************************************************************/ 466 467 468 /*************************************************************************/ 469 /* */ 470 /* <Function> */ 471 /* FT_Matrix_Multiply */ 472 /* */ 473 /* <Description> */ 474 /* Performs the matrix operation `b = a*b'. */ 475 /* */ 476 /* <Input> */ 477 /* a :: A pointer to matrix `a'. */ 478 /* */ 479 /* <InOut> */ 480 /* b :: A pointer to matrix `b'. */ 481 /* */ 482 /* <Note> */ 483 /* The result is undefined if either `a' or `b' is zero. */ 484 /* */ 485 FT_EXPORT( void ) 486 FT_Matrix_Multiply( FT_Matrix* a, 487 FT_Matrix* b ); 488 489 490 /*************************************************************************/ 491 /* */ 492 /* <Function> */ 493 /* FT_Matrix_Invert */ 494 /* */ 495 /* <Description> */ 496 /* Inverts a 2x2 matrix. Returns an error if it can't be inverted. */ 497 /* */ 498 /* <InOut> */ 499 /* matrix :: A pointer to the target matrix. Remains untouched in */ 500 /* case of error. */ 501 /* */ 502 /* <Return> */ 503 /* FreeType error code. 0 means success. */ 504 /* */ 505 FT_EXPORT( FT_Error ) 506 FT_Matrix_Invert( FT_Matrix* matrix ); 507 508 509 /* */ 510 511 512 FT_END_HEADER 513 514 #endif /* __FTGLYPH_H__ */ 515 516 517 /* END */ 518