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