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