PageRenderTime 65ms CodeModel.GetById 40ms app.highlight 16ms RepoModel.GetById 1ms app.codeStats 1ms

/src/freetype/include/freetype/ftstroke.h

https://bitbucket.org/cabalistic/ogredeps/
C++ Header | 741 lines | 92 code | 61 blank | 588 comment | 0 complexity | 952d10c536a28b2615f7c39be04a2e61 MD5 | raw file
  1/***************************************************************************/
  2/*                                                                         */
  3/*  ftstroke.h                                                             */
  4/*                                                                         */
  5/*    FreeType path stroker (specification).                               */
  6/*                                                                         */
  7/*  Copyright 2002-2006, 2008, 2009, 2011 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.  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  {
111    FT_STROKER_LINEJOIN_ROUND          = 0,
112    FT_STROKER_LINEJOIN_BEVEL          = 1,
113    FT_STROKER_LINEJOIN_MITER_VARIABLE = 2,
114    FT_STROKER_LINEJOIN_MITER          = FT_STROKER_LINEJOIN_MITER_VARIABLE,
115    FT_STROKER_LINEJOIN_MITER_FIXED    = 3
116
117  } FT_Stroker_LineJoin;
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  {
144    FT_STROKER_LINECAP_BUTT = 0,
145    FT_STROKER_LINECAP_ROUND,
146    FT_STROKER_LINECAP_SQUARE
147
148  } FT_Stroker_LineCap;
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  {
178    FT_STROKER_BORDER_LEFT = 0,
179    FT_STROKER_BORDER_RIGHT
180
181  } FT_StrokerBorder;
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   */
201  FT_EXPORT( FT_StrokerBorder )
202  FT_Outline_GetInsideBorder( FT_Outline*  outline );
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   */
222  FT_EXPORT( FT_StrokerBorder )
223  FT_Outline_GetOutsideBorder( FT_Outline*  outline );
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   */
245  FT_EXPORT( FT_Error )
246  FT_Stroker_New( FT_Library   library,
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   */
340  FT_EXPORT( FT_Error )
341  FT_Stroker_ParseOutline( FT_Stroker   stroker,
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   */
371  FT_EXPORT( FT_Error )
372  FT_Stroker_BeginSubPath( FT_Stroker  stroker,
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   */
397  FT_EXPORT( FT_Error )
398  FT_Stroker_EndSubPath( FT_Stroker  stroker );
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   */
424  FT_EXPORT( FT_Error )
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   */
455  FT_EXPORT( FT_Error )
456  FT_Stroker_ConicTo( FT_Stroker  stroker,
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   */
490  FT_EXPORT( FT_Error )
491  FT_Stroker_CubicTo( FT_Stroker  stroker,
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   */
536  FT_EXPORT( FT_Error )
537  FT_Stroker_GetBorderCounts( FT_Stroker        stroker,
538                              FT_StrokerBorder  border,
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 )
583  FT_Stroker_ExportBorder( FT_Stroker        stroker,
584                           FT_StrokerBorder  border,
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   */
613  FT_EXPORT( FT_Error )
614  FT_Stroker_GetCounts( FT_Stroker  stroker,
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  FT_EXPORT( FT_Error )
687  FT_Glyph_Stroke( FT_Glyph    *pglyph,
688                   FT_Stroker   stroker,
689                   FT_Bool      destroy );
690
691
692  /**************************************************************
693   *
694   * @function:
695   *   FT_Glyph_StrokeBorder
696   *
697   * @description:
698   *   Stroke a given outline glyph object with a given stroker, but
699   *   only return either its inside or outside border.
700   *
701   * @inout:
702   *   pglyph ::
703   *     Source glyph handle on input, new glyph handle on output.
704   *
705   * @input:
706   *   stroker ::
707   *     A stroker handle.
708   *
709   *   inside ::
710   *     A Boolean.  If~1, return the inside border, otherwise
711   *     the outside border.
712   *
713   *   destroy ::
714   *     A Boolean.  If~1, the source glyph object is destroyed
715   *     on success.
716   *
717   * @return:
718   *    FreeType error code.  0~means success.
719   *
720   * @note:
721   *   The source glyph is untouched in case of error.
722   */
723  FT_EXPORT( FT_Error )
724  FT_Glyph_StrokeBorder( FT_Glyph    *pglyph,
725                         FT_Stroker   stroker,
726                         FT_Bool      inside,
727                         FT_Bool      destroy );
728
729 /* */
730
731FT_END_HEADER
732
733#endif /* __FT_STROKE_H__ */
734
735
736/* END */
737
738
739/* Local Variables: */
740/* coding: utf-8    */
741/* End:             */