1 /**************************************************************************** 2 * 3 * ftimage.h 4 * 5 * FreeType glyph image formats and default raster interface 6 * (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 * 21 * Note: A `raster' is simply a scan-line converter, used to render 22 * FT_Outlines into FT_Bitmaps. 23 * 24 */ 25 26 27 #ifndef FTIMAGE_H_ 28 #define FTIMAGE_H_ 29 30 31 /* STANDALONE_ is from ftgrays.c */ 32 #ifndef STANDALONE_ 33 #include <ft2build.h> 34 #endif 35 36 37 FT_BEGIN_HEADER 38 39 40 /************************************************************************** 41 * 42 * @section: 43 * basic_types 44 * 45 */ 46 47 48 /************************************************************************** 49 * 50 * @type: 51 * FT_Pos 52 * 53 * @description: 54 * The type FT_Pos is used to store vectorial coordinates. Depending 55 * on the context, these can represent distances in integer font 56 * units, or 16.16, or 26.6 fixed-point pixel coordinates. 57 */ 58 typedef signed long FT_Pos; 59 60 61 /************************************************************************** 62 * 63 * @struct: 64 * FT_Vector 65 * 66 * @description: 67 * A simple structure used to store a 2D vector; coordinates are of 68 * the FT_Pos type. 69 * 70 * @fields: 71 * x :: 72 * The horizontal coordinate. 73 * y :: 74 * The vertical coordinate. 75 */ 76 typedef struct FT_Vector_ 77 { 78 FT_Pos x; 79 FT_Pos y; 80 81 } FT_Vector; 82 83 84 /************************************************************************** 85 * 86 * @struct: 87 * FT_BBox 88 * 89 * @description: 90 * A structure used to hold an outline's bounding box, i.e., the 91 * coordinates of its extrema in the horizontal and vertical 92 * directions. 93 * 94 * @fields: 95 * xMin :: 96 * The horizontal minimum (left-most). 97 * 98 * yMin :: 99 * The vertical minimum (bottom-most). 100 * 101 * xMax :: 102 * The horizontal maximum (right-most). 103 * 104 * yMax :: 105 * The vertical maximum (top-most). 106 * 107 * @note: 108 * The bounding box is specified with the coordinates of the lower 109 * left and the upper right corner. In PostScript, those values are 110 * often called (llx,lly) and (urx,ury), respectively. 111 * 112 * If `yMin' is negative, this value gives the glyph's descender. 113 * Otherwise, the glyph doesn't descend below the baseline. 114 * Similarly, if `ymax' is positive, this value gives the glyph's 115 * ascender. 116 * 117 * `xMin' gives the horizontal distance from the glyph's origin to 118 * the left edge of the glyph's bounding box. If `xMin' is negative, 119 * the glyph extends to the left of the origin. 120 */ 121 typedef struct FT_BBox_ 122 { 123 FT_Pos xMin, yMin; 124 FT_Pos xMax, yMax; 125 126 } FT_BBox; 127 128 129 /************************************************************************** 130 * 131 * @enum: 132 * FT_Pixel_Mode 133 * 134 * @description: 135 * An enumeration type used to describe the format of pixels in a 136 * given bitmap. Note that additional formats may be added in the 137 * future. 138 * 139 * @values: 140 * FT_PIXEL_MODE_NONE :: 141 * Value~0 is reserved. 142 * 143 * FT_PIXEL_MODE_MONO :: 144 * A monochrome bitmap, using 1~bit per pixel. Note that pixels 145 * are stored in most-significant order (MSB), which means that 146 * the left-most pixel in a byte has value 128. 147 * 148 * FT_PIXEL_MODE_GRAY :: 149 * An 8-bit bitmap, generally used to represent anti-aliased glyph 150 * images. Each pixel is stored in one byte. Note that the number 151 * of `gray' levels is stored in the `num_grays' field of the 152 * @FT_Bitmap structure (it generally is 256). 153 * 154 * FT_PIXEL_MODE_GRAY2 :: 155 * A 2-bit per pixel bitmap, used to represent embedded 156 * anti-aliased bitmaps in font files according to the OpenType 157 * specification. We haven't found a single font using this 158 * format, however. 159 * 160 * FT_PIXEL_MODE_GRAY4 :: 161 * A 4-bit per pixel bitmap, representing embedded anti-aliased 162 * bitmaps in font files according to the OpenType specification. 163 * We haven't found a single font using this format, however. 164 * 165 * FT_PIXEL_MODE_LCD :: 166 * An 8-bit bitmap, representing RGB or BGR decimated glyph images 167 * used for display on LCD displays; the bitmap is three times 168 * wider than the original glyph image. See also 169 * @FT_RENDER_MODE_LCD. 170 * 171 * FT_PIXEL_MODE_LCD_V :: 172 * An 8-bit bitmap, representing RGB or BGR decimated glyph images 173 * used for display on rotated LCD displays; the bitmap is three 174 * times taller than the original glyph image. See also 175 * @FT_RENDER_MODE_LCD_V. 176 * 177 * FT_PIXEL_MODE_BGRA :: 178 * [Since 2.5] An image with four 8-bit channels per pixel, 179 * representing a color image (such as emoticons) with alpha 180 * channel. For each pixel, the format is BGRA, which means, the 181 * blue channel comes first in memory. The color channels are 182 * pre-multiplied and in the sRGB colorspace. For example, full 183 * red at half-translucent opacity will be represented as 184 * `00,00,80,80', not `00,00,FF,80'. See also @FT_LOAD_COLOR. 185 */ 186 typedef enum FT_Pixel_Mode_ 187 { 188 FT_PIXEL_MODE_NONE = 0, 189 FT_PIXEL_MODE_MONO, 190 FT_PIXEL_MODE_GRAY, 191 FT_PIXEL_MODE_GRAY2, 192 FT_PIXEL_MODE_GRAY4, 193 FT_PIXEL_MODE_LCD, 194 FT_PIXEL_MODE_LCD_V, 195 FT_PIXEL_MODE_BGRA, 196 197 FT_PIXEL_MODE_MAX /* do not remove */ 198 199 } FT_Pixel_Mode; 200 201 202 /* these constants are deprecated; use the corresponding `FT_Pixel_Mode' */ 203 /* values instead. */ 204 #define ft_pixel_mode_none FT_PIXEL_MODE_NONE 205 #define ft_pixel_mode_mono FT_PIXEL_MODE_MONO 206 #define ft_pixel_mode_grays FT_PIXEL_MODE_GRAY 207 #define ft_pixel_mode_pal2 FT_PIXEL_MODE_GRAY2 208 #define ft_pixel_mode_pal4 FT_PIXEL_MODE_GRAY4 209 210 211 /************************************************************************** 212 * 213 * @struct: 214 * FT_Bitmap 215 * 216 * @description: 217 * A structure used to describe a bitmap or pixmap to the raster. 218 * Note that we now manage pixmaps of various depths through the 219 * `pixel_mode' field. 220 * 221 * @fields: 222 * rows :: 223 * The number of bitmap rows. 224 * 225 * width :: 226 * The number of pixels in bitmap row. 227 * 228 * pitch :: 229 * The pitch's absolute value is the number of bytes 230 * taken by one bitmap row, including padding. 231 * However, the pitch is positive when the bitmap has 232 * a `down' flow, and negative when it has an `up' 233 * flow. In all cases, the pitch is an offset to add 234 * to a bitmap pointer in order to go down one row. 235 * 236 * Note that `padding' means the alignment of a 237 * bitmap to a byte border, and FreeType functions 238 * normally align to the smallest possible integer 239 * value. 240 * 241 * For the B/W rasterizer, `pitch' is always an even 242 * number. 243 * 244 * To change the pitch of a bitmap (say, to make it a 245 * multiple of 4), use @FT_Bitmap_Convert. 246 * Alternatively, you might use callback functions to 247 * directly render to the application's surface; see 248 * the file `example2.cpp' in the tutorial for a 249 * demonstration. 250 * 251 * buffer :: 252 * A typeless pointer to the bitmap buffer. This 253 * value should be aligned on 32-bit boundaries in 254 * most cases. 255 * 256 * num_grays :: 257 * This field is only used with 258 * @FT_PIXEL_MODE_GRAY; it gives the number of gray 259 * levels used in the bitmap. 260 * 261 * pixel_mode :: 262 * The pixel mode, i.e., how pixel bits are stored. 263 * See @FT_Pixel_Mode for possible values. 264 * 265 * palette_mode :: 266 * This field is intended for paletted pixel modes; 267 * it indicates how the palette is stored. Not 268 * used currently. 269 * 270 * palette :: 271 * A typeless pointer to the bitmap palette; this 272 * field is intended for paletted pixel modes. Not 273 * used currently. 274 */ 275 typedef struct FT_Bitmap_ 276 { 277 unsigned int rows; 278 unsigned int width; 279 int pitch; 280 unsigned char* buffer; 281 unsigned short num_grays; 282 unsigned char pixel_mode; 283 unsigned char palette_mode; 284 void* palette; 285 286 } FT_Bitmap; 287 288 289 /************************************************************************** 290 * 291 * @section: 292 * outline_processing 293 * 294 */ 295 296 297 /************************************************************************** 298 * 299 * @struct: 300 * FT_Outline 301 * 302 * @description: 303 * This structure is used to describe an outline to the scan-line 304 * converter. 305 * 306 * @fields: 307 * n_contours :: 308 * The number of contours in the outline. 309 * 310 * n_points :: 311 * The number of points in the outline. 312 * 313 * points :: 314 * A pointer to an array of `n_points' @FT_Vector 315 * elements, giving the outline's point coordinates. 316 * 317 * tags :: 318 * A pointer to an array of `n_points' chars, giving 319 * each outline point's type. 320 * 321 * If bit~0 is unset, the point is `off' the curve, 322 * i.e., a Bezier control point, while it is `on' if 323 * set. 324 * 325 * Bit~1 is meaningful for `off' points only. If set, 326 * it indicates a third-order Bezier arc control point; 327 * and a second-order control point if unset. 328 * 329 * If bit~2 is set, bits 5-7 contain the drop-out mode 330 * (as defined in the OpenType specification; the value 331 * is the same as the argument to the SCANMODE 332 * instruction). 333 * 334 * Bits 3 and~4 are reserved for internal purposes. 335 * 336 * contours :: 337 * An array of `n_contours' shorts, giving the end 338 * point of each contour within the outline. For 339 * example, the first contour is defined by the points 340 * `0' to `contours[0]', the second one is defined by 341 * the points `contours[0]+1' to `contours[1]', etc. 342 * 343 * flags :: 344 * A set of bit flags used to characterize the outline 345 * and give hints to the scan-converter and hinter on 346 * how to convert/grid-fit it. See @FT_OUTLINE_XXX. 347 * 348 * @note: 349 * The B/W rasterizer only checks bit~2 in the `tags' array for the 350 * first point of each contour. The drop-out mode as given with 351 * @FT_OUTLINE_IGNORE_DROPOUTS, @FT_OUTLINE_SMART_DROPOUTS, and 352 * @FT_OUTLINE_INCLUDE_STUBS in `flags' is then overridden. 353 */ 354 typedef struct FT_Outline_ 355 { 356 short n_contours; /* number of contours in glyph */ 357 short n_points; /* number of points in the glyph */ 358 359 FT_Vector* points; /* the outline's points */ 360 char* tags; /* the points flags */ 361 short* contours; /* the contour end points */ 362 363 int flags; /* outline masks */ 364 365 } FT_Outline; 366 367 /* */ 368 369 /* Following limits must be consistent with */ 370 /* FT_Outline.{n_contours,n_points} */ 371 #define FT_OUTLINE_CONTOURS_MAX SHRT_MAX 372 #define FT_OUTLINE_POINTS_MAX SHRT_MAX 373 374 375 /************************************************************************** 376 * 377 * @enum: 378 * FT_OUTLINE_XXX 379 * 380 * @description: 381 * A list of bit-field constants use for the flags in an outline's 382 * `flags' field. 383 * 384 * @values: 385 * FT_OUTLINE_NONE :: 386 * Value~0 is reserved. 387 * 388 * FT_OUTLINE_OWNER :: 389 * If set, this flag indicates that the outline's field arrays 390 * (i.e., `points', `flags', and `contours') are `owned' by the 391 * outline object, and should thus be freed when it is destroyed. 392 * 393 * FT_OUTLINE_EVEN_ODD_FILL :: 394 * By default, outlines are filled using the non-zero winding rule. 395 * If set to 1, the outline will be filled using the even-odd fill 396 * rule (only works with the smooth rasterizer). 397 * 398 * FT_OUTLINE_REVERSE_FILL :: 399 * By default, outside contours of an outline are oriented in 400 * clock-wise direction, as defined in the TrueType specification. 401 * This flag is set if the outline uses the opposite direction 402 * (typically for Type~1 fonts). This flag is ignored by the scan 403 * converter. 404 * 405 * FT_OUTLINE_IGNORE_DROPOUTS :: 406 * By default, the scan converter will try to detect drop-outs in 407 * an outline and correct the glyph bitmap to ensure consistent 408 * shape continuity. If set, this flag hints the scan-line 409 * converter to ignore such cases. See below for more information. 410 * 411 * FT_OUTLINE_SMART_DROPOUTS :: 412 * Select smart dropout control. If unset, use simple dropout 413 * control. Ignored if @FT_OUTLINE_IGNORE_DROPOUTS is set. See 414 * below for more information. 415 * 416 * FT_OUTLINE_INCLUDE_STUBS :: 417 * If set, turn pixels on for `stubs', otherwise exclude them. 418 * Ignored if @FT_OUTLINE_IGNORE_DROPOUTS is set. See below for 419 * more information. 420 * 421 * FT_OUTLINE_HIGH_PRECISION :: 422 * This flag indicates that the scan-line converter should try to 423 * convert this outline to bitmaps with the highest possible 424 * quality. It is typically set for small character sizes. Note 425 * that this is only a hint that might be completely ignored by a 426 * given scan-converter. 427 * 428 * FT_OUTLINE_SINGLE_PASS :: 429 * This flag is set to force a given scan-converter to only use a 430 * single pass over the outline to render a bitmap glyph image. 431 * Normally, it is set for very large character sizes. It is only 432 * a hint that might be completely ignored by a given 433 * scan-converter. 434 * 435 * @note: 436 * The flags @FT_OUTLINE_IGNORE_DROPOUTS, @FT_OUTLINE_SMART_DROPOUTS, 437 * and @FT_OUTLINE_INCLUDE_STUBS are ignored by the smooth 438 * rasterizer. 439 * 440 * There exists a second mechanism to pass the drop-out mode to the 441 * B/W rasterizer; see the `tags' field in @FT_Outline. 442 * 443 * Please refer to the description of the `SCANTYPE' instruction in 444 * the OpenType specification (in file `ttinst1.doc') how simple 445 * drop-outs, smart drop-outs, and stubs are defined. 446 */ 447 #define FT_OUTLINE_NONE 0x0 448 #define FT_OUTLINE_OWNER 0x1 449 #define FT_OUTLINE_EVEN_ODD_FILL 0x2 450 #define FT_OUTLINE_REVERSE_FILL 0x4 451 #define FT_OUTLINE_IGNORE_DROPOUTS 0x8 452 #define FT_OUTLINE_SMART_DROPOUTS 0x10 453 #define FT_OUTLINE_INCLUDE_STUBS 0x20 454 455 #define FT_OUTLINE_HIGH_PRECISION 0x100 456 #define FT_OUTLINE_SINGLE_PASS 0x200 457 458 459 /* these constants are deprecated; use the corresponding */ 460 /* `FT_OUTLINE_XXX' values instead */ 461 #define ft_outline_none FT_OUTLINE_NONE 462 #define ft_outline_owner FT_OUTLINE_OWNER 463 #define ft_outline_even_odd_fill FT_OUTLINE_EVEN_ODD_FILL 464 #define ft_outline_reverse_fill FT_OUTLINE_REVERSE_FILL 465 #define ft_outline_ignore_dropouts FT_OUTLINE_IGNORE_DROPOUTS 466 #define ft_outline_high_precision FT_OUTLINE_HIGH_PRECISION 467 #define ft_outline_single_pass FT_OUTLINE_SINGLE_PASS 468 469 /* */ 470 471 #define FT_CURVE_TAG( flag ) ( flag & 3 ) 472 473 #define FT_CURVE_TAG_ON 1 474 #define FT_CURVE_TAG_CONIC 0 475 #define FT_CURVE_TAG_CUBIC 2 476 477 #define FT_CURVE_TAG_HAS_SCANMODE 4 478 479 #define FT_CURVE_TAG_TOUCH_X 8 /* reserved for the TrueType hinter */ 480 #define FT_CURVE_TAG_TOUCH_Y 16 /* reserved for the TrueType hinter */ 481 482 #define FT_CURVE_TAG_TOUCH_BOTH ( FT_CURVE_TAG_TOUCH_X | \ 483 FT_CURVE_TAG_TOUCH_Y ) 484 485 #define FT_Curve_Tag_On FT_CURVE_TAG_ON 486 #define FT_Curve_Tag_Conic FT_CURVE_TAG_CONIC 487 #define FT_Curve_Tag_Cubic FT_CURVE_TAG_CUBIC 488 #define FT_Curve_Tag_Touch_X FT_CURVE_TAG_TOUCH_X 489 #define FT_Curve_Tag_Touch_Y FT_CURVE_TAG_TOUCH_Y 490 491 492 /************************************************************************** 493 * 494 * @functype: 495 * FT_Outline_MoveToFunc 496 * 497 * @description: 498 * A function pointer type used to describe the signature of a `move 499 * to' function during outline walking/decomposition. 500 * 501 * A `move to' is emitted to start a new contour in an outline. 502 * 503 * @input: 504 * to :: 505 * A pointer to the target point of the `move to'. 506 * 507 * user :: 508 * A typeless pointer, which is passed from the caller of the 509 * decomposition function. 510 * 511 * @return: 512 * Error code. 0~means success. 513 */ 514 typedef int 515 (*FT_Outline_MoveToFunc)( const FT_Vector* to, 516 void* user ); 517 518 #define FT_Outline_MoveTo_Func FT_Outline_MoveToFunc 519 520 521 /************************************************************************** 522 * 523 * @functype: 524 * FT_Outline_LineToFunc 525 * 526 * @description: 527 * A function pointer type used to describe the signature of a `line 528 * to' function during outline walking/decomposition. 529 * 530 * A `line to' is emitted to indicate a segment in the outline. 531 * 532 * @input: 533 * to :: 534 * A pointer to the target point of the `line to'. 535 * 536 * user :: 537 * A typeless pointer, which is passed from the caller of the 538 * decomposition function. 539 * 540 * @return: 541 * Error code. 0~means success. 542 */ 543 typedef int 544 (*FT_Outline_LineToFunc)( const FT_Vector* to, 545 void* user ); 546 547 #define FT_Outline_LineTo_Func FT_Outline_LineToFunc 548 549 550 /************************************************************************** 551 * 552 * @functype: 553 * FT_Outline_ConicToFunc 554 * 555 * @description: 556 * A function pointer type used to describe the signature of a `conic 557 * to' function during outline walking or decomposition. 558 * 559 * A `conic to' is emitted to indicate a second-order Bezier arc in 560 * the outline. 561 * 562 * @input: 563 * control :: 564 * An intermediate control point between the last position 565 * and the new target in `to'. 566 * 567 * to :: 568 * A pointer to the target end point of the conic arc. 569 * 570 * user :: 571 * A typeless pointer, which is passed from the caller of 572 * the decomposition function. 573 * 574 * @return: 575 * Error code. 0~means success. 576 */ 577 typedef int 578 (*FT_Outline_ConicToFunc)( const FT_Vector* control, 579 const FT_Vector* to, 580 void* user ); 581 582 #define FT_Outline_ConicTo_Func FT_Outline_ConicToFunc 583 584 585 /************************************************************************** 586 * 587 * @functype: 588 * FT_Outline_CubicToFunc 589 * 590 * @description: 591 * A function pointer type used to describe the signature of a `cubic 592 * to' function during outline walking or decomposition. 593 * 594 * A `cubic to' is emitted to indicate a third-order Bezier arc. 595 * 596 * @input: 597 * control1 :: 598 * A pointer to the first Bezier control point. 599 * 600 * control2 :: 601 * A pointer to the second Bezier control point. 602 * 603 * to :: 604 * A pointer to the target end point. 605 * 606 * user :: 607 * A typeless pointer, which is passed from the caller of 608 * the decomposition function. 609 * 610 * @return: 611 * Error code. 0~means success. 612 */ 613 typedef int 614 (*FT_Outline_CubicToFunc)( const FT_Vector* control1, 615 const FT_Vector* control2, 616 const FT_Vector* to, 617 void* user ); 618 619 #define FT_Outline_CubicTo_Func FT_Outline_CubicToFunc 620 621 622 /************************************************************************** 623 * 624 * @struct: 625 * FT_Outline_Funcs 626 * 627 * @description: 628 * A structure to hold various function pointers used during outline 629 * decomposition in order to emit segments, conic, and cubic Beziers. 630 * 631 * @fields: 632 * move_to :: 633 * The `move to' emitter. 634 * 635 * line_to :: 636 * The segment emitter. 637 * 638 * conic_to :: 639 * The second-order Bezier arc emitter. 640 * 641 * cubic_to :: 642 * The third-order Bezier arc emitter. 643 * 644 * shift :: 645 * The shift that is applied to coordinates before they 646 * are sent to the emitter. 647 * 648 * delta :: 649 * The delta that is applied to coordinates before they 650 * are sent to the emitter, but after the shift. 651 * 652 * @note: 653 * The point coordinates sent to the emitters are the transformed 654 * version of the original coordinates (this is important for high 655 * accuracy during scan-conversion). The transformation is simple: 656 * 657 * { 658 * x' = (x << shift) - delta 659 * y' = (y << shift) - delta 660 * } 661 * 662 * Set the values of `shift' and `delta' to~0 to get the original 663 * point coordinates. 664 */ 665 typedef struct FT_Outline_Funcs_ 666 { 667 FT_Outline_MoveToFunc move_to; 668 FT_Outline_LineToFunc line_to; 669 FT_Outline_ConicToFunc conic_to; 670 FT_Outline_CubicToFunc cubic_to; 671 672 int shift; 673 FT_Pos delta; 674 675 } FT_Outline_Funcs; 676 677 678 /************************************************************************** 679 * 680 * @section: 681 * basic_types 682 * 683 */ 684 685 686 /************************************************************************** 687 * 688 * @macro: 689 * FT_IMAGE_TAG 690 * 691 * @description: 692 * This macro converts four-letter tags to an unsigned long type. 693 * 694 * @note: 695 * Since many 16-bit compilers don't like 32-bit enumerations, you 696 * should redefine this macro in case of problems to something like 697 * this: 698 * 699 * { 700 * #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) value 701 * } 702 * 703 * to get a simple enumeration without assigning special numbers. 704 */ 705 #ifndef FT_IMAGE_TAG 706 #define FT_IMAGE_TAG( value, _x1, _x2, _x3, _x4 ) \ 707 value = ( ( (unsigned long)_x1 << 24 ) | \ 708 ( (unsigned long)_x2 << 16 ) | \ 709 ( (unsigned long)_x3 << 8 ) | \ 710 (unsigned long)_x4 ) 711 #endif /* FT_IMAGE_TAG */ 712 713 714 /************************************************************************** 715 * 716 * @enum: 717 * FT_Glyph_Format 718 * 719 * @description: 720 * An enumeration type used to describe the format of a given glyph 721 * image. Note that this version of FreeType only supports two image 722 * formats, even though future font drivers will be able to register 723 * their own format. 724 * 725 * @values: 726 * FT_GLYPH_FORMAT_NONE :: 727 * The value~0 is reserved. 728 * 729 * FT_GLYPH_FORMAT_COMPOSITE :: 730 * The glyph image is a composite of several other images. This 731 * format is _only_ used with @FT_LOAD_NO_RECURSE, and is used to 732 * report compound glyphs (like accented characters). 733 * 734 * FT_GLYPH_FORMAT_BITMAP :: 735 * The glyph image is a bitmap, and can be described as an 736 * @FT_Bitmap. You generally need to access the `bitmap' field of 737 * the @FT_GlyphSlotRec structure to read it. 738 * 739 * FT_GLYPH_FORMAT_OUTLINE :: 740 * The glyph image is a vectorial outline made of line segments 741 * and Bezier arcs; it can be described as an @FT_Outline; you 742 * generally want to access the `outline' field of the 743 * @FT_GlyphSlotRec structure to read it. 744 * 745 * FT_GLYPH_FORMAT_PLOTTER :: 746 * The glyph image is a vectorial path with no inside and outside 747 * contours. Some Type~1 fonts, like those in the Hershey family, 748 * contain glyphs in this format. These are described as 749 * @FT_Outline, but FreeType isn't currently capable of rendering 750 * them correctly. 751 */ 752 typedef enum FT_Glyph_Format_ 753 { 754 FT_IMAGE_TAG( FT_GLYPH_FORMAT_NONE, 0, 0, 0, 0 ), 755 756 FT_IMAGE_TAG( FT_GLYPH_FORMAT_COMPOSITE, 'c', 'o', 'm', 'p' ), 757 FT_IMAGE_TAG( FT_GLYPH_FORMAT_BITMAP, 'b', 'i', 't', 's' ), 758 FT_IMAGE_TAG( FT_GLYPH_FORMAT_OUTLINE, 'o', 'u', 't', 'l' ), 759 FT_IMAGE_TAG( FT_GLYPH_FORMAT_PLOTTER, 'p', 'l', 'o', 't' ) 760 761 } FT_Glyph_Format; 762 763 764 /* these constants are deprecated; use the corresponding */ 765 /* `FT_Glyph_Format' values instead. */ 766 #define ft_glyph_format_none FT_GLYPH_FORMAT_NONE 767 #define ft_glyph_format_composite FT_GLYPH_FORMAT_COMPOSITE 768 #define ft_glyph_format_bitmap FT_GLYPH_FORMAT_BITMAP 769 #define ft_glyph_format_outline FT_GLYPH_FORMAT_OUTLINE 770 #define ft_glyph_format_plotter FT_GLYPH_FORMAT_PLOTTER 771 772 773 /*************************************************************************/ 774 /*************************************************************************/ 775 /*************************************************************************/ 776 /***** *****/ 777 /***** R A S T E R D E F I N I T I O N S *****/ 778 /***** *****/ 779 /*************************************************************************/ 780 /*************************************************************************/ 781 /*************************************************************************/ 782 783 784 /************************************************************************** 785 * 786 * A raster is a scan converter, in charge of rendering an outline into 787 * a bitmap. This section contains the public API for rasters. 788 * 789 * Note that in FreeType 2, all rasters are now encapsulated within 790 * specific modules called `renderers'. See `ftrender.h' for more 791 * details on renderers. 792 * 793 */ 794 795 796 /************************************************************************** 797 * 798 * @section: 799 * raster 800 * 801 * @title: 802 * Scanline Converter 803 * 804 * @abstract: 805 * How vectorial outlines are converted into bitmaps and pixmaps. 806 * 807 * @description: 808 * This section contains technical definitions. 809 * 810 * @order: 811 * FT_Raster 812 * FT_Span 813 * FT_SpanFunc 814 * 815 * FT_Raster_Params 816 * FT_RASTER_FLAG_XXX 817 * 818 * FT_Raster_NewFunc 819 * FT_Raster_DoneFunc 820 * FT_Raster_ResetFunc 821 * FT_Raster_SetModeFunc 822 * FT_Raster_RenderFunc 823 * FT_Raster_Funcs 824 * 825 */ 826 827 828 /************************************************************************** 829 * 830 * @type: 831 * FT_Raster 832 * 833 * @description: 834 * An opaque handle (pointer) to a raster object. Each object can be 835 * used independently to convert an outline into a bitmap or pixmap. 836 */ 837 typedef struct FT_RasterRec_* FT_Raster; 838 839 840 /************************************************************************** 841 * 842 * @struct: 843 * FT_Span 844 * 845 * @description: 846 * A structure used to model a single span of gray pixels when 847 * rendering an anti-aliased bitmap. 848 * 849 * @fields: 850 * x :: 851 * The span's horizontal start position. 852 * 853 * len :: 854 * The span's length in pixels. 855 * 856 * coverage :: 857 * The span color/coverage, ranging from 0 (background) 858 * to 255 (foreground). 859 * 860 * @note: 861 * This structure is used by the span drawing callback type named 862 * @FT_SpanFunc that takes the y~coordinate of the span as a 863 * parameter. 864 * 865 * The coverage value is always between 0 and 255. If you want less 866 * gray values, the callback function has to reduce them. 867 */ 868 typedef struct FT_Span_ 869 { 870 short x; 871 unsigned short len; 872 unsigned char coverage; 873 874 } FT_Span; 875 876 877 /************************************************************************** 878 * 879 * @functype: 880 * FT_SpanFunc 881 * 882 * @description: 883 * A function used as a call-back by the anti-aliased renderer in 884 * order to let client applications draw themselves the gray pixel 885 * spans on each scan line. 886 * 887 * @input: 888 * y :: 889 * The scanline's y~coordinate. 890 * 891 * count :: 892 * The number of spans to draw on this scanline. 893 * 894 * spans :: 895 * A table of `count' spans to draw on the scanline. 896 * 897 * user :: 898 * User-supplied data that is passed to the callback. 899 * 900 * @note: 901 * This callback allows client applications to directly render the 902 * gray spans of the anti-aliased bitmap to any kind of surfaces. 903 * 904 * This can be used to write anti-aliased outlines directly to a 905 * given background bitmap, and even perform translucency. 906 */ 907 typedef void 908 (*FT_SpanFunc)( int y, 909 int count, 910 const FT_Span* spans, 911 void* user ); 912 913 #define FT_Raster_Span_Func FT_SpanFunc 914 915 916 /************************************************************************** 917 * 918 * @functype: 919 * FT_Raster_BitTest_Func 920 * 921 * @description: 922 * Deprecated, unimplemented. 923 */ 924 typedef int 925 (*FT_Raster_BitTest_Func)( int y, 926 int x, 927 void* user ); 928 929 930 /************************************************************************** 931 * 932 * @functype: 933 * FT_Raster_BitSet_Func 934 * 935 * @description: 936 * Deprecated, unimplemented. 937 */ 938 typedef void 939 (*FT_Raster_BitSet_Func)( int y, 940 int x, 941 void* user ); 942 943 944 /************************************************************************** 945 * 946 * @enum: 947 * FT_RASTER_FLAG_XXX 948 * 949 * @description: 950 * A list of bit flag constants as used in the `flags' field of a 951 * @FT_Raster_Params structure. 952 * 953 * @values: 954 * FT_RASTER_FLAG_DEFAULT :: 955 * This value is 0. 956 * 957 * FT_RASTER_FLAG_AA :: 958 * This flag is set to indicate that an 959 * anti-aliased glyph image should be 960 * generated. Otherwise, it will be 961 * monochrome (1-bit). 962 * 963 * FT_RASTER_FLAG_DIRECT :: 964 * This flag is set to indicate direct 965 * rendering. In this mode, client 966 * applications must provide their own span 967 * callback. This lets them directly 968 * draw or compose over an existing bitmap. 969 * If this bit is not set, the target 970 * pixmap's buffer _must_ be zeroed before 971 * rendering. 972 * 973 * Direct rendering is only possible with 974 * anti-aliased glyphs. 975 * 976 * FT_RASTER_FLAG_CLIP :: 977 * This flag is only used in direct 978 * rendering mode. If set, the output will 979 * be clipped to a box specified in the 980 * `clip_box' field of the 981 * @FT_Raster_Params structure. 982 * 983 * Note that by default, the glyph bitmap 984 * is clipped to the target pixmap, except 985 * in direct rendering mode where all spans 986 * are generated if no clipping box is set. 987 */ 988 #define FT_RASTER_FLAG_DEFAULT 0x0 989 #define FT_RASTER_FLAG_AA 0x1 990 #define FT_RASTER_FLAG_DIRECT 0x2 991 #define FT_RASTER_FLAG_CLIP 0x4 992 993 /* these constants are deprecated; use the corresponding */ 994 /* `FT_RASTER_FLAG_XXX' values instead */ 995 #define ft_raster_flag_default FT_RASTER_FLAG_DEFAULT 996 #define ft_raster_flag_aa FT_RASTER_FLAG_AA 997 #define ft_raster_flag_direct FT_RASTER_FLAG_DIRECT 998 #define ft_raster_flag_clip FT_RASTER_FLAG_CLIP 999 1000 1001 /************************************************************************** 1002 * 1003 * @struct: 1004 * FT_Raster_Params 1005 * 1006 * @description: 1007 * A structure to hold the arguments used by a raster's render 1008 * function. 1009 * 1010 * @fields: 1011 * target :: 1012 * The target bitmap. 1013 * 1014 * source :: 1015 * A pointer to the source glyph image (e.g., an 1016 * @FT_Outline). 1017 * 1018 * flags :: 1019 * The rendering flags. 1020 * 1021 * gray_spans :: 1022 * The gray span drawing callback. 1023 * 1024 * black_spans :: 1025 * Unused. 1026 * 1027 * bit_test :: 1028 * Unused. 1029 * 1030 * bit_set :: 1031 * Unused. 1032 * 1033 * user :: 1034 * User-supplied data that is passed to each drawing 1035 * callback. 1036 * 1037 * clip_box :: 1038 * An optional clipping box. It is only used in 1039 * direct rendering mode. Note that coordinates here 1040 * should be expressed in _integer_ pixels (and not in 1041 * 26.6 fixed-point units). 1042 * 1043 * @note: 1044 * An anti-aliased glyph bitmap is drawn if the @FT_RASTER_FLAG_AA 1045 * bit flag is set in the `flags' field, otherwise a monochrome 1046 * bitmap is generated. 1047 * 1048 * If the @FT_RASTER_FLAG_DIRECT bit flag is set in `flags', the 1049 * raster will call the `gray_spans' callback to draw gray pixel 1050 * spans. This allows direct composition over a pre-existing bitmap 1051 * through user-provided callbacks to perform the span drawing and 1052 * composition. Not supported by the monochrome rasterizer. 1053 */ 1054 typedef struct FT_Raster_Params_ 1055 { 1056 const FT_Bitmap* target; 1057 const void* source; 1058 int flags; 1059 FT_SpanFunc gray_spans; 1060 FT_SpanFunc black_spans; /* unused */ 1061 FT_Raster_BitTest_Func bit_test; /* unused */ 1062 FT_Raster_BitSet_Func bit_set; /* unused */ 1063 void* user; 1064 FT_BBox clip_box; 1065 1066 } FT_Raster_Params; 1067 1068 1069 /************************************************************************** 1070 * 1071 * @functype: 1072 * FT_Raster_NewFunc 1073 * 1074 * @description: 1075 * A function used to create a new raster object. 1076 * 1077 * @input: 1078 * memory :: 1079 * A handle to the memory allocator. 1080 * 1081 * @output: 1082 * raster :: 1083 * A handle to the new raster object. 1084 * 1085 * @return: 1086 * Error code. 0~means success. 1087 * 1088 * @note: 1089 * The `memory' parameter is a typeless pointer in order to avoid 1090 * un-wanted dependencies on the rest of the FreeType code. In 1091 * practice, it is an @FT_Memory object, i.e., a handle to the 1092 * standard FreeType memory allocator. However, this field can be 1093 * completely ignored by a given raster implementation. 1094 */ 1095 typedef int 1096 (*FT_Raster_NewFunc)( void* memory, 1097 FT_Raster* raster ); 1098 1099 #define FT_Raster_New_Func FT_Raster_NewFunc 1100 1101 1102 /************************************************************************** 1103 * 1104 * @functype: 1105 * FT_Raster_DoneFunc 1106 * 1107 * @description: 1108 * A function used to destroy a given raster object. 1109 * 1110 * @input: 1111 * raster :: 1112 * A handle to the raster object. 1113 */ 1114 typedef void 1115 (*FT_Raster_DoneFunc)( FT_Raster raster ); 1116 1117 #define FT_Raster_Done_Func FT_Raster_DoneFunc 1118 1119 1120 /************************************************************************** 1121 * 1122 * @functype: 1123 * FT_Raster_ResetFunc 1124 * 1125 * @description: 1126 * FreeType used to provide an area of memory called the `render 1127 * pool' available to all registered rasterizers. This was not 1128 * thread safe, however, and now FreeType never allocates this pool. 1129 * 1130 * This function is called after a new raster object is created. 1131 * 1132 * @input: 1133 * raster :: 1134 * A handle to the new raster object. 1135 * 1136 * pool_base :: 1137 * Previously, the address in memory of the render pool. 1138 * Set this to NULL. 1139 * 1140 * pool_size :: 1141 * Previously, the size in bytes of the render pool. 1142 * Set this to 0. 1143 * 1144 * @note: 1145 * Rasterizers should rely on dynamic or stack allocation if they 1146 * want to (a handle to the memory allocator is passed to the 1147 * rasterizer constructor). 1148 */ 1149 typedef void 1150 (*FT_Raster_ResetFunc)( FT_Raster raster, 1151 unsigned char* pool_base, 1152 unsigned long pool_size ); 1153 1154 #define FT_Raster_Reset_Func FT_Raster_ResetFunc 1155 1156 1157 /************************************************************************** 1158 * 1159 * @functype: 1160 * FT_Raster_SetModeFunc 1161 * 1162 * @description: 1163 * This function is a generic facility to change modes or attributes 1164 * in a given raster. This can be used for debugging purposes, or 1165 * simply to allow implementation-specific `features' in a given 1166 * raster module. 1167 * 1168 * @input: 1169 * raster :: 1170 * A handle to the new raster object. 1171 * 1172 * mode :: 1173 * A 4-byte tag used to name the mode or property. 1174 * 1175 * args :: 1176 * A pointer to the new mode/property to use. 1177 */ 1178 typedef int 1179 (*FT_Raster_SetModeFunc)( FT_Raster raster, 1180 unsigned long mode, 1181 void* args ); 1182 1183 #define FT_Raster_Set_Mode_Func FT_Raster_SetModeFunc 1184 1185 1186 /************************************************************************** 1187 * 1188 * @functype: 1189 * FT_Raster_RenderFunc 1190 * 1191 * @description: 1192 * Invoke a given raster to scan-convert a given glyph image into a 1193 * target bitmap. 1194 * 1195 * @input: 1196 * raster :: 1197 * A handle to the raster object. 1198 * 1199 * params :: 1200 * A pointer to an @FT_Raster_Params structure used to 1201 * store the rendering parameters. 1202 * 1203 * @return: 1204 * Error code. 0~means success. 1205 * 1206 * @note: 1207 * The exact format of the source image depends on the raster's glyph 1208 * format defined in its @FT_Raster_Funcs structure. It can be an 1209 * @FT_Outline or anything else in order to support a large array of 1210 * glyph formats. 1211 * 1212 * Note also that the render function can fail and return a 1213 * `FT_Err_Unimplemented_Feature' error code if the raster used does 1214 * not support direct composition. 1215 * 1216 * XXX: For now, the standard raster doesn't support direct 1217 * composition but this should change for the final release (see 1218 * the files `demos/src/ftgrays.c' and `demos/src/ftgrays2.c' 1219 * for examples of distinct implementations that support direct 1220 * composition). 1221 */ 1222 typedef int 1223 (*FT_Raster_RenderFunc)( FT_Raster raster, 1224 const FT_Raster_Params* params ); 1225 1226 #define FT_Raster_Render_Func FT_Raster_RenderFunc 1227 1228 1229 /************************************************************************** 1230 * 1231 * @struct: 1232 * FT_Raster_Funcs 1233 * 1234 * @description: 1235 * A structure used to describe a given raster class to the library. 1236 * 1237 * @fields: 1238 * glyph_format :: 1239 * The supported glyph format for this raster. 1240 * 1241 * raster_new :: 1242 * The raster constructor. 1243 * 1244 * raster_reset :: 1245 * Used to reset the render pool within the raster. 1246 * 1247 * raster_render :: 1248 * A function to render a glyph into a given bitmap. 1249 * 1250 * raster_done :: 1251 * The raster destructor. 1252 */ 1253 typedef struct FT_Raster_Funcs_ 1254 { 1255 FT_Glyph_Format glyph_format; 1256 1257 FT_Raster_NewFunc raster_new; 1258 FT_Raster_ResetFunc raster_reset; 1259 FT_Raster_SetModeFunc raster_set_mode; 1260 FT_Raster_RenderFunc raster_render; 1261 FT_Raster_DoneFunc raster_done; 1262 1263 } FT_Raster_Funcs; 1264 1265 /* */ 1266 1267 1268 FT_END_HEADER 1269 1270 #endif /* FTIMAGE_H_ */ 1271 1272 1273 /* END */ 1274 1275 1276 /* Local Variables: */ 1277 /* coding: utf-8 */ 1278 /* End: */ 1279
