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__
30 /************************************************************************
39 * Generating bordered and stroked glyphs.
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.
46 * This can be useful to generate `bordered' glyph, i.e., glyphs
47 * displayed with a coloured (and anti-aliased) border around their
52 /**************************************************************
58 * Opaque handler to a path stroker object.
60 typedef struct FT_StrokerRec_* FT_Stroker;
63 /**************************************************************
69 * These values determine how two joining lines are rendered
73 * FT_STROKER_LINEJOIN_ROUND ::
74 * Used to render rounded line joins. Circular arcs are used
75 * to join two lines smoothly.
77 * FT_STROKER_LINEJOIN_BEVEL ::
78 * Used to render beveled line joins; i.e., the two joining lines
79 * are extended until they intersect.
81 * FT_STROKER_LINEJOIN_MITER ::
82 * Same as beveled rendering, except that an additional line
83 * break is added if the angle between the two joining lines
84 * is too closed (this is useful to avoid unpleasant spikes
85 * in beveled rendering).
89 FT_STROKER_LINEJOIN_ROUND = 0,
90 FT_STROKER_LINEJOIN_BEVEL,
91 FT_STROKER_LINEJOIN_MITER
93 } FT_Stroker_LineJoin;
96 /**************************************************************
102 * These values determine how the end of opened sub-paths are
103 * rendered in a stroke.
106 * FT_STROKER_LINECAP_BUTT ::
107 * The end of lines is rendered as a full stop on the last
110 * FT_STROKER_LINECAP_ROUND ::
111 * The end of lines is rendered as a half-circle around the
114 * FT_STROKER_LINECAP_SQUARE ::
115 * The end of lines is rendered as a square around the
120 FT_STROKER_LINECAP_BUTT = 0,
121 FT_STROKER_LINECAP_ROUND,
122 FT_STROKER_LINECAP_SQUARE
124 } FT_Stroker_LineCap;
127 /**************************************************************
133 * These values are used to select a given stroke border
134 * in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
137 * FT_STROKER_BORDER_LEFT ::
138 * Select the left border, relative to the drawing direction.
140 * FT_STROKER_BORDER_RIGHT ::
141 * Select the right border, relative to the drawing direction.
144 * Applications are generally interested in the `inside' and `outside'
145 * borders. However, there is no direct mapping between these and
146 * the `left' / `right' ones, since this really depends on the glyph's
147 * drawing orientation, which varies between font formats.
149 * You can however use @FT_Outline_GetInsideBorder and
150 * @FT_Outline_GetOutsideBorder to get these.
154 FT_STROKER_BORDER_LEFT = 0,
155 FT_STROKER_BORDER_RIGHT
160 /**************************************************************
163 * FT_Outline_GetInsideBorder
166 * Retrieve the @FT_StrokerBorder value corresponding to the
167 * `inside' borders of a given outline.
171 * The source outline handle.
174 * The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
177 FT_EXPORT( FT_StrokerBorder )
178 FT_Outline_GetInsideBorder( FT_Outline* outline );
181 /**************************************************************
184 * FT_Outline_GetOutsideBorder
187 * Retrieve the @FT_StrokerBorder value corresponding to the
188 * `outside' borders of a given outline.
192 * The source outline handle.
195 * The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
198 FT_EXPORT( FT_StrokerBorder )
199 FT_Outline_GetOutsideBorder( FT_Outline* outline );
202 /**************************************************************
208 * Create a new stroker object.
212 * The memory manager handle.
215 * A new stroker object handle. NULL in case of error.
218 * FreeType error code. 0 means success.
220 FT_EXPORT( FT_Error )
221 FT_Stroker_New( FT_Memory memory,
222 FT_Stroker *astroker );
225 /**************************************************************
231 * Reset a stroker object's attributes.
235 * The target stroker handle.
241 * The line cap style.
244 * The line join style.
247 * The miter limit for the FT_STROKER_LINEJOIN_MITER style,
248 * expressed as 16.16 fixed point value.
251 * The radius is expressed in the same units that the outline
255 FT_Stroker_Set( FT_Stroker stroker,
257 FT_Stroker_LineCap line_cap,
258 FT_Stroker_LineJoin line_join,
259 FT_Fixed miter_limit );
262 /**************************************************************
268 * Reset a stroker object without changing its attributes.
269 * You should call this function before beginning a new
270 * series of calls to @FT_Stroker_BeginSubPath or
271 * @FT_Stroker_EndSubPath.
275 * The target stroker handle.
278 FT_Stroker_Rewind( FT_Stroker stroker );
281 /**************************************************************
284 * FT_Stroker_ParseOutline
287 * A convenience function used to parse a whole outline with
288 * the stroker. The resulting outline(s) can be retrieved
289 * later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
293 * The target stroker handle.
296 * The source outline.
299 * A boolean. If TRUE, the outline is treated as an open path
300 * instead of a closed one.
303 * FreeType error code. 0 means success.
306 * If `opened' is 0 (the default), the outline is treated as a closed
307 * path, and the stroker will generate two distinct `border' outlines.
309 * If `opened' is 1, the outline is processed as an open path, and the
310 * stroker will generate a single `stroke' outline.
312 * This function calls @FT_Stroker_Rewind automatically.
314 FT_EXPORT( FT_Error )
315 FT_Stroker_ParseOutline( FT_Stroker stroker,
320 /**************************************************************
323 * FT_Stroker_BeginSubPath
326 * Start a new sub-path in the stroker.
330 * The target stroker handle.
333 * A pointer to the start vector.
336 * A boolean. If TRUE, the sub-path is treated as an open one.
339 * FreeType error code. 0 means success.
342 * This function is useful when you need to stroke a path that is
343 * not stored as a @FT_Outline object.
345 FT_EXPORT( FT_Error )
346 FT_Stroker_BeginSubPath( FT_Stroker stroker,
351 /**************************************************************
354 * FT_Stroker_EndSubPath
357 * Close the current sub-path in the stroker.
361 * The target stroker handle.
364 * FreeType error code. 0 means success.
367 * You should call this function after @FT_Stroker_BeginSubPath.
368 * If the subpath was not `opened', this function will `draw' a
369 * single line segment to the start position when needed.
371 FT_EXPORT( FT_Error )
372 FT_Stroker_EndSubPath( FT_Stroker stroker );
375 /**************************************************************
381 * `Draw' a single line segment in the stroker's current sub-path,
382 * from the last position.
386 * The target stroker handle.
389 * A pointer to the destination point.
392 * FreeType error code. 0 means success.
395 * You should call this function between @FT_Stroker_BeginSubPath and
396 * @FT_Stroker_EndSubPath.
398 FT_EXPORT( FT_Error )
399 FT_Stroker_LineTo( FT_Stroker stroker,
403 /**************************************************************
409 * `Draw; a single quadratic bezier in the stroker's current sub-path,
410 * from the last position.
414 * The target stroker handle.
417 * A pointer to a Bézier control point.
420 * A pointer to the destination point.
423 * FreeType error code. 0 means success.
426 * You should call this function between @FT_Stroker_BeginSubPath and
427 * @FT_Stroker_EndSubPath.
429 FT_EXPORT( FT_Error )
430 FT_Stroker_ConicTo( FT_Stroker stroker,
435 /**************************************************************
441 * `Draw' a single cubic Bézier in the stroker's current sub-path,
442 * from the last position.
446 * The target stroker handle.
449 * A pointer to the first Bézier control point.
452 * A pointer to second Bézier control point.
455 * A pointer to the destination point.
458 * FreeType error code. 0 means success.
461 * You should call this function between @FT_Stroker_BeginSubPath and
462 * @FT_Stroker_EndSubPath.
464 FT_EXPORT( FT_Error )
465 FT_Stroker_CubicTo( FT_Stroker stroker,
471 /**************************************************************
474 * FT_Stroker_GetBorderCounts
477 * Vall this function once you have finished parsing your paths
478 * with the stroker. It will return the number of points and
479 * contours necessary to export one of the `border' or `stroke'
480 * outlines generated by the stroker.
484 * The target stroker handle.
491 * The number of points.
494 * The number of contours.
497 * FreeType error code. 0 means success.
500 * When an outline, or a sub-path, is `closed', the stroker generates
501 * two independent `border' outlines, named `left' and `right'.
503 * When the outline, or a sub-path, is `opened', the stroker merges
504 * the `border' outlines with caps. The `left' border receives all
505 * points, while the `right' border becomes empty.
507 * Use the function @FT_Stroker_GetCounts instead if you want to
508 * retrieve the counts associated to both borders.
510 FT_EXPORT( FT_Error )
511 FT_Stroker_GetBorderCounts( FT_Stroker stroker,
512 FT_StrokerBorder border,
513 FT_UInt *anum_points,
514 FT_UInt *anum_contours );
517 /**************************************************************
520 * FT_Stroker_ExportBorder
523 * Call this function after @FT_Stroker_GetBorderCounts to
524 * export the corresponding border to your own @FT_Outline
527 * Note that this function will append the border points and
528 * contours to your outline, but will not try to resize its
533 * The target stroker handle.
539 * The target outline handle.
542 * Always call this function after @FT_Stroker_GetBorderCounts to
543 * get sure that there is enough room in your @FT_Outline object to
544 * receive all new data.
546 * When an outline, or a sub-path, is `closed', the stroker generates
547 * two independent `border' outlines, named `left' and `right'
549 * When the outline, or a sub-path, is `opened', the stroker merges
550 * the `border' outlines with caps. The `left' border receives all
551 * points, while the `right' border becomes empty.
553 * Use the function @FT_Stroker_Export instead if you want to
554 * retrieve all borders at once.
557 FT_Stroker_ExportBorder( FT_Stroker stroker,
558 FT_StrokerBorder border,
559 FT_Outline* outline );
562 /**************************************************************
565 * FT_Stroker_GetCounts
568 * Call this function once you have finished parsing your paths
569 * with the stroker. It returns the number of points and
570 * contours necessary to export all points/borders from the stroked
575 * The target stroker handle.
579 * The number of points.
582 * The number of contours.
585 * FreeType error code. 0 means success.
587 FT_EXPORT( FT_Error )
588 FT_Stroker_GetCounts( FT_Stroker stroker,
589 FT_UInt *anum_points,
590 FT_UInt *anum_contours );
593 /**************************************************************
599 * Call this function after @FT_Stroker_GetBorderCounts to
600 * export the all borders to your own @FT_Outline structure.
602 * Note that this function will append the border points and
603 * contours to your outline, but will not try to resize its
608 * The target stroker handle.
611 * The target outline handle.
614 FT_Stroker_Export( FT_Stroker stroker,
615 FT_Outline* outline );
618 /**************************************************************
624 * Destroy a stroker object.
628 * A stroker handle. Can be NULL.
631 FT_Stroker_Done( FT_Stroker stroker );
634 /**************************************************************
640 * Stroke a given outline glyph object with a given stroker.
643 * pglyph :: Source glyph handle on input, new glyph handle
651 * A Boolean. If TRUE, the source glyph object is destroyed
655 * FreeType error code. 0 means success.
658 * The source glyph is untouched in case of error.
660 FT_EXPORT( FT_Error )
661 FT_Glyph_Stroke( FT_Glyph *pglyph,
666 /**************************************************************
669 * FT_Glyph_StrokeBorder
672 * Stroke a given outline glyph object with a given stroker, but
673 * only return either its inside or outside border.
677 * Source glyph handle on input, new glyph handle on output.
684 * A Boolean. If TRUE, return the inside border, otherwise
685 * the outside border.
688 * A Boolean. If TRUE, the source glyph object is destroyed
692 * FreeType error code. 0 means success.
695 * The source glyph is untouched in case of error.
697 FT_EXPORT( FT_Error )
698 FT_Glyph_StrokeBorder( FT_Glyph *pglyph,
707 #endif /* __FT_STROKE_H__ */