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