1 /***************************************************************************/ 2 /* */ 3 /* ftoutln.h */ 4 /* */ 5 /* Support for the FT_Outline type used to store glyph shapes of */ 6 /* most scalable font formats (specification). */ 7 /* */ 8 /* Copyright 1996-2001, 2002, 2003, 2005, 2006, 2007, 2008, 2009 by */ 9 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 10 /* */ 11 /* This file is part of the FreeType project, and may only be used, */ 12 /* modified, and distributed under the terms of the FreeType project */ 13 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 14 /* this file you indicate that you have read the license and */ 15 /* understand and accept it fully. */ 16 /* */ 17 /***************************************************************************/ 18 19 20 #ifndef __FTOUTLN_H__ 21 #define __FTOUTLN_H__ 22 23 24 #include <ft2build.h> 25 #include FT_FREETYPE_H 26 27 #ifdef FREETYPE_H 28 #error "freetype.h of FreeType 1 has been loaded!" 29 #error "Please fix the directory search order for header files" 30 #error "so that freetype.h of FreeType 2 is found first." 31 #endif 32 33 34 FT_BEGIN_HEADER 35 36 37 /*************************************************************************/ 38 /* */ 39 /* <Section> */ 40 /* outline_processing */ 41 /* */ 42 /* <Title> */ 43 /* Outline Processing */ 44 /* */ 45 /* <Abstract> */ 46 /* Functions to create, transform, and render vectorial glyph images. */ 47 /* */ 48 /* <Description> */ 49 /* This section contains routines used to create and destroy scalable */ 50 /* glyph images known as `outlines'. These can also be measured, */ 51 /* transformed, and converted into bitmaps and pixmaps. */ 52 /* */ 53 /* <Order> */ 54 /* FT_Outline */ 55 /* FT_OUTLINE_FLAGS */ 56 /* FT_Outline_New */ 57 /* FT_Outline_Done */ 58 /* FT_Outline_Copy */ 59 /* FT_Outline_Translate */ 60 /* FT_Outline_Transform */ 61 /* FT_Outline_Embolden */ 62 /* FT_Outline_Reverse */ 63 /* FT_Outline_Check */ 64 /* */ 65 /* FT_Outline_Get_CBox */ 66 /* FT_Outline_Get_BBox */ 67 /* */ 68 /* FT_Outline_Get_Bitmap */ 69 /* FT_Outline_Render */ 70 /* */ 71 /* FT_Outline_Decompose */ 72 /* FT_Outline_Funcs */ 73 /* FT_Outline_MoveTo_Func */ 74 /* FT_Outline_LineTo_Func */ 75 /* FT_Outline_ConicTo_Func */ 76 /* FT_Outline_CubicTo_Func */ 77 /* */ 78 /*************************************************************************/ 79 80 81 /*************************************************************************/ 82 /* */ 83 /* <Function> */ 84 /* FT_Outline_Decompose */ 85 /* */ 86 /* <Description> */ 87 /* Walk over an outline's structure to decompose it into individual */ 88 /* segments and Bézier arcs. This function is also able to emit */ 89 /* `move to' and `close to' operations to indicate the start and end */ 90 /* of new contours in the outline. */ 91 /* */ 92 /* <Input> */ 93 /* outline :: A pointer to the source target. */ 94 /* */ 95 /* func_interface :: A table of `emitters', i.e., function pointers */ 96 /* called during decomposition to indicate path */ 97 /* operations. */ 98 /* */ 99 /* <InOut> */ 100 /* user :: A typeless pointer which is passed to each */ 101 /* emitter during the decomposition. It can be */ 102 /* used to store the state during the */ 103 /* decomposition. */ 104 /* */ 105 /* <Return> */ 106 /* FreeType error code. 0~means success. */ 107 /* */ 108 FT_EXPORT( FT_Error ) 109 FT_Outline_Decompose( FT_Outline* outline, 110 const FT_Outline_Funcs* func_interface, 111 void* user ); 112 113 114 /*************************************************************************/ 115 /* */ 116 /* <Function> */ 117 /* FT_Outline_New */ 118 /* */ 119 /* <Description> */ 120 /* Create a new outline of a given size. */ 121 /* */ 122 /* <Input> */ 123 /* library :: A handle to the library object from where the */ 124 /* outline is allocated. Note however that the new */ 125 /* outline will *not* necessarily be *freed*, when */ 126 /* destroying the library, by @FT_Done_FreeType. */ 127 /* */ 128 /* numPoints :: The maximal number of points within the outline. */ 129 /* */ 130 /* numContours :: The maximal number of contours within the outline. */ 131 /* */ 132 /* <Output> */ 133 /* anoutline :: A handle to the new outline. */ 134 /* */ 135 /* <Return> */ 136 /* FreeType error code. 0~means success. */ 137 /* */ 138 /* <Note> */ 139 /* The reason why this function takes a `library' parameter is simply */ 140 /* to use the library's memory allocator. */ 141 /* */ 142 FT_EXPORT( FT_Error ) 143 FT_Outline_New( FT_Library library, 144 FT_UInt numPoints, 145 FT_Int numContours, 146 FT_Outline *anoutline ); 147 148 149 FT_EXPORT( FT_Error ) 150 FT_Outline_New_Internal( FT_Memory memory, 151 FT_UInt numPoints, 152 FT_Int numContours, 153 FT_Outline *anoutline ); 154 155 156 /*************************************************************************/ 157 /* */ 158 /* <Function> */ 159 /* FT_Outline_Done */ 160 /* */ 161 /* <Description> */ 162 /* Destroy an outline created with @FT_Outline_New. */ 163 /* */ 164 /* <Input> */ 165 /* library :: A handle of the library object used to allocate the */ 166 /* outline. */ 167 /* */ 168 /* outline :: A pointer to the outline object to be discarded. */ 169 /* */ 170 /* <Return> */ 171 /* FreeType error code. 0~means success. */ 172 /* */ 173 /* <Note> */ 174 /* If the outline's `owner' field is not set, only the outline */ 175 /* descriptor will be released. */ 176 /* */ 177 /* The reason why this function takes an `library' parameter is */ 178 /* simply to use ft_mem_free(). */ 179 /* */ 180 FT_EXPORT( FT_Error ) 181 FT_Outline_Done( FT_Library library, 182 FT_Outline* outline ); 183 184 185 FT_EXPORT( FT_Error ) 186 FT_Outline_Done_Internal( FT_Memory memory, 187 FT_Outline* outline ); 188 189 190 /*************************************************************************/ 191 /* */ 192 /* <Function> */ 193 /* FT_Outline_Check */ 194 /* */ 195 /* <Description> */ 196 /* Check the contents of an outline descriptor. */ 197 /* */ 198 /* <Input> */ 199 /* outline :: A handle to a source outline. */ 200 /* */ 201 /* <Return> */ 202 /* FreeType error code. 0~means success. */ 203 /* */ 204 FT_EXPORT( FT_Error ) 205 FT_Outline_Check( FT_Outline* outline ); 206 207 208 /*************************************************************************/ 209 /* */ 210 /* <Function> */ 211 /* FT_Outline_Get_CBox */ 212 /* */ 213 /* <Description> */ 214 /* Return an outline's `control box'. The control box encloses all */ 215 /* the outline's points, including Bézier control points. Though it */ 216 /* coincides with the exact bounding box for most glyphs, it can be */ 217 /* slightly larger in some situations (like when rotating an outline */ 218 /* which contains Bézier outside arcs). */ 219 /* */ 220 /* Computing the control box is very fast, while getting the bounding */ 221 /* box can take much more time as it needs to walk over all segments */ 222 /* and arcs in the outline. To get the latter, you can use the */ 223 /* `ftbbox' component which is dedicated to this single task. */ 224 /* */ 225 /* <Input> */ 226 /* outline :: A pointer to the source outline descriptor. */ 227 /* */ 228 /* <Output> */ 229 /* acbox :: The outline's control box. */ 230 /* */ 231 FT_EXPORT( void ) 232 FT_Outline_Get_CBox( const FT_Outline* outline, 233 FT_BBox *acbox ); 234 235 236 /*************************************************************************/ 237 /* */ 238 /* <Function> */ 239 /* FT_Outline_Translate */ 240 /* */ 241 /* <Description> */ 242 /* Apply a simple translation to the points of an outline. */ 243 /* */ 244 /* <InOut> */ 245 /* outline :: A pointer to the target outline descriptor. */ 246 /* */ 247 /* <Input> */ 248 /* xOffset :: The horizontal offset. */ 249 /* */ 250 /* yOffset :: The vertical offset. */ 251 /* */ 252 FT_EXPORT( void ) 253 FT_Outline_Translate( const FT_Outline* outline, 254 FT_Pos xOffset, 255 FT_Pos yOffset ); 256 257 258 /*************************************************************************/ 259 /* */ 260 /* <Function> */ 261 /* FT_Outline_Copy */ 262 /* */ 263 /* <Description> */ 264 /* Copy an outline into another one. Both objects must have the */ 265 /* same sizes (number of points & number of contours) when this */ 266 /* function is called. */ 267 /* */ 268 /* <Input> */ 269 /* source :: A handle to the source outline. */ 270 /* */ 271 /* <Output> */ 272 /* target :: A handle to the target outline. */ 273 /* */ 274 /* <Return> */ 275 /* FreeType error code. 0~means success. */ 276 /* */ 277 FT_EXPORT( FT_Error ) 278 FT_Outline_Copy( const FT_Outline* source, 279 FT_Outline *target ); 280 281 282 /*************************************************************************/ 283 /* */ 284 /* <Function> */ 285 /* FT_Outline_Transform */ 286 /* */ 287 /* <Description> */ 288 /* Apply a simple 2x2 matrix to all of an outline's points. Useful */ 289 /* for applying rotations, slanting, flipping, etc. */ 290 /* */ 291 /* <InOut> */ 292 /* outline :: A pointer to the target outline descriptor. */ 293 /* */ 294 /* <Input> */ 295 /* matrix :: A pointer to the transformation matrix. */ 296 /* */ 297 /* <Note> */ 298 /* You can use @FT_Outline_Translate if you need to translate the */ 299 /* outline's points. */ 300 /* */ 301 FT_EXPORT( void ) 302 FT_Outline_Transform( const FT_Outline* outline, 303 const FT_Matrix* matrix ); 304 305 306 /*************************************************************************/ 307 /* */ 308 /* <Function> */ 309 /* FT_Outline_Embolden */ 310 /* */ 311 /* <Description> */ 312 /* Embolden an outline. The new outline will be at most 4~times */ 313 /* `strength' pixels wider and higher. You may think of the left and */ 314 /* bottom borders as unchanged. */ 315 /* */ 316 /* Negative `strength' values to reduce the outline thickness are */ 317 /* possible also. */ 318 /* */ 319 /* <InOut> */ 320 /* outline :: A handle to the target outline. */ 321 /* */ 322 /* <Input> */ 323 /* strength :: How strong the glyph is emboldened. Expressed in */ 324 /* 26.6 pixel format. */ 325 /* */ 326 /* <Return> */ 327 /* FreeType error code. 0~means success. */ 328 /* */ 329 /* <Note> */ 330 /* The used algorithm to increase or decrease the thickness of the */ 331 /* glyph doesn't change the number of points; this means that certain */ 332 /* situations like acute angles or intersections are sometimes */ 333 /* handled incorrectly. */ 334 /* */ 335 /* If you need `better' metrics values you should call */ 336 /* @FT_Outline_Get_CBox ot @FT_Outline_Get_BBox. */ 337 /* */ 338 /* Example call: */ 339 /* */ 340 /* { */ 341 /* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); */ 342 /* if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE ) */ 343 /* FT_Outline_Embolden( &face->slot->outline, strength ); */ 344 /* } */ 345 /* */ 346 FT_EXPORT( FT_Error ) 347 FT_Outline_Embolden( FT_Outline* outline, 348 FT_Pos strength ); 349 350 351 /*************************************************************************/ 352 /* */ 353 /* <Function> */ 354 /* FT_Outline_Reverse */ 355 /* */ 356 /* <Description> */ 357 /* Reverse the drawing direction of an outline. This is used to */ 358 /* ensure consistent fill conventions for mirrored glyphs. */ 359 /* */ 360 /* <InOut> */ 361 /* outline :: A pointer to the target outline descriptor. */ 362 /* */ 363 /* <Note> */ 364 /* This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in */ 365 /* the outline's `flags' field. */ 366 /* */ 367 /* It shouldn't be used by a normal client application, unless it */ 368 /* knows what it is doing. */ 369 /* */ 370 FT_EXPORT( void ) 371 FT_Outline_Reverse( FT_Outline* outline ); 372 373 374 /*************************************************************************/ 375 /* */ 376 /* <Function> */ 377 /* FT_Outline_Get_Bitmap */ 378 /* */ 379 /* <Description> */ 380 /* Render an outline within a bitmap. The outline's image is simply */ 381 /* OR-ed to the target bitmap. */ 382 /* */ 383 /* <Input> */ 384 /* library :: A handle to a FreeType library object. */ 385 /* */ 386 /* outline :: A pointer to the source outline descriptor. */ 387 /* */ 388 /* <InOut> */ 389 /* abitmap :: A pointer to the target bitmap descriptor. */ 390 /* */ 391 /* <Return> */ 392 /* FreeType error code. 0~means success. */ 393 /* */ 394 /* <Note> */ 395 /* This function does NOT CREATE the bitmap, it only renders an */ 396 /* outline image within the one you pass to it! Consequently, the */ 397 /* various fields in `abitmap' should be set accordingly. */ 398 /* */ 399 /* It will use the raster corresponding to the default glyph format. */ 400 /* */ 401 /* The value of the `num_grays' field in `abitmap' is ignored. If */ 402 /* you select the gray-level rasterizer, and you want less than 256 */ 403 /* gray levels, you have to use @FT_Outline_Render directly. */ 404 /* */ 405 FT_EXPORT( FT_Error ) 406 FT_Outline_Get_Bitmap( FT_Library library, 407 FT_Outline* outline, 408 const FT_Bitmap *abitmap ); 409 410 411 /*************************************************************************/ 412 /* */ 413 /* <Function> */ 414 /* FT_Outline_Render */ 415 /* */ 416 /* <Description> */ 417 /* Render an outline within a bitmap using the current scan-convert. */ 418 /* This function uses an @FT_Raster_Params structure as an argument, */ 419 /* allowing advanced features like direct composition, translucency, */ 420 /* etc. */ 421 /* */ 422 /* <Input> */ 423 /* library :: A handle to a FreeType library object. */ 424 /* */ 425 /* outline :: A pointer to the source outline descriptor. */ 426 /* */ 427 /* <InOut> */ 428 /* params :: A pointer to an @FT_Raster_Params structure used to */ 429 /* describe the rendering operation. */ 430 /* */ 431 /* <Return> */ 432 /* FreeType error code. 0~means success. */ 433 /* */ 434 /* <Note> */ 435 /* You should know what you are doing and how @FT_Raster_Params works */ 436 /* to use this function. */ 437 /* */ 438 /* The field `params.source' will be set to `outline' before the scan */ 439 /* converter is called, which means that the value you give to it is */ 440 /* actually ignored. */ 441 /* */ 442 /* The gray-level rasterizer always uses 256 gray levels. If you */ 443 /* want less gray levels, you have to provide your own span callback. */ 444 /* See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the */ 445 /* @FT_Raster_Params structure for more details. */ 446 /* */ 447 FT_EXPORT( FT_Error ) 448 FT_Outline_Render( FT_Library library, 449 FT_Outline* outline, 450 FT_Raster_Params* params ); 451 452 453 /************************************************************************** 454 * 455 * @enum: 456 * FT_Orientation 457 * 458 * @description: 459 * A list of values used to describe an outline's contour orientation. 460 * 461 * The TrueType and PostScript specifications use different conventions 462 * to determine whether outline contours should be filled or unfilled. 463 * 464 * @values: 465 * FT_ORIENTATION_TRUETYPE :: 466 * According to the TrueType specification, clockwise contours must 467 * be filled, and counter-clockwise ones must be unfilled. 468 * 469 * FT_ORIENTATION_POSTSCRIPT :: 470 * According to the PostScript specification, counter-clockwise contours 471 * must be filled, and clockwise ones must be unfilled. 472 * 473 * FT_ORIENTATION_FILL_RIGHT :: 474 * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to 475 * remember that in TrueType, everything that is to the right of 476 * the drawing direction of a contour must be filled. 477 * 478 * FT_ORIENTATION_FILL_LEFT :: 479 * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to 480 * remember that in PostScript, everything that is to the left of 481 * the drawing direction of a contour must be filled. 482 * 483 * FT_ORIENTATION_NONE :: 484 * The orientation cannot be determined. That is, different parts of 485 * the glyph have different orientation. 486 * 487 */ 488 typedef enum FT_Orientation_ 489 { 490 FT_ORIENTATION_TRUETYPE = 0, 491 FT_ORIENTATION_POSTSCRIPT = 1, 492 FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE, 493 FT_ORIENTATION_FILL_LEFT = FT_ORIENTATION_POSTSCRIPT, 494 FT_ORIENTATION_NONE 495 496 } FT_Orientation; 497 498 499 /************************************************************************** 500 * 501 * @function: 502 * FT_Outline_Get_Orientation 503 * 504 * @description: 505 * This function analyzes a glyph outline and tries to compute its 506 * fill orientation (see @FT_Orientation). This is done by computing 507 * the direction of each global horizontal and/or vertical extrema 508 * within the outline. 509 * 510 * Note that this will return @FT_ORIENTATION_TRUETYPE for empty 511 * outlines. 512 * 513 * @input: 514 * outline :: 515 * A handle to the source outline. 516 * 517 * @return: 518 * The orientation. 519 * 520 */ 521 FT_EXPORT( FT_Orientation ) 522 FT_Outline_Get_Orientation( FT_Outline* outline ); 523 524 525 /* */ 526 527 528 FT_END_HEADER 529 530 #endif /* __FTOUTLN_H__ */ 531 532 533 /* END */ 534 535 536 /* Local Variables: */ 537 /* coding: utf-8 */ 538 /* End: */ 539