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-2003, 2005-2012 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 "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_EmboldenXY */ 63 /* FT_Outline_Reverse */ 64 /* FT_Outline_Check */ 65 /* */ 66 /* FT_Outline_Get_CBox */ 67 /* FT_Outline_Get_BBox */ 68 /* */ 69 /* FT_Outline_Get_Bitmap */ 70 /* FT_Outline_Render */ 71 /* */ 72 /* FT_Outline_Decompose */ 73 /* FT_Outline_Funcs */ 74 /* FT_Outline_MoveTo_Func */ 75 /* FT_Outline_LineTo_Func */ 76 /* FT_Outline_ConicTo_Func */ 77 /* FT_Outline_CubicTo_Func */ 78 /* */ 79 /*************************************************************************/ 80 81 82 /*************************************************************************/ 83 /* */ 84 /* <Function> */ 85 /* FT_Outline_Decompose */ 86 /* */ 87 /* <Description> */ 88 /* Walk over an outline's structure to decompose it into individual */ 89 /* segments and Bzier arcs. This function also emits `move to' */ 90 /* operations to indicate the start 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 maximum number of points within the outline. */ 129 /* Must be smaller than or equal to 0xFFFF (65535). */ 130 /* */ 131 /* numContours :: The maximum number of contours within the outline. */ 132 /* This value must be in the range 0 to `numPoints'. */ 133 /* */ 134 /* <Output> */ 135 /* anoutline :: A handle to the new outline. */ 136 /* */ 137 /* <Return> */ 138 /* FreeType error code. 0~means success. */ 139 /* */ 140 /* <Note> */ 141 /* The reason why this function takes a `library' parameter is simply */ 142 /* to use the library's memory allocator. */ 143 /* */ 144 FT_EXPORT( FT_Error ) 145 FT_Outline_New( FT_Library library, 146 FT_UInt numPoints, 147 FT_Int numContours, 148 FT_Outline *anoutline ); 149 150 151 FT_EXPORT( FT_Error ) 152 FT_Outline_New_Internal( FT_Memory memory, 153 FT_UInt numPoints, 154 FT_Int numContours, 155 FT_Outline *anoutline ); 156 157 158 /*************************************************************************/ 159 /* */ 160 /* <Function> */ 161 /* FT_Outline_Done */ 162 /* */ 163 /* <Description> */ 164 /* Destroy an outline created with @FT_Outline_New. */ 165 /* */ 166 /* <Input> */ 167 /* library :: A handle of the library object used to allocate the */ 168 /* outline. */ 169 /* */ 170 /* outline :: A pointer to the outline object to be discarded. */ 171 /* */ 172 /* <Return> */ 173 /* FreeType error code. 0~means success. */ 174 /* */ 175 /* <Note> */ 176 /* If the outline's `owner' field is not set, only the outline */ 177 /* descriptor will be released. */ 178 /* */ 179 /* The reason why this function takes an `library' parameter is */ 180 /* simply to use ft_mem_free(). */ 181 /* */ 182 FT_EXPORT( FT_Error ) 183 FT_Outline_Done( FT_Library library, 184 FT_Outline* outline ); 185 186 187 FT_EXPORT( FT_Error ) 188 FT_Outline_Done_Internal( FT_Memory memory, 189 FT_Outline* outline ); 190 191 192 /*************************************************************************/ 193 /* */ 194 /* <Function> */ 195 /* FT_Outline_Check */ 196 /* */ 197 /* <Description> */ 198 /* Check the contents of an outline descriptor. */ 199 /* */ 200 /* <Input> */ 201 /* outline :: A handle to a source outline. */ 202 /* */ 203 /* <Return> */ 204 /* FreeType error code. 0~means success. */ 205 /* */ 206 FT_EXPORT( FT_Error ) 207 FT_Outline_Check( FT_Outline* outline ); 208 209 210 /*************************************************************************/ 211 /* */ 212 /* <Function> */ 213 /* FT_Outline_Get_CBox */ 214 /* */ 215 /* <Description> */ 216 /* Return an outline's `control box'. The control box encloses all */ 217 /* the outline's points, including Bzier control points. Though it */ 218 /* coincides with the exact bounding box for most glyphs, it can be */ 219 /* slightly larger in some situations (like when rotating an outline */ 220 /* which contains Bzier outside arcs). */ 221 /* */ 222 /* Computing the control box is very fast, while getting the bounding */ 223 /* box can take much more time as it needs to walk over all segments */ 224 /* and arcs in the outline. To get the latter, you can use the */ 225 /* `ftbbox' component which is dedicated to this single task. */ 226 /* */ 227 /* <Input> */ 228 /* outline :: A pointer to the source outline descriptor. */ 229 /* */ 230 /* <Output> */ 231 /* acbox :: The outline's control box. */ 232 /* */ 233 /* <Note> */ 234 /* See @FT_Glyph_Get_CBox for a discussion of tricky fonts. */ 235 /* */ 236 FT_EXPORT( void ) 237 FT_Outline_Get_CBox( const FT_Outline* outline, 238 FT_BBox *acbox ); 239 240 241 /*************************************************************************/ 242 /* */ 243 /* <Function> */ 244 /* FT_Outline_Translate */ 245 /* */ 246 /* <Description> */ 247 /* Apply a simple translation to the points of an outline. */ 248 /* */ 249 /* <InOut> */ 250 /* outline :: A pointer to the target outline descriptor. */ 251 /* */ 252 /* <Input> */ 253 /* xOffset :: The horizontal offset. */ 254 /* */ 255 /* yOffset :: The vertical offset. */ 256 /* */ 257 FT_EXPORT( void ) 258 FT_Outline_Translate( const FT_Outline* outline, 259 FT_Pos xOffset, 260 FT_Pos yOffset ); 261 262 263 /*************************************************************************/ 264 /* */ 265 /* <Function> */ 266 /* FT_Outline_Copy */ 267 /* */ 268 /* <Description> */ 269 /* Copy an outline into another one. Both objects must have the */ 270 /* same sizes (number of points & number of contours) when this */ 271 /* function is called. */ 272 /* */ 273 /* <Input> */ 274 /* source :: A handle to the source outline. */ 275 /* */ 276 /* <Output> */ 277 /* target :: A handle to the target outline. */ 278 /* */ 279 /* <Return> */ 280 /* FreeType error code. 0~means success. */ 281 /* */ 282 FT_EXPORT( FT_Error ) 283 FT_Outline_Copy( const FT_Outline* source, 284 FT_Outline *target ); 285 286 287 /*************************************************************************/ 288 /* */ 289 /* <Function> */ 290 /* FT_Outline_Transform */ 291 /* */ 292 /* <Description> */ 293 /* Apply a simple 2x2 matrix to all of an outline's points. Useful */ 294 /* for applying rotations, slanting, flipping, etc. */ 295 /* */ 296 /* <InOut> */ 297 /* outline :: A pointer to the target outline descriptor. */ 298 /* */ 299 /* <Input> */ 300 /* matrix :: A pointer to the transformation matrix. */ 301 /* */ 302 /* <Note> */ 303 /* You can use @FT_Outline_Translate if you need to translate the */ 304 /* outline's points. */ 305 /* */ 306 FT_EXPORT( void ) 307 FT_Outline_Transform( const FT_Outline* outline, 308 const FT_Matrix* matrix ); 309 310 311 /*************************************************************************/ 312 /* */ 313 /* <Function> */ 314 /* FT_Outline_Embolden */ 315 /* */ 316 /* <Description> */ 317 /* Embolden an outline. The new outline will be at most 4~times */ 318 /* `strength' pixels wider and higher. You may think of the left and */ 319 /* bottom borders as unchanged. */ 320 /* */ 321 /* Negative `strength' values to reduce the outline thickness are */ 322 /* possible also. */ 323 /* */ 324 /* <InOut> */ 325 /* outline :: A handle to the target outline. */ 326 /* */ 327 /* <Input> */ 328 /* strength :: How strong the glyph is emboldened. Expressed in */ 329 /* 26.6 pixel format. */ 330 /* */ 331 /* <Return> */ 332 /* FreeType error code. 0~means success. */ 333 /* */ 334 /* <Note> */ 335 /* The used algorithm to increase or decrease the thickness of the */ 336 /* glyph doesn't change the number of points; this means that certain */ 337 /* situations like acute angles or intersections are sometimes */ 338 /* handled incorrectly. */ 339 /* */ 340 /* If you need `better' metrics values you should call */ 341 /* @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. */ 342 /* */ 343 /* Example call: */ 344 /* */ 345 /* { */ 346 /* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); */ 347 /* if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE ) */ 348 /* FT_Outline_Embolden( &face->slot->outline, strength ); */ 349 /* } */ 350 /* */ 351 FT_EXPORT( FT_Error ) 352 FT_Outline_Embolden( FT_Outline* outline, 353 FT_Pos strength ); 354 355 356 /*************************************************************************/ 357 /* */ 358 /* <Function> */ 359 /* FT_Outline_EmboldenXY */ 360 /* */ 361 /* <Description> */ 362 /* Embolden an outline. The new outline will be `xstrength' pixels */ 363 /* wider and `ystrength' pixels higher. Otherwise, it is similar to */ 364 /* @FT_Outline_Embolden, which uses the same strength in both */ 365 /* directions. */ 366 /* */ 367 FT_EXPORT( FT_Error ) 368 FT_Outline_EmboldenXY( FT_Outline* outline, 369 FT_Pos xstrength, 370 FT_Pos ystrength ); 371 372 373 /*************************************************************************/ 374 /* */ 375 /* <Function> */ 376 /* FT_Outline_Reverse */ 377 /* */ 378 /* <Description> */ 379 /* Reverse the drawing direction of an outline. This is used to */ 380 /* ensure consistent fill conventions for mirrored glyphs. */ 381 /* */ 382 /* <InOut> */ 383 /* outline :: A pointer to the target outline descriptor. */ 384 /* */ 385 /* <Note> */ 386 /* This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in */ 387 /* the outline's `flags' field. */ 388 /* */ 389 /* It shouldn't be used by a normal client application, unless it */ 390 /* knows what it is doing. */ 391 /* */ 392 FT_EXPORT( void ) 393 FT_Outline_Reverse( FT_Outline* outline ); 394 395 396 /*************************************************************************/ 397 /* */ 398 /* <Function> */ 399 /* FT_Outline_Get_Bitmap */ 400 /* */ 401 /* <Description> */ 402 /* Render an outline within a bitmap. The outline's image is simply */ 403 /* OR-ed to the target bitmap. */ 404 /* */ 405 /* <Input> */ 406 /* library :: A handle to a FreeType library object. */ 407 /* */ 408 /* outline :: A pointer to the source outline descriptor. */ 409 /* */ 410 /* <InOut> */ 411 /* abitmap :: A pointer to the target bitmap descriptor. */ 412 /* */ 413 /* <Return> */ 414 /* FreeType error code. 0~means success. */ 415 /* */ 416 /* <Note> */ 417 /* This function does NOT CREATE the bitmap, it only renders an */ 418 /* outline image within the one you pass to it! Consequently, the */ 419 /* various fields in `abitmap' should be set accordingly. */ 420 /* */ 421 /* It will use the raster corresponding to the default glyph format. */ 422 /* */ 423 /* The value of the `num_grays' field in `abitmap' is ignored. If */ 424 /* you select the gray-level rasterizer, and you want less than 256 */ 425 /* gray levels, you have to use @FT_Outline_Render directly. */ 426 /* */ 427 FT_EXPORT( FT_Error ) 428 FT_Outline_Get_Bitmap( FT_Library library, 429 FT_Outline* outline, 430 const FT_Bitmap *abitmap ); 431 432 433 /*************************************************************************/ 434 /* */ 435 /* <Function> */ 436 /* FT_Outline_Render */ 437 /* */ 438 /* <Description> */ 439 /* Render an outline within a bitmap using the current scan-convert. */ 440 /* This function uses an @FT_Raster_Params structure as an argument, */ 441 /* allowing advanced features like direct composition, translucency, */ 442 /* etc. */ 443 /* */ 444 /* <Input> */ 445 /* library :: A handle to a FreeType library object. */ 446 /* */ 447 /* outline :: A pointer to the source outline descriptor. */ 448 /* */ 449 /* <InOut> */ 450 /* params :: A pointer to an @FT_Raster_Params structure used to */ 451 /* describe the rendering operation. */ 452 /* */ 453 /* <Return> */ 454 /* FreeType error code. 0~means success. */ 455 /* */ 456 /* <Note> */ 457 /* You should know what you are doing and how @FT_Raster_Params works */ 458 /* to use this function. */ 459 /* */ 460 /* The field `params.source' will be set to `outline' before the scan */ 461 /* converter is called, which means that the value you give to it is */ 462 /* actually ignored. */ 463 /* */ 464 /* The gray-level rasterizer always uses 256 gray levels. If you */ 465 /* want less gray levels, you have to provide your own span callback. */ 466 /* See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the */ 467 /* @FT_Raster_Params structure for more details. */ 468 /* */ 469 FT_EXPORT( FT_Error ) 470 FT_Outline_Render( FT_Library library, 471 FT_Outline* outline, 472 FT_Raster_Params* params ); 473 474 475 /************************************************************************** 476 * 477 * @enum: 478 * FT_Orientation 479 * 480 * @description: 481 * A list of values used to describe an outline's contour orientation. 482 * 483 * The TrueType and PostScript specifications use different conventions 484 * to determine whether outline contours should be filled or unfilled. 485 * 486 * @values: 487 * FT_ORIENTATION_TRUETYPE :: 488 * According to the TrueType specification, clockwise contours must 489 * be filled, and counter-clockwise ones must be unfilled. 490 * 491 * FT_ORIENTATION_POSTSCRIPT :: 492 * According to the PostScript specification, counter-clockwise contours 493 * must be filled, and clockwise ones must be unfilled. 494 * 495 * FT_ORIENTATION_FILL_RIGHT :: 496 * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to 497 * remember that in TrueType, everything that is to the right of 498 * the drawing direction of a contour must be filled. 499 * 500 * FT_ORIENTATION_FILL_LEFT :: 501 * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to 502 * remember that in PostScript, everything that is to the left of 503 * the drawing direction of a contour must be filled. 504 * 505 * FT_ORIENTATION_NONE :: 506 * The orientation cannot be determined. That is, different parts of 507 * the glyph have different orientation. 508 * 509 */ 510 typedef enum FT_Orientation_ 511 { 512 FT_ORIENTATION_TRUETYPE = 0, 513 FT_ORIENTATION_POSTSCRIPT = 1, 514 FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE, 515 FT_ORIENTATION_FILL_LEFT = FT_ORIENTATION_POSTSCRIPT, 516 FT_ORIENTATION_NONE 517 518 } FT_Orientation; 519 520 521 /************************************************************************** 522 * 523 * @function: 524 * FT_Outline_Get_Orientation 525 * 526 * @description: 527 * This function analyzes a glyph outline and tries to compute its 528 * fill orientation (see @FT_Orientation). This is done by computing 529 * the direction of each global horizontal and/or vertical extrema 530 * within the outline. 531 * 532 * Note that this will return @FT_ORIENTATION_TRUETYPE for empty 533 * outlines. 534 * 535 * @input: 536 * outline :: 537 * A handle to the source outline. 538 * 539 * @return: 540 * The orientation. 541 * 542 */ 543 FT_EXPORT( FT_Orientation ) 544 FT_Outline_Get_Orientation( FT_Outline* outline ); 545 546 547 /* */ 548 549 550 FT_END_HEADER 551 552 #endif /* __FTOUTLN_H__ */ 553 554 555 /* END */ 556 557 558 /* Local Variables: */ 559 /* coding: utf-8 */ 560 /* End: */ 561
