LibGd 2.4.0-dev
GD Graphics library
Loading...
Searching...
No Matches
gd_ft_raster.h
1#ifndef GD_FT_IMG_H
2#define GD_FT_IMG_H
3/***************************************************************************/
4/* */
5/* ftimage.h */
6/* */
7/* FreeType glyph image formats and default raster interface */
8/* (specification). */
9/* */
10/* Copyright 1996-2010, 2013 by */
11/* David Turner, Robert Wilhelm, and Werner Lemberg. */
12/* */
13/* This file is part of the FreeType project, and may only be used, */
14/* modified, and distributed under the terms of the FreeType project */
15/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
16/* this file you indicate that you have read the license and */
17/* understand and accept it fully. */
18/* */
19/***************************************************************************/
20
21/*************************************************************************/
22/* */
23/* Note: A `raster' is simply a scan-line converter, used to render */
24/* GD_FT_Outlines into GD_FT_Bitmaps. */
25/* */
26/*************************************************************************/
27
28#include "gd_ft_types.h"
29
30typedef struct gdPathStruct *gdPathPtr;
31typedef struct gdPathMatrixStruct *gdPathMatrixPtr;
32
33/*************************************************************************/
34/* */
35/* <Struct> */
36/* FT_BBox */
37/* */
38/* <Description> */
39/* A structure used to hold an outline's bounding box, i.e., the */
40/* coordinates of its extrema in the horizontal and vertical */
41/* directions. */
42/* */
43/* <Fields> */
44/* xMin :: The horizontal minimum (left-most). */
45/* */
46/* yMin :: The vertical minimum (bottom-most). */
47/* */
48/* xMax :: The horizontal maximum (right-most). */
49/* */
50/* yMax :: The vertical maximum (top-most). */
51/* */
52/* <Note> */
53/* The bounding box is specified with the coordinates of the lower */
54/* left and the upper right corner. In PostScript, those values are */
55/* often called (llx,lly) and (urx,ury), respectively. */
56/* */
57/* If `yMin' is negative, this value gives the glyph's descender. */
58/* Otherwise, the glyph doesn't descend below the baseline. */
59/* Similarly, if `ymax' is positive, this value gives the glyph's */
60/* ascender. */
61/* */
62/* `xMin' gives the horizontal distance from the glyph's origin to */
63/* the left edge of the glyph's bounding box. If `xMin' is negative, */
64/* the glyph extends to the left of the origin. */
65/* */
66typedef struct GD_FT_BBox_ {
67 GD_FT_Pos xMin, yMin;
68 GD_FT_Pos xMax, yMax;
69
70} GD_FT_BBox;
71
72/*************************************************************************/
73/* */
74/* <Struct> */
75/* GD_FT_Outline */
76/* */
77/* <Description> */
78/* This structure is used to describe an outline to the scan-line */
79/* converter. */
80/* */
81/* <Fields> */
82/* n_contours :: The number of contours in the outline. */
83/* */
84/* n_points :: The number of points in the outline. */
85/* */
86/* points :: A pointer to an array of `n_points' @GD_FT_Vector */
87/* elements, giving the outline's point coordinates. */
88/* */
89/* tags :: A pointer to an array of `n_points' chars, giving */
90/* each outline point's type. */
91/* */
92/* If bit~0 is unset, the point is `off' the curve, */
93/* i.e., a Bézier control point, while it is `on' if */
94/* set. */
95/* */
96/* Bit~1 is meaningful for `off' points only. If set, */
97/* it indicates a third-order Bézier arc control point; */
98/* and a second-order control point if unset. */
99/* */
100/* If bit~2 is set, bits 5-7 contain the drop-out mode */
101/* (as defined in the OpenType specification; the value */
102/* is the same as the argument to the SCANMODE */
103/* instruction). */
104/* */
105/* Bits 3 and~4 are reserved for internal purposes. */
106/* */
107/* contours :: An array of `n_contours' shorts, giving the end */
108/* point of each contour within the outline. For */
109/* example, the first contour is defined by the points */
110/* `0' to `contours[0]', the second one is defined by */
111/* the points `contours[0]+1' to `contours[1]', etc. */
112/* */
113/* flags :: A set of bit flags used to characterize the outline */
114/* and give hints to the scan-converter and hinter on */
115/* how to convert/grid-fit it. See @GD_FT_OUTLINE_FLAGS.*/
116/* */
117typedef struct GD_FT_Outline_ {
118 short n_contours; /* number of contours in glyph */
119 short n_points; /* number of points in the glyph */
120
121 GD_FT_Vector *points; /* the outline's points */
122 char *tags; /* the points flags */
123 short *contours; /* the contour end points */
124 char *contours_flag; /* the contour open flags */
125
126 int flags; /* outline masks */
127
128} GD_FT_Outline;
129
130/*************************************************************************/
131/* */
132/* <Enum> */
133/* GD_FT_OUTLINE_FLAGS */
134/* */
135/* <Description> */
136/* A list of bit-field constants use for the flags in an outline's */
137/* `flags' field. */
138/* */
139/* <Values> */
140/* GD_FT_OUTLINE_NONE :: */
141/* Value~0 is reserved. */
142/* */
143/* GD_FT_OUTLINE_OWNER :: */
144/* If set, this flag indicates that the outline's field arrays */
145/* (i.e., `points', `flags', and `contours') are `owned' by the */
146/* outline object, and should thus be freed when it is destroyed. */
147/* */
148/* GD_FT_OUTLINE_EVEN_ODD_FILL :: */
149/* By default, outlines are filled using the non-zero winding rule. */
150/* If set to 1, the outline will be filled using the even-odd fill */
151/* rule (only works with the smooth rasterizer). */
152/* */
153/* GD_FT_OUTLINE_REVERSE_FILL :: */
154/* By default, outside contours of an outline are oriented in */
155/* clock-wise direction, as defined in the TrueType specification. */
156/* This flag is set if the outline uses the opposite direction */
157/* (typically for Type~1 fonts). This flag is ignored by the scan */
158/* converter. */
159/* */
160/* */
161/* */
162/* There exists a second mechanism to pass the drop-out mode to the */
163/* B/W rasterizer; see the `tags' field in @GD_FT_Outline. */
164/* */
165/* Please refer to the description of the `SCANTYPE' instruction in */
166/* the OpenType specification (in file `ttinst1.doc') how simple */
167/* drop-outs, smart drop-outs, and stubs are defined. */
168/* */
169#define GD_FT_OUTLINE_NONE 0x0
170#define GD_FT_OUTLINE_OWNER 0x1
171#define GD_FT_OUTLINE_EVEN_ODD_FILL 0x2
172#define GD_FT_OUTLINE_REVERSE_FILL 0x4
173
174/* */
175
176#define GD_FT_CURVE_TAG(flag) (flag & 3)
177
178#define GD_FT_CURVE_TAG_ON 1
179#define GD_FT_CURVE_TAG_CONIC 0
180#define GD_FT_CURVE_TAG_CUBIC 2
181
182#define GD_FT_Curve_Tag_On GD_FT_CURVE_TAG_ON
183#define GD_FT_Curve_Tag_Conic GD_FT_CURVE_TAG_CONIC
184#define GD_FT_Curve_Tag_Cubic GD_FT_CURVE_TAG_CUBIC
185
186/*************************************************************************/
187/* */
188/* A raster is a scan converter, in charge of rendering an outline into */
189/* a a bitmap. This section contains the public API for rasters. */
190/* */
191/* Note that in FreeType 2, all rasters are now encapsulated within */
192/* specific modules called `renderers'. See `ftrender.h' for more */
193/* details on renderers. */
194/* */
195/*************************************************************************/
196
197/*************************************************************************/
198/* */
199/* <Type> */
200/* GD_FT_Raster */
201/* */
202/* <Description> */
203/* A handle (pointer) to a raster object. Each object can be used */
204/* independently to convert an outline into a bitmap or pixmap. */
205/* */
206typedef struct GD_FT_RasterRec_ *GD_FT_Raster;
207
208/*************************************************************************/
209/* */
210/* <Struct> */
211/* GD_FT_Span */
212/* */
213/* <Description> */
214/* A structure used to model a single span of gray (or black) pixels */
215/* when rendering a monochrome or anti-aliased bitmap. */
216/* */
217/* <Fields> */
218/* x :: The span's horizontal start position. */
219/* */
220/* len :: The span's length in pixels. */
221/* */
222/* coverage :: The span color/coverage, ranging from 0 (background) */
223/* to 255 (foreground). Only used for anti-aliased */
224/* rendering. */
225/* */
226/* <Note> */
227/* This structure is used by the span drawing callback type named */
228/* @GD_FT_SpanFunc that takes the y~coordinate of the span as a */
229/* parameter. */
230/* */
231/* The coverage value is always between 0 and 255. If you want less */
232/* gray values, the callback function has to reduce them. */
233/* */
234typedef struct GD_FT_Span_ {
235 short x;
236 short y;
237 unsigned short len;
238 unsigned char coverage;
239
240} GD_FT_Span;
241
242/*************************************************************************/
243/* */
244/* <FuncType> */
245/* GD_FT_SpanFunc */
246/* */
247/* <Description> */
248/* A function used as a call-back by the anti-aliased renderer in */
249/* order to let client applications draw themselves the gray pixel */
250/* spans on each scan line. */
251/* */
252/* <Input> */
253/* y :: The scanline's y~coordinate. */
254/* */
255/* count :: The number of spans to draw on this scanline. */
256/* */
257/* spans :: A table of `count' spans to draw on the scanline. */
258/* */
259/* user :: User-supplied data that is passed to the callback. */
260/* */
261/* <Note> */
262/* This callback allows client applications to directly render the */
263/* gray spans of the anti-aliased bitmap to any kind of surfaces. */
264/* */
265/* This can be used to write anti-aliased outlines directly to a */
266/* given background bitmap, and even perform translucency. */
267/* */
268/* Note that the `count' field cannot be greater than a fixed value */
269/* defined by the `GD_FT_MAX_GRAY_SPANS' configuration macro in */
270/* `ftoption.h'. By default, this value is set to~32, which means */
271/* that if there are more than 32~spans on a given scanline, the */
272/* callback is called several times with the same `y' parameter in */
273/* order to draw all callbacks. */
274/* */
275/* Otherwise, the callback is only called once per scan-line, and */
276/* only for those scanlines that do have `gray' pixels on them. */
277/* */
278typedef void (*GD_FT_SpanFunc)(int count, const GD_FT_Span *spans, void *user);
279
280typedef void (*GD_FT_BboxFunc)(int x, int y, int w, int h, void *user);
281
282#define GD_FT_Raster_Span_Func GD_FT_SpanFunc
283
284/*************************************************************************/
285/* */
286/* <Enum> */
287/* GD_FT_RASTER_FLAG_XXX */
288/* */
289/* <Description> */
290/* A list of bit flag constants as used in the `flags' field of a */
291/* @GD_FT_Raster_Params structure. */
292/* */
293/* <Values> */
294/* GD_FT_RASTER_FLAG_DEFAULT :: This value is 0. */
295/* */
296/* GD_FT_RASTER_FLAG_AA :: This flag is set to indicate that an */
297/* anti-aliased glyph image should be */
298/* generated. Otherwise, it will be */
299/* monochrome (1-bit). */
300/* */
301/* GD_FT_RASTER_FLAG_DIRECT :: This flag is set to indicate direct */
302/* rendering. In this mode, client */
303/* applications must provide their own span */
304/* callback. This lets them directly */
305/* draw or compose over an existing bitmap. */
306/* If this bit is not set, the target */
307/* pixmap's buffer _must_ be zeroed before */
308/* rendering. */
309/* */
310/* Note that for now, direct rendering is */
311/* only possible with anti-aliased glyphs. */
312/* */
313/* GD_FT_RASTER_FLAG_CLIP :: This flag is only used in direct */
314/* rendering mode. If set, the output will */
315/* be clipped to a box specified in the */
316/* `clip_box' field of the */
317/* @GD_FT_Raster_Params structure. */
318/* */
319/* Note that by default, the glyph bitmap */
320/* is clipped to the target pixmap, except */
321/* in direct rendering mode where all spans */
322/* are generated if no clipping box is set. */
323/* */
324#define GD_FT_RASTER_FLAG_DEFAULT 0x0
325#define GD_FT_RASTER_FLAG_AA 0x1
326#define GD_FT_RASTER_FLAG_DIRECT 0x2
327#define GD_FT_RASTER_FLAG_CLIP 0x4
328
329/*************************************************************************/
330/* */
331/* <Struct> */
332/* GD_FT_Raster_Params */
333/* */
334/* <Description> */
335/* A structure to hold the arguments used by a raster's render */
336/* function. */
337/* */
338/* <Fields> */
339/* target :: The target bitmap. */
340/* */
341/* source :: A pointer to the source glyph image (e.g., an */
342/* @GD_FT_Outline). */
343/* */
344/* flags :: The rendering flags. */
345/* */
346/* gray_spans :: The gray span drawing callback. */
347/* */
348/* black_spans :: The black span drawing callback. UNIMPLEMENTED! */
349/* */
350/* bit_test :: The bit test callback. UNIMPLEMENTED! */
351/* */
352/* bit_set :: The bit set callback. UNIMPLEMENTED! */
353/* */
354/* user :: User-supplied data that is passed to each drawing */
355/* callback. */
356/* */
357/* clip_box :: An optional clipping box. It is only used in */
358/* direct rendering mode. Note that coordinates here */
359/* should be expressed in _integer_ pixels (and not in */
360/* 26.6 fixed-point units). */
361/* */
362/* <Note> */
363/* An anti-aliased glyph bitmap is drawn if the @GD_FT_RASTER_FLAG_AA */
364/* bit flag is set in the `flags' field, otherwise a monochrome */
365/* bitmap is generated. */
366/* */
367/* If the @GD_FT_RASTER_FLAG_DIRECT bit flag is set in `flags', the */
368/* raster will call the `gray_spans' callback to draw gray pixel */
369/* spans, in the case of an aa glyph bitmap, it will call */
370/* `black_spans', and `bit_test' and `bit_set' in the case of a */
371/* monochrome bitmap. This allows direct composition over a */
372/* pre-existing bitmap through user-provided callbacks to perform the */
373/* span drawing/composition. */
374/* */
375/* Note that the `bit_test' and `bit_set' callbacks are required when */
376/* rendering a monochrome bitmap, as they are crucial to implement */
377/* correct drop-out control as defined in the TrueType specification. */
378/* */
379typedef struct GD_FT_Raster_Params_ {
380 const void *source;
381 int flags;
382 GD_FT_SpanFunc gray_spans;
383 GD_FT_BboxFunc bbox_cb;
384 void *user;
385 GD_FT_BBox clip_box;
386
387} GD_FT_Raster_Params;
388
389/*************************************************************************/
390/* */
391/* <Function> */
392/* GD_FT_Outline_Check */
393/* */
394/* <Description> */
395/* Check the contents of an outline descriptor. */
396/* */
397/* <Input> */
398/* outline :: A handle to a source outline. */
399/* */
400/* <Return> */
401/* FreeType error code. 0~means success. */
402/* */
403GD_FT_Error GD_FT_Outline_Check(GD_FT_Outline *outline);
404
405/*************************************************************************/
406/* */
407/* <Function> */
408/* GD_FT_Outline_Get_CBox */
409/* */
410/* <Description> */
411/* Return an outline's `control box'. The control box encloses all */
412/* the outline's points, including Bézier control points. Though it */
413/* coincides with the exact bounding box for most glyphs, it can be */
414/* slightly larger in some situations (like when rotating an outline */
415/* that contains Bézier outside arcs). */
416/* */
417/* Computing the control box is very fast, while getting the bounding */
418/* box can take much more time as it needs to walk over all segments */
419/* and arcs in the outline. To get the latter, you can use the */
420/* `ftbbox' component, which is dedicated to this single task. */
421/* */
422/* <Input> */
423/* outline :: A pointer to the source outline descriptor. */
424/* */
425/* <Output> */
426/* acbox :: The outline's control box. */
427/* */
428/* <Note> */
429/* See @GD_FT_Glyph_Get_CBox for a discussion of tricky fonts. */
430/* */
431void GD_FT_Outline_Get_CBox(const GD_FT_Outline *outline, GD_FT_BBox *acbox);
432
433/*************************************************************************/
434/* */
435/* <FuncType> */
436/* GD_FT_Raster_NewFunc */
437/* */
438/* <Description> */
439/* A function used to create a new raster object. */
440/* */
441/* <Input> */
442/* memory :: A handle to the memory allocator. */
443/* */
444/* <Output> */
445/* raster :: A handle to the new raster object. */
446/* */
447/* <Return> */
448/* Error code. 0~means success. */
449/* */
450/* <Note> */
451/* The `memory' parameter is a typeless pointer in order to avoid */
452/* un-wanted dependencies on the rest of the FreeType code. In */
453/* practice, it is an @GD_FT_Memory object, i.e., a handle to the */
454/* standard FreeType memory allocator. However, this field can be */
455/* completely ignored by a given raster implementation. */
456/* */
457typedef int (*GD_FT_Raster_NewFunc)(GD_FT_Raster *raster);
458
459#define GD_FT_Raster_New_Func GD_FT_Raster_NewFunc
460
461/*************************************************************************/
462/* */
463/* <FuncType> */
464/* GD_FT_Raster_DoneFunc */
465/* */
466/* <Description> */
467/* A function used to destroy a given raster object. */
468/* */
469/* <Input> */
470/* raster :: A handle to the raster object. */
471/* */
472typedef void (*GD_FT_Raster_DoneFunc)(GD_FT_Raster raster);
473
474#define GD_FT_Raster_Done_Func GD_FT_Raster_DoneFunc
475
476/*************************************************************************/
477/* */
478/* <FuncType> */
479/* GD_FT_Raster_ResetFunc */
480/* */
481/* <Description> */
482/* FreeType provides an area of memory called the `render pool', */
483/* available to all registered rasters. This pool can be freely used */
484/* during a given scan-conversion but is shared by all rasters. Its */
485/* content is thus transient. */
486/* */
487/* This function is called each time the render pool changes, or just */
488/* after a new raster object is created. */
489/* */
490/* <Input> */
491/* raster :: A handle to the new raster object. */
492/* */
493/* pool_base :: The address in memory of the render pool. */
494/* */
495/* pool_size :: The size in bytes of the render pool. */
496/* */
497/* <Note> */
498/* Rasters can ignore the render pool and rely on dynamic memory */
499/* allocation if they want to (a handle to the memory allocator is */
500/* passed to the raster constructor). However, this is not */
501/* recommended for efficiency purposes. */
502/* */
503typedef void (*GD_FT_Raster_ResetFunc)(GD_FT_Raster raster, unsigned char *pool_base,
504 unsigned long pool_size);
505
506#define GD_FT_Raster_Reset_Func GD_FT_Raster_ResetFunc
507
508/*************************************************************************/
509/* */
510/* <FuncType> */
511/* GD_FT_Raster_RenderFunc */
512/* */
513/* <Description> */
514/* Invoke a given raster to scan-convert a given glyph image into a */
515/* target bitmap. */
516/* */
517/* <Input> */
518/* raster :: A handle to the raster object. */
519/* */
520/* params :: A pointer to an @GD_FT_Raster_Params structure used to */
521/* store the rendering parameters. */
522/* */
523/* <Return> */
524/* Error code. 0~means success. */
525/* */
526/* <Note> */
527/* The exact format of the source image depends on the raster's glyph */
528/* format defined in its @GD_FT_Raster_Funcs structure. It can be an */
529/* @GD_FT_Outline or anything else in order to support a large array of */
530/* glyph formats. */
531/* */
532/* Note also that the render function can fail and return a */
533/* `GD_FT_Err_Unimplemented_Feature' error code if the raster used does */
534/* not support direct composition. */
535/* */
536/* XXX: For now, the standard raster doesn't support direct */
537/* composition but this should change for the final release (see */
538/* the files `demos/src/ftgrays.c' and `demos/src/ftgrays2.c' */
539/* for examples of distinct implementations that support direct */
540/* composition). */
541/* */
542typedef int (*GD_FT_Raster_RenderFunc)(GD_FT_Raster raster, const GD_FT_Raster_Params *params);
543
544#define GD_FT_Raster_Render_Func GD_FT_Raster_RenderFunc
545
546/*************************************************************************/
547/* */
548/* <Struct> */
549/* GD_FT_Raster_Funcs */
550/* */
551/* <Description> */
552/* A structure used to describe a given raster class to the library. */
553/* */
554/* <Fields> */
555/* glyph_format :: The supported glyph format for this raster. */
556/* */
557/* raster_new :: The raster constructor. */
558/* */
559/* raster_reset :: Used to reset the render pool within the raster. */
560/* */
561/* raster_render :: A function to render a glyph into a given bitmap. */
562/* */
563/* raster_done :: The raster destructor. */
564/* */
565typedef struct GD_FT_Raster_Funcs_ {
566 GD_FT_Raster_NewFunc raster_new;
567 GD_FT_Raster_ResetFunc raster_reset;
568 GD_FT_Raster_RenderFunc raster_render;
569 GD_FT_Raster_DoneFunc raster_done;
570
571} GD_FT_Raster_Funcs;
572
573extern const GD_FT_Raster_Funcs gd_ft_grays_raster;
574
575/* Direct path rendering without FT_Outline intermediate */
576GD_FT_Error gd_ft_raster_render_path(const gdPathPtr path, gdPathMatrixPtr matrix,
577 GD_FT_Raster_Params *params, int outline_flags);
578
579#endif // GD_FT_IMG_H
gdPathMatrixPtr
gdPathMatrix * gdPathMatrixPtr
Affine transformation matrix pointer.
Definition gd_vector2d.h:146
gdPathMatrixStruct
Affine transformation matrix.
Definition gd_vector2d.h:139
Generated by doxygen 1.9.8