1
/***************************************************************************/
5
/* FreeType path stroker (specification). */
7
/* Copyright 2002, 2003, 2004 by */
8
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
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. */
16
/***************************************************************************/
19
#ifndef __FT_STROKE_H__
20
#define __FT_STROKE_H__
28
/*@*************************************************************
34
* Opaque handler to a path stroker object.
36
typedef struct FT_StrokerRec_* FT_Stroker;
39
/*@*************************************************************
45
* These values determine how two joining lines are rendered
49
* FT_STROKER_LINEJOIN_ROUND ::
50
* Used to render rounded line joins. Circular arcs are used
51
* to join two lines smoothly.
53
* FT_STROKER_LINEJOIN_BEVEL ::
54
* Used to render beveled line joins; i.e., the two joining lines
55
* are extended until they intersect.
57
* FT_STROKER_LINEJOIN_MITER ::
58
* Same as beveled rendering, except that an additional line
59
* break is added if the angle between the two joining lines
60
* is too closed (this is useful to avoid unpleasant spikes
61
* in beveled rendering).
65
FT_STROKER_LINEJOIN_ROUND = 0,
66
FT_STROKER_LINEJOIN_BEVEL,
67
FT_STROKER_LINEJOIN_MITER
69
} FT_Stroker_LineJoin;
72
/*@*************************************************************
78
* These values determine how the end of opened sub-paths are
79
* rendered in a stroke.
82
* FT_STROKER_LINECAP_BUTT ::
83
* The end of lines is rendered as a full stop on the last
86
* FT_STROKER_LINECAP_ROUND ::
87
* The end of lines is rendered as a half-circle around the
90
* FT_STROKER_LINECAP_SQUARE ::
91
* The end of lines is rendered as a square around the
96
FT_STROKER_LINECAP_BUTT = 0,
97
FT_STROKER_LINECAP_ROUND,
98
FT_STROKER_LINECAP_SQUARE
100
} FT_Stroker_LineCap;
103
/**************************************************************
109
* These values are used to select a given stroke border
110
* in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
113
* FT_STROKER_BORDER_LEFT ::
114
* Select the left border, relative to the drawing direction.
116
* FT_STROKER_BORDER_RIGHT ::
117
* Select the right border, relative to the drawing direction.
120
* Applications are generally interested in the `inside' and `outside'
121
* borders. However, there is no direct mapping between these and
122
* the `left' / `right' ones, since this really depends on the glyph's
123
* drawing orientation, which varies between font formats.
125
* You can however use @FT_Outline_GetInsideBorder and
126
* @FT_Outline_GetOutsideBorder to get these.
130
FT_STROKER_BORDER_LEFT = 0,
131
FT_STROKER_BORDER_RIGHT
136
/**************************************************************
139
* FT_Outline_GetInsideBorder
142
* Retrieve the @FT_StrokerBorder value corresponding to the
143
* `inside' borders of a given outline.
147
* The source outline handle.
150
* The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
153
FT_EXPORT( FT_StrokerBorder )
154
FT_Outline_GetInsideBorder( FT_Outline* outline );
157
/**************************************************************
160
* FT_Outline_GetOutsideBorder
163
* Retrieve the @FT_StrokerBorder value corresponding to the
164
* `outside' borders of a given outline.
168
* The source outline handle.
171
* The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
174
FT_EXPORT( FT_StrokerBorder )
175
FT_Outline_GetOutsideBorder( FT_Outline* outline );
178
/**************************************************************
184
* Create a new stroker object.
188
* The memory manager handle.
191
* A new stroker object handle. NULL in case of error.
194
* FreeType error code. 0 means success.
196
FT_EXPORT( FT_Error )
197
FT_Stroker_New( FT_Memory memory,
198
FT_Stroker *astroker );
201
/**************************************************************
207
* Reset a stroker object's attributes.
211
* The target stroker handle.
217
* The line cap style.
220
* The line join style.
223
* The miter limit for the FT_STROKER_LINEJOIN_MITER style,
224
* expressed as 16.16 fixed point value.
227
* The radius is expressed in the same units that the outline
231
FT_Stroker_Set( FT_Stroker stroker,
233
FT_Stroker_LineCap line_cap,
234
FT_Stroker_LineJoin line_join,
235
FT_Fixed miter_limit );
238
/**************************************************************
244
* Reset a stroker object without changing its attributes.
245
* You should call this function before beginning a new
246
* series of calls to @FT_Stroker_BeginSubPath or
247
* @FT_Stroker_EndSubPath.
251
* The target stroker handle.
254
FT_Stroker_Rewind( FT_Stroker stroker );
257
/**************************************************************
260
* FT_Stroker_ParseOutline
263
* A convenience function used to parse a whole outline with
264
* the stroker. The resulting outline(s) can be retrieved
265
* later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
269
* The target stroker handle.
272
* The source outline.
275
* A boolean. If TRUE, the outline is treated as an open path
276
* instead of a closed one.
279
* FreeType error code. 0 means success.
282
* If `opened' is 0 (the default), the outline is treated as a closed
283
* path, and the stroker will generate two distinct `border' outlines.
285
* If `opened' is 1, the outline is processed as an open path, and the
286
* stroker will generate a single `stroke' outline.
288
* This function calls @FT_Stroker_Rewind automatically.
290
FT_EXPORT( FT_Error )
291
FT_Stroker_ParseOutline( FT_Stroker stroker,
296
/**************************************************************
299
* FT_Stroker_BeginSubPath
302
* Start a new sub-path in the stroker.
306
* The target stroker handle.
309
* A pointer to the start vector.
312
* A boolean. If TRUE, the sub-path is treated as an open one.
315
* FreeType error code. 0 means success.
318
* This function is useful when you need to stroke a path that is
319
* not stored as a @FT_Outline object.
321
FT_EXPORT( FT_Error )
322
FT_Stroker_BeginSubPath( FT_Stroker stroker,
327
/**************************************************************
330
* FT_Stroker_EndSubPath
333
* Close the current sub-path in the stroker.
337
* The target stroker handle.
340
* FreeType error code. 0 means success.
343
* You should call this function after @FT_Stroker_BeginSubPath.
344
* If the subpath was not `opened', this function will `draw' a
345
* single line segment to the start position when needed.
347
FT_EXPORT( FT_Error )
348
FT_Stroker_EndSubPath( FT_Stroker stroker );
351
/**************************************************************
357
* `Draw' a single line segment in the stroker's current sub-path,
358
* from the last position.
362
* The target stroker handle.
365
* A pointer to the destination point.
368
* FreeType error code. 0 means success.
371
* You should call this function between @FT_Stroker_BeginSubPath and
372
* @FT_Stroker_EndSubPath.
374
FT_EXPORT( FT_Error )
375
FT_Stroker_LineTo( FT_Stroker stroker,
379
/**************************************************************
385
* `Draw; a single quadratic bezier in the stroker's current sub-path,
386
* from the last position.
390
* The target stroker handle.
393
* A pointer to a Bļæ½zier control point.
396
* A pointer to the destination point.
399
* FreeType error code. 0 means success.
402
* You should call this function between @FT_Stroker_BeginSubPath and
403
* @FT_Stroker_EndSubPath.
405
FT_EXPORT( FT_Error )
406
FT_Stroker_ConicTo( FT_Stroker stroker,
411
/**************************************************************
417
* `Draw' a single cubic Bļæ½zier in the stroker's current sub-path,
418
* from the last position.
422
* The target stroker handle.
425
* A pointer to the first Bļæ½zier control point.
428
* A pointer to second Bļæ½zier control point.
431
* A pointer to the destination point.
434
* FreeType error code. 0 means success.
437
* You should call this function between @FT_Stroker_BeginSubPath and
438
* @FT_Stroker_EndSubPath.
440
FT_EXPORT( FT_Error )
441
FT_Stroker_CubicTo( FT_Stroker stroker,
447
/**************************************************************
450
* FT_Stroker_GetBorderCounts
453
* Vall this function once you have finished parsing your paths
454
* with the stroker. It will return the number of points and
455
* contours necessary to export one of the `border' or `stroke'
456
* outlines generated by the stroker.
460
* The target stroker handle.
467
* The number of points.
470
* The number of contours.
473
* FreeType error code. 0 means success.
476
* When an outline, or a sub-path, is `closed', the stroker generates
477
* two independent `border' outlines, named `left' and `right'.
479
* When the outline, or a sub-path, is `opened', the stroker merges
480
* the `border' outlines with caps. The `left' border receives all
481
* points, while the `right' border becomes empty.
483
* Use the function @FT_Stroker_GetCounts instead if you want to
484
* retrieve the counts associated to both borders.
486
FT_EXPORT( FT_Error )
487
FT_Stroker_GetBorderCounts( FT_Stroker stroker,
488
FT_StrokerBorder border,
489
FT_UInt *anum_points,
490
FT_UInt *anum_contours );
493
/**************************************************************
496
* FT_Stroker_ExportBorder
499
* Call this function after @FT_Stroker_GetBorderCounts to
500
* export the corresponding border to your own @FT_Outline
503
* Note that this function will append the border points and
504
* contours to your outline, but will not try to resize its
509
* The target stroker handle.
515
* The target outline handle.
518
* Always call this function after @FT_Stroker_GetBorderCounts to
519
* get sure that there is enough room in your @FT_Outline object to
520
* receive all new data.
522
* When an outline, or a sub-path, is `closed', the stroker generates
523
* two independent `border' outlines, named `left' and `right'
525
* When the outline, or a sub-path, is `opened', the stroker merges
526
* the `border' outlines with caps. The `left' border receives all
527
* points, while the `right' border becomes empty.
529
* Use the function @FT_Stroker_Export instead if you want to
530
* retrieve all borders at once.
533
FT_Stroker_ExportBorder( FT_Stroker stroker,
534
FT_StrokerBorder border,
535
FT_Outline* outline );
538
/**************************************************************
541
* FT_Stroker_GetCounts
544
* Call this function once you have finished parsing your paths
545
* with the stroker. It returns the number of points and
546
* contours necessary to export all points/borders from the stroked
551
* The target stroker handle.
555
* The number of points.
558
* The number of contours.
561
* FreeType error code. 0 means success.
563
FT_EXPORT( FT_Error )
564
FT_Stroker_GetCounts( FT_Stroker stroker,
565
FT_UInt *anum_points,
566
FT_UInt *anum_contours );
569
/**************************************************************
575
* Call this function after @FT_Stroker_GetBorderCounts to
576
* export the all borders to your own @FT_Outline structure.
578
* Note that this function will append the border points and
579
* contours to your outline, but will not try to resize its
584
* The target stroker handle.
587
* The target outline handle.
590
FT_Stroker_Export( FT_Stroker stroker,
591
FT_Outline* outline );
594
/**************************************************************
600
* Destroy a stroker object.
604
* A stroker handle. Can be NULL.
607
FT_Stroker_Done( FT_Stroker stroker );
610
/**************************************************************
616
* Stroke a given outline glyph object with a given stroker.
619
* pglyph :: Source glyph handle on input, new glyph handle
627
* A Boolean. If TRUE, the source glyph object is destroyed
631
* FreeType error code. 0 means success.
634
* The source glyph is untouched in case of error.
636
FT_EXPORT( FT_Error )
637
FT_Glyph_Stroke( FT_Glyph *pglyph,
642
/**************************************************************
645
* FT_Glyph_StrokeBorder
648
* Stroke a given outline glyph object with a given stroker, but
649
* only return either its inside or outside border.
653
* Source glyph handle on input, new glyph handle on output.
660
* A Boolean. If TRUE, return the inside border, otherwise
661
* the outside border.
664
* A Boolean. If TRUE, the source glyph object is destroyed
668
* FreeType error code. 0 means success.
671
* The source glyph is untouched in case of error.
673
FT_EXPORT( FT_Error )
674
FT_Glyph_StrokeBorder( FT_Glyph *pglyph,
683
#endif /* __FT_STROKE_H__ */