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