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