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
36FT_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
1283FT_END_HEADER
1284
1285#endif /* FTIMAGE_H_ */
1286
1287
1288/* END */
1289
1290
1291/* Local Variables: */
1292/* coding: utf-8 */
1293/* End: */
1294