source: trunk/poppler/freetype-2.1.10/include/freetype/ftstroke.h @ 2

Last change on this file since 2 was 2, checked in by Eugene Romanenko, 15 years ago

First import

File size: 19.0 KB
Line 
1/***************************************************************************/
2/*                                                                         */
3/*  ftstroke.h                                                             */
4/*                                                                         */
5/*    FreeType path stroker (specification).                               */
6/*                                                                         */
7/*  Copyright 2002, 2003, 2004 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
27FT_BEGIN_HEADER
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; i.e., the two joining lines
79   *     are extended until they intersect.
80   *
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).
86   */
87  typedef enum
88  {
89    FT_STROKER_LINEJOIN_ROUND = 0,
90    FT_STROKER_LINEJOIN_BEVEL,
91    FT_STROKER_LINEJOIN_MITER
92
93  } FT_Stroker_LineJoin;
94
95
96  /**************************************************************
97   *
98   * @enum:
99   *   FT_Stroker_LineCap
100   *
101   * @description:
102   *   These values determine how the end of opened sub-paths are
103   *   rendered in a stroke.
104   *
105   * @values:
106   *   FT_STROKER_LINECAP_BUTT ::
107   *     The end of lines is rendered as a full stop on the last
108   *     point itself.
109   *
110   *   FT_STROKER_LINECAP_ROUND ::
111   *     The end of lines is rendered as a half-circle around the
112   *     last point.
113   *
114   *   FT_STROKER_LINECAP_SQUARE ::
115   *     The end of lines is rendered as a square around the
116   *     last point.
117   */
118  typedef enum
119  {
120    FT_STROKER_LINECAP_BUTT = 0,
121    FT_STROKER_LINECAP_ROUND,
122    FT_STROKER_LINECAP_SQUARE
123
124  } FT_Stroker_LineCap;
125
126
127  /**************************************************************
128   *
129   * @enum:
130   *   FT_StrokerBorder
131   *
132   * @description:
133   *   These values are used to select a given stroke border
134   *   in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
135   *
136   * @values:
137   *   FT_STROKER_BORDER_LEFT ::
138   *     Select the left border, relative to the drawing direction.
139   *
140   *   FT_STROKER_BORDER_RIGHT ::
141   *     Select the right border, relative to the drawing direction.
142   *
143   * @note:
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.
148   *
149   *   You can however use @FT_Outline_GetInsideBorder and
150   *   @FT_Outline_GetOutsideBorder to get these.
151   */
152  typedef enum
153  {
154    FT_STROKER_BORDER_LEFT = 0,
155    FT_STROKER_BORDER_RIGHT
156
157  } FT_StrokerBorder;
158
159
160  /**************************************************************
161   *
162   * @function:
163   *   FT_Outline_GetInsideBorder
164   *
165   * @description:
166   *   Retrieve the @FT_StrokerBorder value corresponding to the
167   *   `inside' borders of a given outline.
168   *
169   * @input:
170   *   outline ::
171   *     The source outline handle.
172   *
173   * @return:
174   *   The border index.  @FT_STROKER_BORDER_LEFT for empty or invalid
175   *   outlines.
176   */
177  FT_EXPORT( FT_StrokerBorder )
178  FT_Outline_GetInsideBorder( FT_Outline*  outline );
179
180
181  /**************************************************************
182   *
183   * @function:
184   *   FT_Outline_GetOutsideBorder
185   *
186   * @description:
187   *   Retrieve the @FT_StrokerBorder value corresponding to the
188   *   `outside' borders of a given outline.
189   *
190   * @input:
191   *   outline ::
192   *     The source outline handle.
193   *
194   * @return:
195   *   The border index.  @FT_STROKER_BORDER_LEFT for empty or invalid
196   *   outlines.
197   */
198  FT_EXPORT( FT_StrokerBorder )
199  FT_Outline_GetOutsideBorder( FT_Outline*  outline );
200
201
202  /**************************************************************
203   *
204   * @function:
205   *   FT_Stroker_New
206   *
207   * @description:
208   *   Create a new stroker object.
209   *
210   * @input:
211   *   memory ::
212   *     The memory manager handle.
213   *
214   * @output:
215   *   A new stroker object handle.  NULL in case of error.
216   *
217   * @return:
218   *    FreeType error code.  0 means success.
219   */
220  FT_EXPORT( FT_Error )
221  FT_Stroker_New( FT_Memory    memory,
222                  FT_Stroker  *astroker );
223
224
225  /**************************************************************
226   *
227   * @function:
228   *   FT_Stroker_Set
229   *
230   * @description:
231   *   Reset a stroker object's attributes.
232   *
233   * @input:
234   *   stroker ::
235   *     The target stroker handle.
236   *
237   *   radius ::
238   *     The border radius.
239   *
240   *   line_cap ::
241   *     The line cap style.
242   *
243   *   line_join ::
244   *     The line join style.
245   *
246   *   miter_limit ::
247   *     The miter limit for the FT_STROKER_LINEJOIN_MITER style,
248   *     expressed as 16.16 fixed point value.
249   *
250   * @note:
251   *   The radius is expressed in the same units that the outline
252   *   coordinates.
253   */
254  FT_EXPORT( void )
255  FT_Stroker_Set( FT_Stroker           stroker,
256                  FT_Fixed             radius,
257                  FT_Stroker_LineCap   line_cap,
258                  FT_Stroker_LineJoin  line_join,
259                  FT_Fixed             miter_limit );
260
261
262  /**************************************************************
263   *
264   * @function:
265   *   FT_Stroker_Rewind
266   *
267   * @description:
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.
272   *
273   * @input:
274   *   stroker ::
275   *     The target stroker handle.
276   */
277  FT_EXPORT( void )
278  FT_Stroker_Rewind( FT_Stroker  stroker );
279
280
281  /**************************************************************
282   *
283   * @function:
284   *   FT_Stroker_ParseOutline
285   *
286   * @description:
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.
290   *
291   * @input:
292   *   stroker ::
293   *     The target stroker handle.
294   *
295   *   outline ::
296   *     The source outline.
297   *
298   *   opened ::
299   *     A boolean.  If TRUE, the outline is treated as an open path
300   *     instead of a closed one.
301   *
302   * @return:
303   *   FreeType error code.  0 means success.
304   *
305   * @note:
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.
308   *
309   *   If `opened' is 1, the outline is processed as an open path, and the
310   *   stroker will generate a single `stroke' outline.
311   *
312   *   This function calls @FT_Stroker_Rewind automatically.
313   */
314  FT_EXPORT( FT_Error )
315  FT_Stroker_ParseOutline( FT_Stroker   stroker,
316                           FT_Outline*  outline,
317                           FT_Bool      opened );
318
319
320  /**************************************************************
321   *
322   * @function:
323   *   FT_Stroker_BeginSubPath
324   *
325   * @description:
326   *   Start a new sub-path in the stroker.
327   *
328   * @input:
329   *   stroker ::
330   *     The target stroker handle.
331   *
332   *   to ::
333   *     A pointer to the start vector.
334   *
335   *   open ::
336   *     A boolean.  If TRUE, the sub-path is treated as an open one.
337   *
338   * @return:
339   *   FreeType error code.  0 means success.
340   *
341   * @note:
342   *   This function is useful when you need to stroke a path that is
343   *   not stored as a @FT_Outline object.
344   */
345  FT_EXPORT( FT_Error )
346  FT_Stroker_BeginSubPath( FT_Stroker  stroker,
347                           FT_Vector*  to,
348                           FT_Bool     open );
349
350
351  /**************************************************************
352   *
353   * @function:
354   *   FT_Stroker_EndSubPath
355   *
356   * @description:
357   *   Close the current sub-path in the stroker.
358   *
359   * @input:
360   *   stroker ::
361   *     The target stroker handle.
362   *
363   * @return:
364   *   FreeType error code.  0 means success.
365   *
366   * @note:
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.
370   */
371  FT_EXPORT( FT_Error )
372  FT_Stroker_EndSubPath( FT_Stroker  stroker );
373
374
375  /**************************************************************
376   *
377   * @function:
378   *   FT_Stroker_LineTo
379   *
380   * @description:
381   *   `Draw' a single line segment in the stroker's current sub-path,
382   *   from the last position.
383   *
384   * @input:
385   *   stroker ::
386   *     The target stroker handle.
387   *
388   *   to ::
389   *     A pointer to the destination point.
390   *
391   * @return:
392   *   FreeType error code.  0 means success.
393   *
394   * @note:
395   *   You should call this function between @FT_Stroker_BeginSubPath and
396   *   @FT_Stroker_EndSubPath.
397   */
398  FT_EXPORT( FT_Error )
399  FT_Stroker_LineTo( FT_Stroker  stroker,
400                     FT_Vector*  to );
401
402
403  /**************************************************************
404   *
405   * @function:
406   *   FT_Stroker_ConicTo
407   *
408   * @description:
409   *   `Draw; a single quadratic bezier in the stroker's current sub-path,
410   *   from the last position.
411   *
412   * @input:
413   *   stroker ::
414   *     The target stroker handle.
415   *
416   *   control ::
417   *     A pointer to a Bézier control point.
418   *
419   *   to ::
420   *     A pointer to the destination point.
421   *
422   * @return:
423   *   FreeType error code.  0 means success.
424   *
425   * @note:
426   *   You should call this function between @FT_Stroker_BeginSubPath and
427   *   @FT_Stroker_EndSubPath.
428   */
429  FT_EXPORT( FT_Error )
430  FT_Stroker_ConicTo( FT_Stroker  stroker,
431                      FT_Vector*  control,
432                      FT_Vector*  to );
433
434
435  /**************************************************************
436   *
437   * @function:
438   *   FT_Stroker_CubicTo
439   *
440   * @description:
441   *   `Draw' a single cubic Bézier in the stroker's current sub-path,
442   *   from the last position.
443   *
444   * @input:
445   *   stroker ::
446   *     The target stroker handle.
447   *
448   *   control1 ::
449   *     A pointer to the first Bézier control point.
450   *
451   *   control2 ::
452   *     A pointer to second Bézier control point.
453   *
454   *   to ::
455   *     A pointer to the destination point.
456   *
457   * @return:
458   *   FreeType error code.  0 means success.
459   *
460   * @note:
461   *   You should call this function between @FT_Stroker_BeginSubPath and
462   *   @FT_Stroker_EndSubPath.
463   */
464  FT_EXPORT( FT_Error )
465  FT_Stroker_CubicTo( FT_Stroker  stroker,
466                      FT_Vector*  control1,
467                      FT_Vector*  control2,
468                      FT_Vector*  to );
469
470
471  /**************************************************************
472   *
473   * @function:
474   *   FT_Stroker_GetBorderCounts
475   *
476   * @description:
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.
481   *
482   * @input:
483   *   stroker ::
484   *     The target stroker handle.
485   *
486   *   border ::
487   *     The border index.
488   *
489   * @output:
490   *   anum_points ::
491   *     The number of points.
492   *
493   *   anum_contours ::
494   *     The number of contours.
495   *
496   * @return:
497   *   FreeType error code.  0 means success.
498   *
499   * @note:
500   *   When an outline, or a sub-path, is `closed', the stroker generates
501   *   two independent `border' outlines, named `left' and `right'.
502   *
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.
506   *
507   *   Use the function @FT_Stroker_GetCounts instead if you want to
508   *   retrieve the counts associated to both borders.
509   */
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 );
515
516
517  /**************************************************************
518   *
519   * @function:
520   *   FT_Stroker_ExportBorder
521   *
522   * @description:
523   *   Call this function after @FT_Stroker_GetBorderCounts to
524   *   export the corresponding border to your own @FT_Outline
525   *   structure.
526   *
527   *   Note that this function will append the border points and
528   *   contours to your outline, but will not try to resize its
529   *   arrays.
530   *
531   * @input:
532   *   stroker ::
533   *     The target stroker handle.
534   *
535   *   border ::
536   *     The border index.
537   *
538   *   outline ::
539   *     The target outline handle.
540   *
541   * @note:
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.
545   *
546   *   When an outline, or a sub-path, is `closed', the stroker generates
547   *   two independent `border' outlines, named `left' and `right'
548   *
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.
552   *
553   *   Use the function @FT_Stroker_Export instead if you want to
554   *   retrieve all borders at once.
555   */
556  FT_EXPORT( void )
557  FT_Stroker_ExportBorder( FT_Stroker        stroker,
558                           FT_StrokerBorder  border,
559                           FT_Outline*       outline );
560
561
562  /**************************************************************
563   *
564   * @function:
565   *   FT_Stroker_GetCounts
566   *
567   * @description:
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
571   *   outline/path.
572   *
573   * @input:
574   *   stroker ::
575   *     The target stroker handle.
576   *
577   * @output:
578   *   anum_points ::
579   *     The number of points.
580   *
581   *   anum_contours ::
582   *     The number of contours.
583   *
584   * @return:
585   *   FreeType error code.  0 means success.
586   */
587  FT_EXPORT( FT_Error )
588  FT_Stroker_GetCounts( FT_Stroker  stroker,
589                        FT_UInt    *anum_points,
590                        FT_UInt    *anum_contours );
591
592
593  /**************************************************************
594   *
595   * @function:
596   *   FT_Stroker_Export
597   *
598   * @description:
599   *   Call this function after @FT_Stroker_GetBorderCounts to
600   *   export the all borders to your own @FT_Outline structure.
601   *
602   *   Note that this function will append the border points and
603   *   contours to your outline, but will not try to resize its
604   *   arrays.
605   *
606   * @input:
607   *   stroker ::
608   *     The target stroker handle.
609   *
610   *   outline ::
611   *     The target outline handle.
612   */
613  FT_EXPORT( void )
614  FT_Stroker_Export( FT_Stroker   stroker,
615                     FT_Outline*  outline );
616
617
618  /**************************************************************
619   *
620   * @function:
621   *   FT_Stroker_Done
622   *
623   * @description:
624   *   Destroy a stroker object.
625   *
626   * @input:
627   *   stroker ::
628   *     A stroker handle.  Can be NULL.
629   */
630  FT_EXPORT( void )
631  FT_Stroker_Done( FT_Stroker  stroker );
632
633
634  /**************************************************************
635   *
636   * @function:
637   *   FT_Glyph_Stroke
638   *
639   * @description:
640   *   Stroke a given outline glyph object with a given stroker.
641   *
642   * @inout:
643   *   pglyph :: Source glyph handle on input, new glyph handle
644   *             on output.
645   *
646   * @input:
647   *   stroker ::
648   *     A stroker handle.
649   *
650   *   destroy ::
651   *     A Boolean.  If TRUE, the source glyph object is destroyed
652   *     on success.
653   *
654   * @return:
655   *    FreeType error code.  0 means success.
656   *
657   * @note:
658   *   The source glyph is untouched in case of error.
659   */
660  FT_EXPORT( FT_Error )
661  FT_Glyph_Stroke( FT_Glyph    *pglyph,
662                   FT_Stroker   stroker,
663                   FT_Bool      destroy );
664
665
666  /**************************************************************
667   *
668   * @function:
669   *   FT_Glyph_StrokeBorder
670   *
671   * @description:
672   *   Stroke a given outline glyph object with a given stroker, but
673   *   only return either its inside or outside border.
674   *
675   * @inout:
676   *   pglyph ::
677   *     Source glyph handle on input, new glyph handle on output.
678   *
679   * @input:
680   *   stroker ::
681   *     A stroker handle.
682   *
683   *   inside ::
684   *     A Boolean.  If TRUE, return the inside border, otherwise
685   *     the outside border.
686   *
687   *   destroy ::
688   *     A Boolean.  If TRUE, the source glyph object is destroyed
689   *     on success.
690   *
691   * @return:
692   *    FreeType error code.  0 means success.
693   *
694   * @note:
695   *   The source glyph is untouched in case of error.
696   */
697  FT_EXPORT( FT_Error )
698  FT_Glyph_StrokeBorder( FT_Glyph    *pglyph,
699                         FT_Stroker   stroker,
700                         FT_Bool      inside,
701                         FT_Bool      destroy );
702
703 /* */
704
705FT_END_HEADER
706
707#endif /* __FT_STROKE_H__ */
708
709
710/* END */
Note: See TracBrowser for help on using the repository browser.