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