1 /***************************************************************************/ 2 /* */ 3 /* ftstroke.h */ 4 /* */ 5 /* FreeType path stroker (specification). */ 6 /* */ 7 /* Copyright 2002, 2003, 2004, 2005, 2006, 2008, 2009 by */ 8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 9 /* */ 10 /* This file is part of the FreeType project, and may only be used, */ 11 /* modified, and distributed under the terms of the FreeType project */ 12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 13 /* this file you indicate that you have read the license and */ 14 /* understand and accept it fully. */ 15 /* */ 16 /***************************************************************************/ 17 18 19 #ifndef __FT_STROKE_H__ 20 #define __FT_STROKE_H__ 21 22 #include <ft2build.h> 23 #include FT_OUTLINE_H 24 #include FT_GLYPH_H 25 26 27 FT_BEGIN_HEADER 28 29 30 /************************************************************************ 31 * 32 * @section: 33 * glyph_stroker 34 * 35 * @title: 36 * Glyph Stroker 37 * 38 * @abstract: 39 * Generating bordered and stroked glyphs. 40 * 41 * @description: 42 * This component generates stroked outlines of a given vectorial 43 * glyph. It also allows you to retrieve the `outside' and/or the 44 * `inside' borders of the stroke. 45 * 46 * This can be useful to generate `bordered' glyph, i.e., glyphs 47 * displayed with a coloured (and anti-aliased) border around their 48 * shape. 49 */ 50 51 52 /************************************************************** 53 * 54 * @type: 55 * FT_Stroker 56 * 57 * @description: 58 * Opaque handler to a path stroker object. 59 */ 60 typedef struct FT_StrokerRec_* FT_Stroker; 61 62 63 /************************************************************** 64 * 65 * @enum: 66 * FT_Stroker_LineJoin 67 * 68 * @description: 69 * These values determine how two joining lines are rendered 70 * in a stroker. 71 * 72 * @values: 73 * FT_STROKER_LINEJOIN_ROUND :: 74 * Used to render rounded line joins. Circular arcs are used 75 * to join two lines smoothly. 76 * 77 * FT_STROKER_LINEJOIN_BEVEL :: 78 * Used to render beveled line joins; i.e., the two joining lines 79 * are extended until they intersect. 80 * 81 * FT_STROKER_LINEJOIN_MITER :: 82 * Same as beveled rendering, except that an additional line 83 * break is added if the angle between the two joining lines 84 * is too closed (this is useful to avoid unpleasant spikes 85 * in beveled rendering). 86 */ 87 typedef enum FT_Stroker_LineJoin_ 88 { 89 FT_STROKER_LINEJOIN_ROUND = 0, 90 FT_STROKER_LINEJOIN_BEVEL, 91 FT_STROKER_LINEJOIN_MITER 92 93 } FT_Stroker_LineJoin; 94 95 96 /************************************************************** 97 * 98 * @enum: 99 * FT_Stroker_LineCap 100 * 101 * @description: 102 * These values determine how the end of opened sub-paths are 103 * rendered in a stroke. 104 * 105 * @values: 106 * FT_STROKER_LINECAP_BUTT :: 107 * The end of lines is rendered as a full stop on the last 108 * point itself. 109 * 110 * FT_STROKER_LINECAP_ROUND :: 111 * The end of lines is rendered as a half-circle around the 112 * last point. 113 * 114 * FT_STROKER_LINECAP_SQUARE :: 115 * The end of lines is rendered as a square around the 116 * last point. 117 */ 118 typedef enum FT_Stroker_LineCap_ 119 { 120 FT_STROKER_LINECAP_BUTT = 0, 121 FT_STROKER_LINECAP_ROUND, 122 FT_STROKER_LINECAP_SQUARE 123 124 } FT_Stroker_LineCap; 125 126 127 /************************************************************** 128 * 129 * @enum: 130 * FT_StrokerBorder 131 * 132 * @description: 133 * These values are used to select a given stroke border 134 * in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder. 135 * 136 * @values: 137 * FT_STROKER_BORDER_LEFT :: 138 * Select the left border, relative to the drawing direction. 139 * 140 * FT_STROKER_BORDER_RIGHT :: 141 * Select the right border, relative to the drawing direction. 142 * 143 * @note: 144 * Applications are generally interested in the `inside' and `outside' 145 * borders. However, there is no direct mapping between these and the 146 * `left' and `right' ones, since this really depends on the glyph's 147 * drawing orientation, which varies between font formats. 148 * 149 * You can however use @FT_Outline_GetInsideBorder and 150 * @FT_Outline_GetOutsideBorder to get these. 151 */ 152 typedef enum FT_StrokerBorder_ 153 { 154 FT_STROKER_BORDER_LEFT = 0, 155 FT_STROKER_BORDER_RIGHT 156 157 } FT_StrokerBorder; 158 159 160 /************************************************************** 161 * 162 * @function: 163 * FT_Outline_GetInsideBorder 164 * 165 * @description: 166 * Retrieve the @FT_StrokerBorder value corresponding to the 167 * `inside' borders of a given outline. 168 * 169 * @input: 170 * outline :: 171 * The source outline handle. 172 * 173 * @return: 174 * The border index. @FT_STROKER_BORDER_RIGHT for empty or invalid 175 * outlines. 176 */ 177 FT_EXPORT( FT_StrokerBorder ) 178 FT_Outline_GetInsideBorder( FT_Outline* outline ); 179 180 181 /************************************************************** 182 * 183 * @function: 184 * FT_Outline_GetOutsideBorder 185 * 186 * @description: 187 * Retrieve the @FT_StrokerBorder value corresponding to the 188 * `outside' borders of a given outline. 189 * 190 * @input: 191 * outline :: 192 * The source outline handle. 193 * 194 * @return: 195 * The border index. @FT_STROKER_BORDER_LEFT for empty or invalid 196 * outlines. 197 */ 198 FT_EXPORT( FT_StrokerBorder ) 199 FT_Outline_GetOutsideBorder( FT_Outline* outline ); 200 201 202 /************************************************************** 203 * 204 * @function: 205 * FT_Stroker_New 206 * 207 * @description: 208 * Create a new stroker object. 209 * 210 * @input: 211 * library :: 212 * FreeType library handle. 213 * 214 * @output: 215 * astroker :: 216 * A new stroker object handle. NULL in case of error. 217 * 218 * @return: 219 * FreeType error code. 0~means success. 220 */ 221 FT_EXPORT( FT_Error ) 222 FT_Stroker_New( FT_Library library, 223 FT_Stroker *astroker ); 224 225 226 /************************************************************** 227 * 228 * @function: 229 * FT_Stroker_Set 230 * 231 * @description: 232 * Reset a stroker object's attributes. 233 * 234 * @input: 235 * stroker :: 236 * The target stroker handle. 237 * 238 * radius :: 239 * The border radius. 240 * 241 * line_cap :: 242 * The line cap style. 243 * 244 * line_join :: 245 * The line join style. 246 * 247 * miter_limit :: 248 * The miter limit for the FT_STROKER_LINEJOIN_MITER style, 249 * expressed as 16.16 fixed point value. 250 * 251 * @note: 252 * The radius is expressed in the same units as the outline 253 * coordinates. 254 */ 255 FT_EXPORT( void ) 256 FT_Stroker_Set( FT_Stroker stroker, 257 FT_Fixed radius, 258 FT_Stroker_LineCap line_cap, 259 FT_Stroker_LineJoin line_join, 260 FT_Fixed miter_limit ); 261 262 263 /************************************************************** 264 * 265 * @function: 266 * FT_Stroker_Rewind 267 * 268 * @description: 269 * Reset a stroker object without changing its attributes. 270 * You should call this function before beginning a new 271 * series of calls to @FT_Stroker_BeginSubPath or 272 * @FT_Stroker_EndSubPath. 273 * 274 * @input: 275 * stroker :: 276 * The target stroker handle. 277 */ 278 FT_EXPORT( void ) 279 FT_Stroker_Rewind( FT_Stroker stroker ); 280 281 282 /************************************************************** 283 * 284 * @function: 285 * FT_Stroker_ParseOutline 286 * 287 * @description: 288 * A convenience function used to parse a whole outline with 289 * the stroker. The resulting outline(s) can be retrieved 290 * later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export. 291 * 292 * @input: 293 * stroker :: 294 * The target stroker handle. 295 * 296 * outline :: 297 * The source outline. 298 * 299 * opened :: 300 * A boolean. If~1, the outline is treated as an open path instead 301 * of a closed one. 302 * 303 * @return: 304 * FreeType error code. 0~means success. 305 * 306 * @note: 307 * If `opened' is~0 (the default), the outline is treated as a closed 308 * path, and the stroker generates two distinct `border' outlines. 309 * 310 * If `opened' is~1, the outline is processed as an open path, and the 311 * stroker generates a single `stroke' outline. 312 * 313 * This function calls @FT_Stroker_Rewind automatically. 314 */ 315 FT_EXPORT( FT_Error ) 316 FT_Stroker_ParseOutline( FT_Stroker stroker, 317 FT_Outline* outline, 318 FT_Bool opened ); 319 320 321 /************************************************************** 322 * 323 * @function: 324 * FT_Stroker_BeginSubPath 325 * 326 * @description: 327 * Start a new sub-path in the stroker. 328 * 329 * @input: 330 * stroker :: 331 * The target stroker handle. 332 * 333 * to :: 334 * A pointer to the start vector. 335 * 336 * open :: 337 * A boolean. If~1, the sub-path is treated as an open one. 338 * 339 * @return: 340 * FreeType error code. 0~means success. 341 * 342 * @note: 343 * This function is useful when you need to stroke a path that is 344 * not stored as an @FT_Outline object. 345 */ 346 FT_EXPORT( FT_Error ) 347 FT_Stroker_BeginSubPath( FT_Stroker stroker, 348 FT_Vector* to, 349 FT_Bool open ); 350 351 352 /************************************************************** 353 * 354 * @function: 355 * FT_Stroker_EndSubPath 356 * 357 * @description: 358 * Close the current sub-path in the stroker. 359 * 360 * @input: 361 * stroker :: 362 * The target stroker handle. 363 * 364 * @return: 365 * FreeType error code. 0~means success. 366 * 367 * @note: 368 * You should call this function after @FT_Stroker_BeginSubPath. 369 * If the subpath was not `opened', this function `draws' a 370 * single line segment to the start position when needed. 371 */ 372 FT_EXPORT( FT_Error ) 373 FT_Stroker_EndSubPath( FT_Stroker stroker ); 374 375 376 /************************************************************** 377 * 378 * @function: 379 * FT_Stroker_LineTo 380 * 381 * @description: 382 * `Draw' a single line segment in the stroker's current sub-path, 383 * from the last position. 384 * 385 * @input: 386 * stroker :: 387 * The target stroker handle. 388 * 389 * to :: 390 * A pointer to the destination point. 391 * 392 * @return: 393 * FreeType error code. 0~means success. 394 * 395 * @note: 396 * You should call this function between @FT_Stroker_BeginSubPath and 397 * @FT_Stroker_EndSubPath. 398 */ 399 FT_EXPORT( FT_Error ) 400 FT_Stroker_LineTo( FT_Stroker stroker, 401 FT_Vector* to ); 402 403 404 /************************************************************** 405 * 406 * @function: 407 * FT_Stroker_ConicTo 408 * 409 * @description: 410 * `Draw' a single quadratic Bezier in the stroker's current sub-path, 411 * from the last position. 412 * 413 * @input: 414 * stroker :: 415 * The target stroker handle. 416 * 417 * control :: 418 * A pointer to a Bezier control point. 419 * 420 * to :: 421 * A pointer to the destination point. 422 * 423 * @return: 424 * FreeType error code. 0~means success. 425 * 426 * @note: 427 * You should call this function between @FT_Stroker_BeginSubPath and 428 * @FT_Stroker_EndSubPath. 429 */ 430 FT_EXPORT( FT_Error ) 431 FT_Stroker_ConicTo( FT_Stroker stroker, 432 FT_Vector* control, 433 FT_Vector* to ); 434 435 436 /************************************************************** 437 * 438 * @function: 439 * FT_Stroker_CubicTo 440 * 441 * @description: 442 * `Draw' a single cubic Bezier in the stroker's current sub-path, 443 * from the last position. 444 * 445 * @input: 446 * stroker :: 447 * The target stroker handle. 448 * 449 * control1 :: 450 * A pointer to the first Bezier control point. 451 * 452 * control2 :: 453 * A pointer to second Bezier control point. 454 * 455 * to :: 456 * A pointer to the destination point. 457 * 458 * @return: 459 * FreeType error code. 0~means success. 460 * 461 * @note: 462 * You should call this function between @FT_Stroker_BeginSubPath and 463 * @FT_Stroker_EndSubPath. 464 */ 465 FT_EXPORT( FT_Error ) 466 FT_Stroker_CubicTo( FT_Stroker stroker, 467 FT_Vector* control1, 468 FT_Vector* control2, 469 FT_Vector* to ); 470 471 472 /************************************************************** 473 * 474 * @function: 475 * FT_Stroker_GetBorderCounts 476 * 477 * @description: 478 * Call this function once you have finished parsing your paths 479 * with the stroker. It returns the number of points and 480 * contours necessary to export one of the `border' or `stroke' 481 * outlines generated by the stroker. 482 * 483 * @input: 484 * stroker :: 485 * The target stroker handle. 486 * 487 * border :: 488 * The border index. 489 * 490 * @output: 491 * anum_points :: 492 * The number of points. 493 * 494 * anum_contours :: 495 * The number of contours. 496 * 497 * @return: 498 * FreeType error code. 0~means success. 499 * 500 * @note: 501 * When an outline, or a sub-path, is `closed', the stroker generates 502 * two independent `border' outlines, named `left' and `right'. 503 * 504 * When the outline, or a sub-path, is `opened', the stroker merges 505 * the `border' outlines with caps. The `left' border receives all 506 * points, while the `right' border becomes empty. 507 * 508 * Use the function @FT_Stroker_GetCounts instead if you want to 509 * retrieve the counts associated to both borders. 510 */ 511 FT_EXPORT( FT_Error ) 512 FT_Stroker_GetBorderCounts( FT_Stroker stroker, 513 FT_StrokerBorder border, 514 FT_UInt *anum_points, 515 FT_UInt *anum_contours ); 516 517 518 /************************************************************** 519 * 520 * @function: 521 * FT_Stroker_ExportBorder 522 * 523 * @description: 524 * Call this function after @FT_Stroker_GetBorderCounts to 525 * export the corresponding border to your own @FT_Outline 526 * structure. 527 * 528 * Note that this function appends the border points and 529 * contours to your outline, but does not try to resize its 530 * arrays. 531 * 532 * @input: 533 * stroker :: 534 * The target stroker handle. 535 * 536 * border :: 537 * The border index. 538 * 539 * outline :: 540 * The target outline handle. 541 * 542 * @note: 543 * Always call this function after @FT_Stroker_GetBorderCounts to 544 * get sure that there is enough room in your @FT_Outline object to 545 * receive all new data. 546 * 547 * When an outline, or a sub-path, is `closed', the stroker generates 548 * two independent `border' outlines, named `left' and `right' 549 * 550 * When the outline, or a sub-path, is `opened', the stroker merges 551 * the `border' outlines with caps. The `left' border receives all 552 * points, while the `right' border becomes empty. 553 * 554 * Use the function @FT_Stroker_Export instead if you want to 555 * retrieve all borders at once. 556 */ 557 FT_EXPORT( void ) 558 FT_Stroker_ExportBorder( FT_Stroker stroker, 559 FT_StrokerBorder border, 560 FT_Outline* outline ); 561 562 563 /************************************************************** 564 * 565 * @function: 566 * FT_Stroker_GetCounts 567 * 568 * @description: 569 * Call this function once you have finished parsing your paths 570 * with the stroker. It returns the number of points and 571 * contours necessary to export all points/borders from the stroked 572 * outline/path. 573 * 574 * @input: 575 * stroker :: 576 * The target stroker handle. 577 * 578 * @output: 579 * anum_points :: 580 * The number of points. 581 * 582 * anum_contours :: 583 * The number of contours. 584 * 585 * @return: 586 * FreeType error code. 0~means success. 587 */ 588 FT_EXPORT( FT_Error ) 589 FT_Stroker_GetCounts( FT_Stroker stroker, 590 FT_UInt *anum_points, 591 FT_UInt *anum_contours ); 592 593 594 /************************************************************** 595 * 596 * @function: 597 * FT_Stroker_Export 598 * 599 * @description: 600 * Call this function after @FT_Stroker_GetBorderCounts to 601 * export the all borders to your own @FT_Outline structure. 602 * 603 * Note that this function appends the border points and 604 * contours to your outline, but does not try to resize its 605 * arrays. 606 * 607 * @input: 608 * stroker :: 609 * The target stroker handle. 610 * 611 * outline :: 612 * The target outline handle. 613 */ 614 FT_EXPORT( void ) 615 FT_Stroker_Export( FT_Stroker stroker, 616 FT_Outline* outline ); 617 618 619 /************************************************************** 620 * 621 * @function: 622 * FT_Stroker_Done 623 * 624 * @description: 625 * Destroy a stroker object. 626 * 627 * @input: 628 * stroker :: 629 * A stroker handle. Can be NULL. 630 */ 631 FT_EXPORT( void ) 632 FT_Stroker_Done( FT_Stroker stroker ); 633 634 635 /************************************************************** 636 * 637 * @function: 638 * FT_Glyph_Stroke 639 * 640 * @description: 641 * Stroke a given outline glyph object with a given stroker. 642 * 643 * @inout: 644 * pglyph :: 645 * Source glyph handle on input, new glyph handle on output. 646 * 647 * @input: 648 * stroker :: 649 * A stroker handle. 650 * 651 * destroy :: 652 * A Boolean. If~1, the source glyph object is destroyed 653 * on success. 654 * 655 * @return: 656 * FreeType error code. 0~means success. 657 * 658 * @note: 659 * The source glyph is untouched in case of error. 660 */ 661 FT_EXPORT( FT_Error ) 662 FT_Glyph_Stroke( FT_Glyph *pglyph, 663 FT_Stroker stroker, 664 FT_Bool destroy ); 665 666 667 /************************************************************** 668 * 669 * @function: 670 * FT_Glyph_StrokeBorder 671 * 672 * @description: 673 * Stroke a given outline glyph object with a given stroker, but 674 * only return either its inside or outside border. 675 * 676 * @inout: 677 * pglyph :: 678 * Source glyph handle on input, new glyph handle on output. 679 * 680 * @input: 681 * stroker :: 682 * A stroker handle. 683 * 684 * inside :: 685 * A Boolean. If~1, return the inside border, otherwise 686 * the outside border. 687 * 688 * destroy :: 689 * A Boolean. If~1, the source glyph object is destroyed 690 * on success. 691 * 692 * @return: 693 * FreeType error code. 0~means success. 694 * 695 * @note: 696 * The source glyph is untouched in case of error. 697 */ 698 FT_EXPORT( FT_Error ) 699 FT_Glyph_StrokeBorder( FT_Glyph *pglyph, 700 FT_Stroker stroker, 701 FT_Bool inside, 702 FT_Bool destroy ); 703 704 /* */ 705 706 FT_END_HEADER 707 708 #endif /* __FT_STROKE_H__ */ 709 710 711 /* END */ 712 713 714 /* Local Variables: */ 715 /* coding: utf-8 */ 716 /* End: */ 717