ReactOS  0.4.15-dev-3165-gdf6fff7
ftstroke.h
Go to the documentation of this file.
1 /***************************************************************************/
2 /* */
3 /* ftstroke.h */
4 /* */
5 /* FreeType path stroker (specification). */
6 /* */
7 /* Copyright 2002-2018 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 FTSTROKE_H_
20 #define FTSTROKE_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  * @order:
51  * FT_Stroker
52  *
53  * FT_Stroker_LineJoin
54  * FT_Stroker_LineCap
55  * FT_StrokerBorder
56  *
57  * FT_Outline_GetInsideBorder
58  * FT_Outline_GetOutsideBorder
59  *
60  * FT_Glyph_Stroke
61  * FT_Glyph_StrokeBorder
62  *
63  * FT_Stroker_New
64  * FT_Stroker_Set
65  * FT_Stroker_Rewind
66  * FT_Stroker_ParseOutline
67  * FT_Stroker_Done
68  *
69  * FT_Stroker_BeginSubPath
70  * FT_Stroker_EndSubPath
71  *
72  * FT_Stroker_LineTo
73  * FT_Stroker_ConicTo
74  * FT_Stroker_CubicTo
75  *
76  * FT_Stroker_GetBorderCounts
77  * FT_Stroker_ExportBorder
78  * FT_Stroker_GetCounts
79  * FT_Stroker_Export
80  *
81  */
82 
83 
84  /**************************************************************
85  *
86  * @type:
87  * FT_Stroker
88  *
89  * @description:
90  * Opaque handle to a path stroker object.
91  */
92  typedef struct FT_StrokerRec_* FT_Stroker;
93 
94 
95  /**************************************************************
96  *
97  * @enum:
98  * FT_Stroker_LineJoin
99  *
100  * @description:
101  * These values determine how two joining lines are rendered
102  * in a stroker.
103  *
104  * @values:
105  * FT_STROKER_LINEJOIN_ROUND ::
106  * Used to render rounded line joins. Circular arcs are used
107  * to join two lines smoothly.
108  *
109  * FT_STROKER_LINEJOIN_BEVEL ::
110  * Used to render beveled line joins. The outer corner of
111  * the joined lines is filled by enclosing the triangular
112  * region of the corner with a straight line between the
113  * outer corners of each stroke.
114  *
115  * FT_STROKER_LINEJOIN_MITER_FIXED ::
116  * Used to render mitered line joins, with fixed bevels if the
117  * miter limit is exceeded. The outer edges of the strokes
118  * for the two segments are extended until they meet at an
119  * angle. If the segments meet at too sharp an angle (such
120  * that the miter would extend from the intersection of the
121  * segments a distance greater than the product of the miter
122  * limit value and the border radius), then a bevel join (see
123  * above) is used instead. This prevents long spikes being
124  * created. FT_STROKER_LINEJOIN_MITER_FIXED generates a miter
125  * line join as used in PostScript and PDF.
126  *
127  * FT_STROKER_LINEJOIN_MITER_VARIABLE ::
128  * FT_STROKER_LINEJOIN_MITER ::
129  * Used to render mitered line joins, with variable bevels if
130  * the miter limit is exceeded. The intersection of the
131  * strokes is clipped at a line perpendicular to the bisector
132  * of the angle between the strokes, at the distance from the
133  * intersection of the segments equal to the product of the
134  * miter limit value and the border radius. This prevents
135  * long spikes being created.
136  * FT_STROKER_LINEJOIN_MITER_VARIABLE generates a mitered line
137  * join as used in XPS. FT_STROKER_LINEJOIN_MITER is an alias
138  * for FT_STROKER_LINEJOIN_MITER_VARIABLE, retained for
139  * backward compatibility.
140  */
141  typedef enum FT_Stroker_LineJoin_
142  {
148 
150 
151 
152  /**************************************************************
153  *
154  * @enum:
155  * FT_Stroker_LineCap
156  *
157  * @description:
158  * These values determine how the end of opened sub-paths are
159  * rendered in a stroke.
160  *
161  * @values:
162  * FT_STROKER_LINECAP_BUTT ::
163  * The end of lines is rendered as a full stop on the last
164  * point itself.
165  *
166  * FT_STROKER_LINECAP_ROUND ::
167  * The end of lines is rendered as a half-circle around the
168  * last point.
169  *
170  * FT_STROKER_LINECAP_SQUARE ::
171  * The end of lines is rendered as a square around the
172  * last point.
173  */
174  typedef enum FT_Stroker_LineCap_
175  {
179 
181 
182 
183  /**************************************************************
184  *
185  * @enum:
186  * FT_StrokerBorder
187  *
188  * @description:
189  * These values are used to select a given stroke border
190  * in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
191  *
192  * @values:
193  * FT_STROKER_BORDER_LEFT ::
194  * Select the left border, relative to the drawing direction.
195  *
196  * FT_STROKER_BORDER_RIGHT ::
197  * Select the right border, relative to the drawing direction.
198  *
199  * @note:
200  * Applications are generally interested in the `inside' and `outside'
201  * borders. However, there is no direct mapping between these and the
202  * `left' and `right' ones, since this really depends on the glyph's
203  * drawing orientation, which varies between font formats.
204  *
205  * You can however use @FT_Outline_GetInsideBorder and
206  * @FT_Outline_GetOutsideBorder to get these.
207  */
208  typedef enum FT_StrokerBorder_
209  {
212 
214 
215 
216  /**************************************************************
217  *
218  * @function:
219  * FT_Outline_GetInsideBorder
220  *
221  * @description:
222  * Retrieve the @FT_StrokerBorder value corresponding to the
223  * `inside' borders of a given outline.
224  *
225  * @input:
226  * outline ::
227  * The source outline handle.
228  *
229  * @return:
230  * The border index. @FT_STROKER_BORDER_RIGHT for empty or invalid
231  * outlines.
232  */
235 
236 
237  /**************************************************************
238  *
239  * @function:
240  * FT_Outline_GetOutsideBorder
241  *
242  * @description:
243  * Retrieve the @FT_StrokerBorder value corresponding to the
244  * `outside' borders of a given outline.
245  *
246  * @input:
247  * outline ::
248  * The source outline handle.
249  *
250  * @return:
251  * The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
252  * outlines.
253  */
256 
257 
258  /**************************************************************
259  *
260  * @function:
261  * FT_Stroker_New
262  *
263  * @description:
264  * Create a new stroker object.
265  *
266  * @input:
267  * library ::
268  * FreeType library handle.
269  *
270  * @output:
271  * astroker ::
272  * A new stroker object handle. NULL in case of error.
273  *
274  * @return:
275  * FreeType error code. 0~means success.
276  */
279  FT_Stroker *astroker );
280 
281 
282  /**************************************************************
283  *
284  * @function:
285  * FT_Stroker_Set
286  *
287  * @description:
288  * Reset a stroker object's attributes.
289  *
290  * @input:
291  * stroker ::
292  * The target stroker handle.
293  *
294  * radius ::
295  * The border radius.
296  *
297  * line_cap ::
298  * The line cap style.
299  *
300  * line_join ::
301  * The line join style.
302  *
303  * miter_limit ::
304  * The miter limit for the FT_STROKER_LINEJOIN_MITER_FIXED and
305  * FT_STROKER_LINEJOIN_MITER_VARIABLE line join styles,
306  * expressed as 16.16 fixed-point value.
307  *
308  * @note:
309  * The radius is expressed in the same units as the outline
310  * coordinates.
311  *
312  * This function calls @FT_Stroker_Rewind automatically.
313  */
314  FT_EXPORT( void )
315  FT_Stroker_Set( FT_Stroker stroker,
320 
321 
322  /**************************************************************
323  *
324  * @function:
325  * FT_Stroker_Rewind
326  *
327  * @description:
328  * Reset a stroker object without changing its attributes.
329  * You should call this function before beginning a new
330  * series of calls to @FT_Stroker_BeginSubPath or
331  * @FT_Stroker_EndSubPath.
332  *
333  * @input:
334  * stroker ::
335  * The target stroker handle.
336  */
337  FT_EXPORT( void )
338  FT_Stroker_Rewind( FT_Stroker stroker );
339 
340 
341  /**************************************************************
342  *
343  * @function:
344  * FT_Stroker_ParseOutline
345  *
346  * @description:
347  * A convenience function used to parse a whole outline with
348  * the stroker. The resulting outline(s) can be retrieved
349  * later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
350  *
351  * @input:
352  * stroker ::
353  * The target stroker handle.
354  *
355  * outline ::
356  * The source outline.
357  *
358  * opened ::
359  * A boolean. If~1, the outline is treated as an open path instead
360  * of a closed one.
361  *
362  * @return:
363  * FreeType error code. 0~means success.
364  *
365  * @note:
366  * If `opened' is~0 (the default), the outline is treated as a closed
367  * path, and the stroker generates two distinct `border' outlines.
368  *
369  * If `opened' is~1, the outline is processed as an open path, and the
370  * stroker generates a single `stroke' outline.
371  *
372  * This function calls @FT_Stroker_Rewind automatically.
373  */
377  FT_Bool opened );
378 
379 
380  /**************************************************************
381  *
382  * @function:
383  * FT_Stroker_BeginSubPath
384  *
385  * @description:
386  * Start a new sub-path in the stroker.
387  *
388  * @input:
389  * stroker ::
390  * The target stroker handle.
391  *
392  * to ::
393  * A pointer to the start vector.
394  *
395  * open ::
396  * A boolean. If~1, the sub-path is treated as an open one.
397  *
398  * @return:
399  * FreeType error code. 0~means success.
400  *
401  * @note:
402  * This function is useful when you need to stroke a path that is
403  * not stored as an @FT_Outline object.
404  */
407  FT_Vector* to,
408  FT_Bool open );
409 
410 
411  /**************************************************************
412  *
413  * @function:
414  * FT_Stroker_EndSubPath
415  *
416  * @description:
417  * Close the current sub-path in the stroker.
418  *
419  * @input:
420  * stroker ::
421  * The target stroker handle.
422  *
423  * @return:
424  * FreeType error code. 0~means success.
425  *
426  * @note:
427  * You should call this function after @FT_Stroker_BeginSubPath.
428  * If the subpath was not `opened', this function `draws' a
429  * single line segment to the start position when needed.
430  */
433 
434 
435  /**************************************************************
436  *
437  * @function:
438  * FT_Stroker_LineTo
439  *
440  * @description:
441  * `Draw' a single line segment in the stroker's current sub-path,
442  * from the last position.
443  *
444  * @input:
445  * stroker ::
446  * The target stroker handle.
447  *
448  * to ::
449  * A pointer to the destination point.
450  *
451  * @return:
452  * FreeType error code. 0~means success.
453  *
454  * @note:
455  * You should call this function between @FT_Stroker_BeginSubPath and
456  * @FT_Stroker_EndSubPath.
457  */
459  FT_Stroker_LineTo( FT_Stroker stroker,
460  FT_Vector* to );
461 
462 
463  /**************************************************************
464  *
465  * @function:
466  * FT_Stroker_ConicTo
467  *
468  * @description:
469  * `Draw' a single quadratic Bezier in the stroker's current sub-path,
470  * from the last position.
471  *
472  * @input:
473  * stroker ::
474  * The target stroker handle.
475  *
476  * control ::
477  * A pointer to a Bezier control point.
478  *
479  * to ::
480  * A pointer to the destination point.
481  *
482  * @return:
483  * FreeType error code. 0~means success.
484  *
485  * @note:
486  * You should call this function between @FT_Stroker_BeginSubPath and
487  * @FT_Stroker_EndSubPath.
488  */
491  FT_Vector* control,
492  FT_Vector* to );
493 
494 
495  /**************************************************************
496  *
497  * @function:
498  * FT_Stroker_CubicTo
499  *
500  * @description:
501  * `Draw' a single cubic Bezier in the stroker's current sub-path,
502  * from the last position.
503  *
504  * @input:
505  * stroker ::
506  * The target stroker handle.
507  *
508  * control1 ::
509  * A pointer to the first Bezier control point.
510  *
511  * control2 ::
512  * A pointer to second Bezier control point.
513  *
514  * to ::
515  * A pointer to the destination point.
516  *
517  * @return:
518  * FreeType error code. 0~means success.
519  *
520  * @note:
521  * You should call this function between @FT_Stroker_BeginSubPath and
522  * @FT_Stroker_EndSubPath.
523  */
526  FT_Vector* control1,
527  FT_Vector* control2,
528  FT_Vector* to );
529 
530 
531  /**************************************************************
532  *
533  * @function:
534  * FT_Stroker_GetBorderCounts
535  *
536  * @description:
537  * Call this function once you have finished parsing your paths
538  * with the stroker. It returns the number of points and
539  * contours necessary to export one of the `border' or `stroke'
540  * outlines generated by the stroker.
541  *
542  * @input:
543  * stroker ::
544  * The target stroker handle.
545  *
546  * border ::
547  * The border index.
548  *
549  * @output:
550  * anum_points ::
551  * The number of points.
552  *
553  * anum_contours ::
554  * The number of contours.
555  *
556  * @return:
557  * FreeType error code. 0~means success.
558  *
559  * @note:
560  * When an outline, or a sub-path, is `closed', the stroker generates
561  * two independent `border' outlines, named `left' and `right'.
562  *
563  * When the outline, or a sub-path, is `opened', the stroker merges
564  * the `border' outlines with caps. The `left' border receives all
565  * points, while the `right' border becomes empty.
566  *
567  * Use the function @FT_Stroker_GetCounts instead if you want to
568  * retrieve the counts associated to both borders.
569  */
573  FT_UInt *anum_points,
574  FT_UInt *anum_contours );
575 
576 
577  /**************************************************************
578  *
579  * @function:
580  * FT_Stroker_ExportBorder
581  *
582  * @description:
583  * Call this function after @FT_Stroker_GetBorderCounts to
584  * export the corresponding border to your own @FT_Outline
585  * structure.
586  *
587  * Note that this function appends the border points and
588  * contours to your outline, but does not try to resize its
589  * arrays.
590  *
591  * @input:
592  * stroker ::
593  * The target stroker handle.
594  *
595  * border ::
596  * The border index.
597  *
598  * outline ::
599  * The target outline handle.
600  *
601  * @note:
602  * Always call this function after @FT_Stroker_GetBorderCounts to
603  * get sure that there is enough room in your @FT_Outline object to
604  * receive all new data.
605  *
606  * When an outline, or a sub-path, is `closed', the stroker generates
607  * two independent `border' outlines, named `left' and `right'.
608  *
609  * When the outline, or a sub-path, is `opened', the stroker merges
610  * the `border' outlines with caps. The `left' border receives all
611  * points, while the `right' border becomes empty.
612  *
613  * Use the function @FT_Stroker_Export instead if you want to
614  * retrieve all borders at once.
615  */
616  FT_EXPORT( void )
619  FT_Outline* outline );
620 
621 
622  /**************************************************************
623  *
624  * @function:
625  * FT_Stroker_GetCounts
626  *
627  * @description:
628  * Call this function once you have finished parsing your paths
629  * with the stroker. It returns the number of points and
630  * contours necessary to export all points/borders from the stroked
631  * outline/path.
632  *
633  * @input:
634  * stroker ::
635  * The target stroker handle.
636  *
637  * @output:
638  * anum_points ::
639  * The number of points.
640  *
641  * anum_contours ::
642  * The number of contours.
643  *
644  * @return:
645  * FreeType error code. 0~means success.
646  */
649  FT_UInt *anum_points,
650  FT_UInt *anum_contours );
651 
652 
653  /**************************************************************
654  *
655  * @function:
656  * FT_Stroker_Export
657  *
658  * @description:
659  * Call this function after @FT_Stroker_GetBorderCounts to
660  * export all borders to your own @FT_Outline structure.
661  *
662  * Note that this function appends the border points and
663  * contours to your outline, but does not try to resize its
664  * arrays.
665  *
666  * @input:
667  * stroker ::
668  * The target stroker handle.
669  *
670  * outline ::
671  * The target outline handle.
672  */
673  FT_EXPORT( void )
674  FT_Stroker_Export( FT_Stroker stroker,
675  FT_Outline* outline );
676 
677 
678  /**************************************************************
679  *
680  * @function:
681  * FT_Stroker_Done
682  *
683  * @description:
684  * Destroy a stroker object.
685  *
686  * @input:
687  * stroker ::
688  * A stroker handle. Can be NULL.
689  */
690  FT_EXPORT( void )
691  FT_Stroker_Done( FT_Stroker stroker );
692 
693 
694  /**************************************************************
695  *
696  * @function:
697  * FT_Glyph_Stroke
698  *
699  * @description:
700  * Stroke a given outline glyph object with a given stroker.
701  *
702  * @inout:
703  * pglyph ::
704  * Source glyph handle on input, new glyph handle on output.
705  *
706  * @input:
707  * stroker ::
708  * A stroker handle.
709  *
710  * destroy ::
711  * A Boolean. If~1, the source glyph object is destroyed
712  * on success.
713  *
714  * @return:
715  * FreeType error code. 0~means success.
716  *
717  * @note:
718  * The source glyph is untouched in case of error.
719  *
720  * Adding stroke may yield a significantly wider and taller glyph
721  * depending on how large of a radius was used to stroke the glyph. You
722  * may need to manually adjust horizontal and vertical advance amounts
723  * to account for this added size.
724  */
726  FT_Glyph_Stroke( FT_Glyph *pglyph,
727  FT_Stroker stroker,
728  FT_Bool destroy );
729 
730 
731  /**************************************************************
732  *
733  * @function:
734  * FT_Glyph_StrokeBorder
735  *
736  * @description:
737  * Stroke a given outline glyph object with a given stroker, but
738  * only return either its inside or outside border.
739  *
740  * @inout:
741  * pglyph ::
742  * Source glyph handle on input, new glyph handle on output.
743  *
744  * @input:
745  * stroker ::
746  * A stroker handle.
747  *
748  * inside ::
749  * A Boolean. If~1, return the inside border, otherwise
750  * the outside border.
751  *
752  * destroy ::
753  * A Boolean. If~1, the source glyph object is destroyed
754  * on success.
755  *
756  * @return:
757  * FreeType error code. 0~means success.
758  *
759  * @note:
760  * The source glyph is untouched in case of error.
761  *
762  * Adding stroke may yield a significantly wider and taller glyph
763  * depending on how large of a radius was used to stroke the glyph. You
764  * may need to manually adjust horizontal and vertical advance amounts
765  * to account for this added size.
766  */
769  FT_Stroker stroker,
770  FT_Bool inside,
771  FT_Bool destroy );
772 
773  /* */
774 
776 
777 #endif /* FTSTROKE_H_ */
778 
779 
780 /* END */
781 
782 
783 /* Local Variables: */
784 /* coding: utf-8 */
785 /* End: */
enum FT_Stroker_LineCap_ FT_Stroker_LineCap
int FT_Error
Definition: fttypes.h:300
FT_Stroker_ParseOutline(FT_Stroker stroker, FT_Outline *outline, FT_Bool opened)
Definition: ftstroke.c:2094
#define FT_END_HEADER
Definition: ftheader.h:54
#define open
Definition: acwin.h:95
FT_Stroker_Rewind(FT_Stroker stroker)
Definition: ftstroke.c:862
FT_Stroker_LineJoin line_join
Definition: ftstroke.c:786
FT_Library library
Definition: cffdrivr.c:654
FT_Stroker_GetBorderCounts(FT_Stroker stroker, FT_StrokerBorder border, FT_UInt *anum_points, FT_UInt *anum_contours)
Definition: ftstroke.c:1984
FT_BEGIN_HEADER typedef unsigned char FT_Bool
Definition: fttypes.h:108
FT_Glyph_StrokeBorder(FT_Glyph *pglyph, FT_Stroker stroker, FT_Bool inside, FT_Bool destroy)
Definition: ftstroke.c:2381
FT_Stroker_ConicTo(FT_Stroker stroker, FT_Vector *control, FT_Vector *to)
Definition: ftstroke.c:1372
#define FT_BEGIN_HEADER
Definition: ftheader.h:36
FT_Stroker_LineCap line_cap
Definition: ftstroke.c:785
FT_Stroker_LineCap_
Definition: ftstroke.h:174
FT_StrokerBorder_
Definition: ftstroke.h:208
enum FT_StrokerBorder_ FT_StrokerBorder
FT_Stroker_ExportBorder(FT_Stroker stroker, FT_StrokerBorder border, FT_Outline *outline)
Definition: ftstroke.c:2057
FT_Stroker_BeginSubPath(FT_Stroker stroker, FT_Vector *to, FT_Bool open)
Definition: ftstroke.c:1789
FT_Stroker_LineTo(FT_Stroker stroker, FT_Vector *to)
Definition: ftstroke.c:1296
GLint GLint GLsizei GLsizei GLsizei GLint border
Definition: gl.h:1546
FT_Stroker_EndSubPath(FT_Stroker stroker)
Definition: ftstroke.c:1891
FT_Stroker_Export(FT_Stroker stroker, FT_Outline *outline)
Definition: ftstroke.c:2079
FT_Glyph_Stroke(FT_Glyph *pglyph, FT_Stroker stroker, FT_Bool destroy)
Definition: ftstroke.c:2302
void destroy(_Tp *__pointer)
Definition: _construct.h:278
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:833
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:1573
Definition: mesh.c:5329
FT_Outline_GetInsideBorder(FT_Outline *outline)
Definition: ftstroke.c:41
signed long FT_Fixed
Definition: fttypes.h:288
unsigned int FT_UInt
Definition: fttypes.h:231
FT_Fixed radius
Definition: ftstroke.c:789
FT_Stroker_Done(FT_Stroker stroker)
Definition: ftstroke.c:875
#define FT_EXPORT(x)
Definition: ftconfig.h:461
FT_Stroker_New(FT_Library library, FT_Stroker *astroker)
Definition: ftstroke.c:800
FT_Outline_GetOutsideBorder(FT_Outline *outline)
Definition: ftstroke.c:54
typedefFT_BEGIN_HEADER struct FT_StrokerRec_ * FT_Stroker
Definition: ftstroke.h:92
FT_Fixed miter_limit
Definition: ftstroke.c:788
FT_Stroker_GetCounts(FT_Stroker stroker, FT_UInt *anum_points, FT_UInt *anum_contours)
Definition: ftstroke.c:2015
FT_Stroker_LineJoin_
Definition: ftstroke.h:141