Visualization Library 2.0.0-b5

A lightweight C++ OpenGL middleware for 2D/3D graphics

VL     Star     Watch     Fork     Issue

[Download] [Tutorials] [All Classes] [Grouped Classes]
ftstroke.h
Go to the documentation of this file.
1 /***************************************************************************/
2 /* */
3 /* ftstroke.h */
4 /* */
5 /* FreeType path stroker (specification). */
6 /* */
7 /* Copyright 2002-2006, 2008, 2009, 2011-2012 by */
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
9 /* */
10 /* This file is part of the FreeType project, and may only be used, */
11 /* modified, and distributed under the terms of the FreeType project */
12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
13 /* this file you indicate that you have read the license and */
14 /* understand and accept it fully. */
15 /* */
16 /***************************************************************************/
17 
18 
19 #ifndef __FT_STROKE_H__
20 #define __FT_STROKE_H__
21 
22 #include <ft2build.h>
23 #include FT_OUTLINE_H
24 #include FT_GLYPH_H
25 
26 
28 
29 
30  /************************************************************************
31  *
32  * @section:
33  * glyph_stroker
34  *
35  * @title:
36  * Glyph Stroker
37  *
38  * @abstract:
39  * Generating bordered and stroked glyphs.
40  *
41  * @description:
42  * This component generates stroked outlines of a given vectorial
43  * glyph. It also allows you to retrieve the `outside' and/or the
44  * `inside' borders of the stroke.
45  *
46  * This can be useful to generate `bordered' glyph, i.e., glyphs
47  * displayed with a coloured (and anti-aliased) border around their
48  * shape.
49  */
50 
51 
52  /**************************************************************
53  *
54  * @type:
55  * FT_Stroker
56  *
57  * @description:
58  * Opaque handler to a path stroker object.
59  */
60  typedef struct FT_StrokerRec_* FT_Stroker;
61 
62 
63  /**************************************************************
64  *
65  * @enum:
66  * FT_Stroker_LineJoin
67  *
68  * @description:
69  * These values determine how two joining lines are rendered
70  * in a stroker.
71  *
72  * @values:
73  * FT_STROKER_LINEJOIN_ROUND ::
74  * Used to render rounded line joins. Circular arcs are used
75  * to join two lines smoothly.
76  *
77  * FT_STROKER_LINEJOIN_BEVEL ::
78  * Used to render beveled line joins. The outer corner of
79  * the joined lines is filled by enclosing the triangular
80  * region of the corner with a straight line between the
81  * outer corners of each stroke.
82  *
83  * FT_STROKER_LINEJOIN_MITER_FIXED ::
84  * Used to render mitered line joins, with fixed bevels if the
85  * miter limit is exceeded. The outer edges of the strokes
86  * for the two segments are extended until they meet at an
87  * angle. If the segments meet at too sharp an angle (such
88  * that the miter would extend from the intersection of the
89  * segments a distance greater than the product of the miter
90  * limit value and the border radius), then a bevel join (see
91  * above) is used instead. This prevents long spikes being
92  * created. FT_STROKER_LINEJOIN_MITER_FIXED generates a miter
93  * line join as used in PostScript and PDF.
94  *
95  * FT_STROKER_LINEJOIN_MITER_VARIABLE ::
96  * FT_STROKER_LINEJOIN_MITER ::
97  * Used to render mitered line joins, with variable bevels if
98  * the miter limit is exceeded. The intersection of the
99  * strokes is clipped at a line perpendicular to the bisector
100  * of the angle between the strokes, at the distance from the
101  * intersection of the segments equal to the product of the
102  * miter limit value and the border radius. This prevents
103  * long spikes being created.
104  * FT_STROKER_LINEJOIN_MITER_VARIABLE generates a mitered line
105  * join as used in XPS. FT_STROKER_LINEJOIN_MITER is an alias
106  * for FT_STROKER_LINEJOIN_MITER_VARIABLE, retained for
107  * backwards compatibility.
108  */
109  typedef enum FT_Stroker_LineJoin_
110  {
116 
118 
119 
120  /**************************************************************
121  *
122  * @enum:
123  * FT_Stroker_LineCap
124  *
125  * @description:
126  * These values determine how the end of opened sub-paths are
127  * rendered in a stroke.
128  *
129  * @values:
130  * FT_STROKER_LINECAP_BUTT ::
131  * The end of lines is rendered as a full stop on the last
132  * point itself.
133  *
134  * FT_STROKER_LINECAP_ROUND ::
135  * The end of lines is rendered as a half-circle around the
136  * last point.
137  *
138  * FT_STROKER_LINECAP_SQUARE ::
139  * The end of lines is rendered as a square around the
140  * last point.
141  */
142  typedef enum FT_Stroker_LineCap_
143  {
147 
149 
150 
151  /**************************************************************
152  *
153  * @enum:
154  * FT_StrokerBorder
155  *
156  * @description:
157  * These values are used to select a given stroke border
158  * in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
159  *
160  * @values:
161  * FT_STROKER_BORDER_LEFT ::
162  * Select the left border, relative to the drawing direction.
163  *
164  * FT_STROKER_BORDER_RIGHT ::
165  * Select the right border, relative to the drawing direction.
166  *
167  * @note:
168  * Applications are generally interested in the `inside' and `outside'
169  * borders. However, there is no direct mapping between these and the
170  * `left' and `right' ones, since this really depends on the glyph's
171  * drawing orientation, which varies between font formats.
172  *
173  * You can however use @FT_Outline_GetInsideBorder and
174  * @FT_Outline_GetOutsideBorder to get these.
175  */
176  typedef enum FT_StrokerBorder_
177  {
180 
182 
183 
184  /**************************************************************
185  *
186  * @function:
187  * FT_Outline_GetInsideBorder
188  *
189  * @description:
190  * Retrieve the @FT_StrokerBorder value corresponding to the
191  * `inside' borders of a given outline.
192  *
193  * @input:
194  * outline ::
195  * The source outline handle.
196  *
197  * @return:
198  * The border index. @FT_STROKER_BORDER_RIGHT for empty or invalid
199  * outlines.
200  */
203 
204 
205  /**************************************************************
206  *
207  * @function:
208  * FT_Outline_GetOutsideBorder
209  *
210  * @description:
211  * Retrieve the @FT_StrokerBorder value corresponding to the
212  * `outside' borders of a given outline.
213  *
214  * @input:
215  * outline ::
216  * The source outline handle.
217  *
218  * @return:
219  * The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
220  * outlines.
221  */
224 
225 
226  /**************************************************************
227  *
228  * @function:
229  * FT_Stroker_New
230  *
231  * @description:
232  * Create a new stroker object.
233  *
234  * @input:
235  * library ::
236  * FreeType library handle.
237  *
238  * @output:
239  * astroker ::
240  * A new stroker object handle. NULL in case of error.
241  *
242  * @return:
243  * FreeType error code. 0~means success.
244  */
247  FT_Stroker *astroker );
248 
249 
250  /**************************************************************
251  *
252  * @function:
253  * FT_Stroker_Set
254  *
255  * @description:
256  * Reset a stroker object's attributes.
257  *
258  * @input:
259  * stroker ::
260  * The target stroker handle.
261  *
262  * radius ::
263  * The border radius.
264  *
265  * line_cap ::
266  * The line cap style.
267  *
268  * line_join ::
269  * The line join style.
270  *
271  * miter_limit ::
272  * The miter limit for the FT_STROKER_LINEJOIN_MITER_FIXED and
273  * FT_STROKER_LINEJOIN_MITER_VARIABLE line join styles,
274  * expressed as 16.16 fixed-point value.
275  *
276  * @note:
277  * The radius is expressed in the same units as the outline
278  * coordinates.
279  */
280  FT_EXPORT( void )
281  FT_Stroker_Set( FT_Stroker stroker,
282  FT_Fixed radius,
283  FT_Stroker_LineCap line_cap,
284  FT_Stroker_LineJoin line_join,
285  FT_Fixed miter_limit );
286 
287 
288  /**************************************************************
289  *
290  * @function:
291  * FT_Stroker_Rewind
292  *
293  * @description:
294  * Reset a stroker object without changing its attributes.
295  * You should call this function before beginning a new
296  * series of calls to @FT_Stroker_BeginSubPath or
297  * @FT_Stroker_EndSubPath.
298  *
299  * @input:
300  * stroker ::
301  * The target stroker handle.
302  */
303  FT_EXPORT( void )
304  FT_Stroker_Rewind( FT_Stroker stroker );
305 
306 
307  /**************************************************************
308  *
309  * @function:
310  * FT_Stroker_ParseOutline
311  *
312  * @description:
313  * A convenience function used to parse a whole outline with
314  * the stroker. The resulting outline(s) can be retrieved
315  * later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
316  *
317  * @input:
318  * stroker ::
319  * The target stroker handle.
320  *
321  * outline ::
322  * The source outline.
323  *
324  * opened ::
325  * A boolean. If~1, the outline is treated as an open path instead
326  * of a closed one.
327  *
328  * @return:
329  * FreeType error code. 0~means success.
330  *
331  * @note:
332  * If `opened' is~0 (the default), the outline is treated as a closed
333  * path, and the stroker generates two distinct `border' outlines.
334  *
335  * If `opened' is~1, the outline is processed as an open path, and the
336  * stroker generates a single `stroke' outline.
337  *
338  * This function calls @FT_Stroker_Rewind automatically.
339  */
342  FT_Outline* outline,
343  FT_Bool opened );
344 
345 
346  /**************************************************************
347  *
348  * @function:
349  * FT_Stroker_BeginSubPath
350  *
351  * @description:
352  * Start a new sub-path in the stroker.
353  *
354  * @input:
355  * stroker ::
356  * The target stroker handle.
357  *
358  * to ::
359  * A pointer to the start vector.
360  *
361  * open ::
362  * A boolean. If~1, the sub-path is treated as an open one.
363  *
364  * @return:
365  * FreeType error code. 0~means success.
366  *
367  * @note:
368  * This function is useful when you need to stroke a path that is
369  * not stored as an @FT_Outline object.
370  */
373  FT_Vector* to,
374  FT_Bool open );
375 
376 
377  /**************************************************************
378  *
379  * @function:
380  * FT_Stroker_EndSubPath
381  *
382  * @description:
383  * Close the current sub-path in the stroker.
384  *
385  * @input:
386  * stroker ::
387  * The target stroker handle.
388  *
389  * @return:
390  * FreeType error code. 0~means success.
391  *
392  * @note:
393  * You should call this function after @FT_Stroker_BeginSubPath.
394  * If the subpath was not `opened', this function `draws' a
395  * single line segment to the start position when needed.
396  */
399 
400 
401  /**************************************************************
402  *
403  * @function:
404  * FT_Stroker_LineTo
405  *
406  * @description:
407  * `Draw' a single line segment in the stroker's current sub-path,
408  * from the last position.
409  *
410  * @input:
411  * stroker ::
412  * The target stroker handle.
413  *
414  * to ::
415  * A pointer to the destination point.
416  *
417  * @return:
418  * FreeType error code. 0~means success.
419  *
420  * @note:
421  * You should call this function between @FT_Stroker_BeginSubPath and
422  * @FT_Stroker_EndSubPath.
423  */
425  FT_Stroker_LineTo( FT_Stroker stroker,
426  FT_Vector* to );
427 
428 
429  /**************************************************************
430  *
431  * @function:
432  * FT_Stroker_ConicTo
433  *
434  * @description:
435  * `Draw' a single quadratic Bézier in the stroker's current sub-path,
436  * from the last position.
437  *
438  * @input:
439  * stroker ::
440  * The target stroker handle.
441  *
442  * control ::
443  * A pointer to a Bézier control point.
444  *
445  * to ::
446  * A pointer to the destination point.
447  *
448  * @return:
449  * FreeType error code. 0~means success.
450  *
451  * @note:
452  * You should call this function between @FT_Stroker_BeginSubPath and
453  * @FT_Stroker_EndSubPath.
454  */
457  FT_Vector* control,
458  FT_Vector* to );
459 
460 
461  /**************************************************************
462  *
463  * @function:
464  * FT_Stroker_CubicTo
465  *
466  * @description:
467  * `Draw' a single cubic Bézier in the stroker's current sub-path,
468  * from the last position.
469  *
470  * @input:
471  * stroker ::
472  * The target stroker handle.
473  *
474  * control1 ::
475  * A pointer to the first Bézier control point.
476  *
477  * control2 ::
478  * A pointer to second Bézier control point.
479  *
480  * to ::
481  * A pointer to the destination point.
482  *
483  * @return:
484  * FreeType error code. 0~means success.
485  *
486  * @note:
487  * You should call this function between @FT_Stroker_BeginSubPath and
488  * @FT_Stroker_EndSubPath.
489  */
492  FT_Vector* control1,
493  FT_Vector* control2,
494  FT_Vector* to );
495 
496 
497  /**************************************************************
498  *
499  * @function:
500  * FT_Stroker_GetBorderCounts
501  *
502  * @description:
503  * Call this function once you have finished parsing your paths
504  * with the stroker. It returns the number of points and
505  * contours necessary to export one of the `border' or `stroke'
506  * outlines generated by the stroker.
507  *
508  * @input:
509  * stroker ::
510  * The target stroker handle.
511  *
512  * border ::
513  * The border index.
514  *
515  * @output:
516  * anum_points ::
517  * The number of points.
518  *
519  * anum_contours ::
520  * The number of contours.
521  *
522  * @return:
523  * FreeType error code. 0~means success.
524  *
525  * @note:
526  * When an outline, or a sub-path, is `closed', the stroker generates
527  * two independent `border' outlines, named `left' and `right'.
528  *
529  * When the outline, or a sub-path, is `opened', the stroker merges
530  * the `border' outlines with caps. The `left' border receives all
531  * points, while the `right' border becomes empty.
532  *
533  * Use the function @FT_Stroker_GetCounts instead if you want to
534  * retrieve the counts associated to both borders.
535  */
539  FT_UInt *anum_points,
540  FT_UInt *anum_contours );
541 
542 
543  /**************************************************************
544  *
545  * @function:
546  * FT_Stroker_ExportBorder
547  *
548  * @description:
549  * Call this function after @FT_Stroker_GetBorderCounts to
550  * export the corresponding border to your own @FT_Outline
551  * structure.
552  *
553  * Note that this function appends the border points and
554  * contours to your outline, but does not try to resize its
555  * arrays.
556  *
557  * @input:
558  * stroker ::
559  * The target stroker handle.
560  *
561  * border ::
562  * The border index.
563  *
564  * outline ::
565  * The target outline handle.
566  *
567  * @note:
568  * Always call this function after @FT_Stroker_GetBorderCounts to
569  * get sure that there is enough room in your @FT_Outline object to
570  * receive all new data.
571  *
572  * When an outline, or a sub-path, is `closed', the stroker generates
573  * two independent `border' outlines, named `left' and `right'
574  *
575  * When the outline, or a sub-path, is `opened', the stroker merges
576  * the `border' outlines with caps. The `left' border receives all
577  * points, while the `right' border becomes empty.
578  *
579  * Use the function @FT_Stroker_Export instead if you want to
580  * retrieve all borders at once.
581  */
582  FT_EXPORT( void )
585  FT_Outline* outline );
586 
587 
588  /**************************************************************
589  *
590  * @function:
591  * FT_Stroker_GetCounts
592  *
593  * @description:
594  * Call this function once you have finished parsing your paths
595  * with the stroker. It returns the number of points and
596  * contours necessary to export all points/borders from the stroked
597  * outline/path.
598  *
599  * @input:
600  * stroker ::
601  * The target stroker handle.
602  *
603  * @output:
604  * anum_points ::
605  * The number of points.
606  *
607  * anum_contours ::
608  * The number of contours.
609  *
610  * @return:
611  * FreeType error code. 0~means success.
612  */
615  FT_UInt *anum_points,
616  FT_UInt *anum_contours );
617 
618 
619  /**************************************************************
620  *
621  * @function:
622  * FT_Stroker_Export
623  *
624  * @description:
625  * Call this function after @FT_Stroker_GetBorderCounts to
626  * export all borders to your own @FT_Outline structure.
627  *
628  * Note that this function appends the border points and
629  * contours to your outline, but does not try to resize its
630  * arrays.
631  *
632  * @input:
633  * stroker ::
634  * The target stroker handle.
635  *
636  * outline ::
637  * The target outline handle.
638  */
639  FT_EXPORT( void )
640  FT_Stroker_Export( FT_Stroker stroker,
641  FT_Outline* outline );
642 
643 
644  /**************************************************************
645  *
646  * @function:
647  * FT_Stroker_Done
648  *
649  * @description:
650  * Destroy a stroker object.
651  *
652  * @input:
653  * stroker ::
654  * A stroker handle. Can be NULL.
655  */
656  FT_EXPORT( void )
657  FT_Stroker_Done( FT_Stroker stroker );
658 
659 
660  /**************************************************************
661  *
662  * @function:
663  * FT_Glyph_Stroke
664  *
665  * @description:
666  * Stroke a given outline glyph object with a given stroker.
667  *
668  * @inout:
669  * pglyph ::
670  * Source glyph handle on input, new glyph handle on output.
671  *
672  * @input:
673  * stroker ::
674  * A stroker handle.
675  *
676  * destroy ::
677  * A Boolean. If~1, the source glyph object is destroyed
678  * on success.
679  *
680  * @return:
681  * FreeType error code. 0~means success.
682  *
683  * @note:
684  * The source glyph is untouched in case of error.
685  *
686  * Adding stroke may yield a significantly wider and taller glyph
687  * depending on how large of a radius was used to stroke the glyph. You
688  * may need to manually adjust horizontal and vertical advance amounts
689  * to account for this added size.
690  */
692  FT_Glyph_Stroke( FT_Glyph *pglyph,
693  FT_Stroker stroker,
694  FT_Bool destroy );
695 
696 
697  /**************************************************************
698  *
699  * @function:
700  * FT_Glyph_StrokeBorder
701  *
702  * @description:
703  * Stroke a given outline glyph object with a given stroker, but
704  * only return either its inside or outside border.
705  *
706  * @inout:
707  * pglyph ::
708  * Source glyph handle on input, new glyph handle on output.
709  *
710  * @input:
711  * stroker ::
712  * A stroker handle.
713  *
714  * inside ::
715  * A Boolean. If~1, return the inside border, otherwise
716  * the outside border.
717  *
718  * destroy ::
719  * A Boolean. If~1, the source glyph object is destroyed
720  * on success.
721  *
722  * @return:
723  * FreeType error code. 0~means success.
724  *
725  * @note:
726  * The source glyph is untouched in case of error.
727  *
728  * Adding stroke may yield a significantly wider and taller glyph
729  * depending on how large of a radius was used to stroke the glyph. You
730  * may need to manually adjust horizontal and vertical advance amounts
731  * to account for this added size.
732  */
735  FT_Stroker stroker,
736  FT_Bool inside,
737  FT_Bool destroy );
738 
739  /* */
740 
742 
743 #endif /* __FT_STROKE_H__ */
744 
745 
746 /* END */
747 
748 
749 /* Local Variables: */
750 /* coding: utf-8 */
751 /* End: */
enum FT_Stroker_LineCap_ FT_Stroker_LineCap
int FT_Error
Definition: fttypes.h:296
FT_Stroker_ParseOutline(FT_Stroker stroker, FT_Outline *outline, FT_Bool opened)
Definition: ftstroke.c:2043
#define FT_END_HEADER
Definition: ftheader.h:54
FT_Stroker_Rewind(FT_Stroker stroker)
Definition: ftstroke.c:845
FT_Library library
Definition: cffdrivr.c:414
FT_Stroker_GetBorderCounts(FT_Stroker stroker, FT_StrokerBorder border, FT_UInt *anum_points, FT_UInt *anum_contours)
Definition: ftstroke.c:1946
FT_BEGIN_HEADER typedef unsigned char FT_Bool
Definition: fttypes.h:104
FT_Glyph_StrokeBorder(FT_Glyph *pglyph, FT_Stroker stroker, FT_Bool inside, FT_Bool destroy)
Definition: ftstroke.c:2332
FT_Stroker_ConicTo(FT_Stroker stroker, FT_Vector *control, FT_Vector *to)
Definition: ftstroke.c:1352
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
GLint GLint GLsizei GLsizei GLsizei GLint border
FT_Stroker_LineCap_
Definition: ftstroke.h:142
FT_StrokerBorder_
Definition: ftstroke.h:176
enum FT_StrokerBorder_ FT_StrokerBorder
FT_Stroker_ExportBorder(FT_Stroker stroker, FT_StrokerBorder border, FT_Outline *outline)
Definition: ftstroke.c:2009
FT_Stroker_BeginSubPath(FT_Stroker stroker, FT_Vector *to, FT_Bool open)
Definition: ftstroke.c:1757
FT_Stroker_LineTo(FT_Stroker stroker, FT_Vector *to)
Definition: ftstroke.c:1279
FT_Stroker_EndSubPath(FT_Stroker stroker)
Definition: ftstroke.c:1856
FT_Stroker_Export(FT_Stroker stroker, FT_Outline *outline)
Definition: ftstroke.c:2028
FT_Glyph_Stroke(FT_Glyph *pglyph, FT_Stroker stroker, FT_Bool destroy)
Definition: ftstroke.c:2257
FT_Stroker_Set(FT_Stroker stroker, FT_Fixed radius, FT_Stroker_LineCap line_cap, FT_Stroker_LineJoin line_join, FT_Fixed miter_limit)
Definition: ftstroke.c:819
enum FT_Stroker_LineJoin_ FT_Stroker_LineJoin
FT_Stroker_CubicTo(FT_Stroker stroker, FT_Vector *control1, FT_Vector *control2, FT_Vector *to)
Definition: ftstroke.c:1547
FT_Outline_GetInsideBorder(FT_Outline *outline)
Definition: ftstroke.c:31
signed long FT_Fixed
Definition: fttypes.h:284
int open(const char *name, int flags, int mode)
Definition: tif_acorn.c:285
unsigned int FT_UInt
Definition: fttypes.h:227
FT_Stroker_Done(FT_Stroker stroker)
Definition: ftstroke.c:858
#define FT_EXPORT(x)
Definition: ftconfig.h:269
FT_Stroker_New(FT_Library library, FT_Stroker *astroker)
Definition: ftstroke.c:789
FT_Outline_GetOutsideBorder(FT_Outline *outline)
Definition: ftstroke.c:44
typedefFT_BEGIN_HEADER struct FT_StrokerRec_ * FT_Stroker
Definition: ftstroke.h:60
FT_Stroker_GetCounts(FT_Stroker stroker, FT_UInt *anum_points, FT_UInt *anum_contours)
Definition: ftstroke.c:1977
FT_Stroker_LineJoin_
Definition: ftstroke.h:109