PageRenderTime 481ms CodeModel.GetById 213ms app.highlight 64ms RepoModel.GetById 199ms app.codeStats 0ms

/src/compiler/android-ndk/jni/freetype/include/freetype/ftstroke.h

http://ftk.googlecode.com/
C++ Header | 716 lines | 90 code | 61 blank | 565 comment | 0 complexity | e976a7565afc12837e0191de677abc11 MD5 | raw file
  1/***************************************************************************/
  2/*                                                                         */
  3/*  ftstroke.h                                                             */
  4/*                                                                         */
  5/*    FreeType path stroker (specification).                               */
  6/*                                                                         */
  7/*  Copyright 2002, 2003, 2004, 2005, 2006, 2008, 2009 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  FT_Stroker_LineJoin_
 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  FT_Stroker_LineCap_
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 the
146   *   `left' and `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  FT_StrokerBorder_
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_RIGHT 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   *   library ::
212   *     FreeType library handle.
213   *
214   * @output:
215   *   astroker ::
216   *     A new stroker object handle.  NULL in case of error.
217   *
218   * @return:
219   *    FreeType error code.  0~means success.
220   */
221  FT_EXPORT( FT_Error )
222  FT_Stroker_New( FT_Library   library,
223                  FT_Stroker  *astroker );
224
225
226  /**************************************************************
227   *
228   * @function:
229   *   FT_Stroker_Set
230   *
231   * @description:
232   *   Reset a stroker object's attributes.
233   *
234   * @input:
235   *   stroker ::
236   *     The target stroker handle.
237   *
238   *   radius ::
239   *     The border radius.
240   *
241   *   line_cap ::
242   *     The line cap style.
243   *
244   *   line_join ::
245   *     The line join style.
246   *
247   *   miter_limit ::
248   *     The miter limit for the FT_STROKER_LINEJOIN_MITER style,
249   *     expressed as 16.16 fixed point value.
250   *
251   * @note:
252   *   The radius is expressed in the same units as the outline
253   *   coordinates.
254   */
255  FT_EXPORT( void )
256  FT_Stroker_Set( FT_Stroker           stroker,
257                  FT_Fixed             radius,
258                  FT_Stroker_LineCap   line_cap,
259                  FT_Stroker_LineJoin  line_join,
260                  FT_Fixed             miter_limit );
261
262
263  /**************************************************************
264   *
265   * @function:
266   *   FT_Stroker_Rewind
267   *
268   * @description:
269   *   Reset a stroker object without changing its attributes.
270   *   You should call this function before beginning a new
271   *   series of calls to @FT_Stroker_BeginSubPath or
272   *   @FT_Stroker_EndSubPath.
273   *
274   * @input:
275   *   stroker ::
276   *     The target stroker handle.
277   */
278  FT_EXPORT( void )
279  FT_Stroker_Rewind( FT_Stroker  stroker );
280
281
282  /**************************************************************
283   *
284   * @function:
285   *   FT_Stroker_ParseOutline
286   *
287   * @description:
288   *   A convenience function used to parse a whole outline with
289   *   the stroker.  The resulting outline(s) can be retrieved
290   *   later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
291   *
292   * @input:
293   *   stroker ::
294   *     The target stroker handle.
295   *
296   *   outline ::
297   *     The source outline.
298   *
299   *   opened ::
300   *     A boolean.  If~1, the outline is treated as an open path instead
301   *     of a closed one.
302   *
303   * @return:
304   *   FreeType error code.  0~means success.
305   *
306   * @note:
307   *   If `opened' is~0 (the default), the outline is treated as a closed
308   *   path, and the stroker generates two distinct `border' outlines.
309   *
310   *   If `opened' is~1, the outline is processed as an open path, and the
311   *   stroker generates a single `stroke' outline.
312   *
313   *   This function calls @FT_Stroker_Rewind automatically.
314   */
315  FT_EXPORT( FT_Error )
316  FT_Stroker_ParseOutline( FT_Stroker   stroker,
317                           FT_Outline*  outline,
318                           FT_Bool      opened );
319
320
321  /**************************************************************
322   *
323   * @function:
324   *   FT_Stroker_BeginSubPath
325   *
326   * @description:
327   *   Start a new sub-path in the stroker.
328   *
329   * @input:
330   *   stroker ::
331   *     The target stroker handle.
332   *
333   *   to ::
334   *     A pointer to the start vector.
335   *
336   *   open ::
337   *     A boolean.  If~1, the sub-path is treated as an open one.
338   *
339   * @return:
340   *   FreeType error code.  0~means success.
341   *
342   * @note:
343   *   This function is useful when you need to stroke a path that is
344   *   not stored as an @FT_Outline object.
345   */
346  FT_EXPORT( FT_Error )
347  FT_Stroker_BeginSubPath( FT_Stroker  stroker,
348                           FT_Vector*  to,
349                           FT_Bool     open );
350
351
352  /**************************************************************
353   *
354   * @function:
355   *   FT_Stroker_EndSubPath
356   *
357   * @description:
358   *   Close the current sub-path in the stroker.
359   *
360   * @input:
361   *   stroker ::
362   *     The target stroker handle.
363   *
364   * @return:
365   *   FreeType error code.  0~means success.
366   *
367   * @note:
368   *   You should call this function after @FT_Stroker_BeginSubPath.
369   *   If the subpath was not `opened', this function `draws' a
370   *   single line segment to the start position when needed.
371   */
372  FT_EXPORT( FT_Error )
373  FT_Stroker_EndSubPath( FT_Stroker  stroker );
374
375
376  /**************************************************************
377   *
378   * @function:
379   *   FT_Stroker_LineTo
380   *
381   * @description:
382   *   `Draw' a single line segment in the stroker's current sub-path,
383   *   from the last position.
384   *
385   * @input:
386   *   stroker ::
387   *     The target stroker handle.
388   *
389   *   to ::
390   *     A pointer to the destination point.
391   *
392   * @return:
393   *   FreeType error code.  0~means success.
394   *
395   * @note:
396   *   You should call this function between @FT_Stroker_BeginSubPath and
397   *   @FT_Stroker_EndSubPath.
398   */
399  FT_EXPORT( FT_Error )
400  FT_Stroker_LineTo( FT_Stroker  stroker,
401                     FT_Vector*  to );
402
403
404  /**************************************************************
405   *
406   * @function:
407   *   FT_Stroker_ConicTo
408   *
409   * @description:
410   *   `Draw' a single quadratic Bézier in the stroker's current sub-path,
411   *   from the last position.
412   *
413   * @input:
414   *   stroker ::
415   *     The target stroker handle.
416   *
417   *   control ::
418   *     A pointer to a Bézier control point.
419   *
420   *   to ::
421   *     A pointer to the destination point.
422   *
423   * @return:
424   *   FreeType error code.  0~means success.
425   *
426   * @note:
427   *   You should call this function between @FT_Stroker_BeginSubPath and
428   *   @FT_Stroker_EndSubPath.
429   */
430  FT_EXPORT( FT_Error )
431  FT_Stroker_ConicTo( FT_Stroker  stroker,
432                      FT_Vector*  control,
433                      FT_Vector*  to );
434
435
436  /**************************************************************
437   *
438   * @function:
439   *   FT_Stroker_CubicTo
440   *
441   * @description:
442   *   `Draw' a single cubic Bézier in the stroker's current sub-path,
443   *   from the last position.
444   *
445   * @input:
446   *   stroker ::
447   *     The target stroker handle.
448   *
449   *   control1 ::
450   *     A pointer to the first Bézier control point.
451   *
452   *   control2 ::
453   *     A pointer to second Bézier control point.
454   *
455   *   to ::
456   *     A pointer to the destination point.
457   *
458   * @return:
459   *   FreeType error code.  0~means success.
460   *
461   * @note:
462   *   You should call this function between @FT_Stroker_BeginSubPath and
463   *   @FT_Stroker_EndSubPath.
464   */
465  FT_EXPORT( FT_Error )
466  FT_Stroker_CubicTo( FT_Stroker  stroker,
467                      FT_Vector*  control1,
468                      FT_Vector*  control2,
469                      FT_Vector*  to );
470
471
472  /**************************************************************
473   *
474   * @function:
475   *   FT_Stroker_GetBorderCounts
476   *
477   * @description:
478   *   Call this function once you have finished parsing your paths
479   *   with the stroker.  It returns the number of points and
480   *   contours necessary to export one of the `border' or `stroke'
481   *   outlines generated by the stroker.
482   *
483   * @input:
484   *   stroker ::
485   *     The target stroker handle.
486   *
487   *   border ::
488   *     The border index.
489   *
490   * @output:
491   *   anum_points ::
492   *     The number of points.
493   *
494   *   anum_contours ::
495   *     The number of contours.
496   *
497   * @return:
498   *   FreeType error code.  0~means success.
499   *
500   * @note:
501   *   When an outline, or a sub-path, is `closed', the stroker generates
502   *   two independent `border' outlines, named `left' and `right'.
503   *
504   *   When the outline, or a sub-path, is `opened', the stroker merges
505   *   the `border' outlines with caps.  The `left' border receives all
506   *   points, while the `right' border becomes empty.
507   *
508   *   Use the function @FT_Stroker_GetCounts instead if you want to
509   *   retrieve the counts associated to both borders.
510   */
511  FT_EXPORT( FT_Error )
512  FT_Stroker_GetBorderCounts( FT_Stroker        stroker,
513                              FT_StrokerBorder  border,
514                              FT_UInt          *anum_points,
515                              FT_UInt          *anum_contours );
516
517
518  /**************************************************************
519   *
520   * @function:
521   *   FT_Stroker_ExportBorder
522   *
523   * @description:
524   *   Call this function after @FT_Stroker_GetBorderCounts to
525   *   export the corresponding border to your own @FT_Outline
526   *   structure.
527   *
528   *   Note that this function appends the border points and
529   *   contours to your outline, but does not try to resize its
530   *   arrays.
531   *
532   * @input:
533   *   stroker ::
534   *     The target stroker handle.
535   *
536   *   border ::
537   *     The border index.
538   *
539   *   outline ::
540   *     The target outline handle.
541   *
542   * @note:
543   *   Always call this function after @FT_Stroker_GetBorderCounts to
544   *   get sure that there is enough room in your @FT_Outline object to
545   *   receive all new data.
546   *
547   *   When an outline, or a sub-path, is `closed', the stroker generates
548   *   two independent `border' outlines, named `left' and `right'
549   *
550   *   When the outline, or a sub-path, is `opened', the stroker merges
551   *   the `border' outlines with caps. The `left' border receives all
552   *   points, while the `right' border becomes empty.
553   *
554   *   Use the function @FT_Stroker_Export instead if you want to
555   *   retrieve all borders at once.
556   */
557  FT_EXPORT( void )
558  FT_Stroker_ExportBorder( FT_Stroker        stroker,
559                           FT_StrokerBorder  border,
560                           FT_Outline*       outline );
561
562
563  /**************************************************************
564   *
565   * @function:
566   *   FT_Stroker_GetCounts
567   *
568   * @description:
569   *   Call this function once you have finished parsing your paths
570   *   with the stroker.  It returns the number of points and
571   *   contours necessary to export all points/borders from the stroked
572   *   outline/path.
573   *
574   * @input:
575   *   stroker ::
576   *     The target stroker handle.
577   *
578   * @output:
579   *   anum_points ::
580   *     The number of points.
581   *
582   *   anum_contours ::
583   *     The number of contours.
584   *
585   * @return:
586   *   FreeType error code.  0~means success.
587   */
588  FT_EXPORT( FT_Error )
589  FT_Stroker_GetCounts( FT_Stroker  stroker,
590                        FT_UInt    *anum_points,
591                        FT_UInt    *anum_contours );
592
593
594  /**************************************************************
595   *
596   * @function:
597   *   FT_Stroker_Export
598   *
599   * @description:
600   *   Call this function after @FT_Stroker_GetBorderCounts to
601   *   export all borders to your own @FT_Outline structure.
602   *
603   *   Note that this function appends the border points and
604   *   contours to your outline, but does not try to resize its
605   *   arrays.
606   *
607   * @input:
608   *   stroker ::
609   *     The target stroker handle.
610   *
611   *   outline ::
612   *     The target outline handle.
613   */
614  FT_EXPORT( void )
615  FT_Stroker_Export( FT_Stroker   stroker,
616                     FT_Outline*  outline );
617
618
619  /**************************************************************
620   *
621   * @function:
622   *   FT_Stroker_Done
623   *
624   * @description:
625   *   Destroy a stroker object.
626   *
627   * @input:
628   *   stroker ::
629   *     A stroker handle.  Can be NULL.
630   */
631  FT_EXPORT( void )
632  FT_Stroker_Done( FT_Stroker  stroker );
633
634
635  /**************************************************************
636   *
637   * @function:
638   *   FT_Glyph_Stroke
639   *
640   * @description:
641   *   Stroke a given outline glyph object with a given stroker.
642   *
643   * @inout:
644   *   pglyph ::
645   *     Source glyph handle on input, new glyph handle on output.
646   *
647   * @input:
648   *   stroker ::
649   *     A stroker handle.
650   *
651   *   destroy ::
652   *     A Boolean.  If~1, the source glyph object is destroyed
653   *     on success.
654   *
655   * @return:
656   *    FreeType error code.  0~means success.
657   *
658   * @note:
659   *   The source glyph is untouched in case of error.
660   */
661  FT_EXPORT( FT_Error )
662  FT_Glyph_Stroke( FT_Glyph    *pglyph,
663                   FT_Stroker   stroker,
664                   FT_Bool      destroy );
665
666
667  /**************************************************************
668   *
669   * @function:
670   *   FT_Glyph_StrokeBorder
671   *
672   * @description:
673   *   Stroke a given outline glyph object with a given stroker, but
674   *   only return either its inside or outside border.
675   *
676   * @inout:
677   *   pglyph ::
678   *     Source glyph handle on input, new glyph handle on output.
679   *
680   * @input:
681   *   stroker ::
682   *     A stroker handle.
683   *
684   *   inside ::
685   *     A Boolean.  If~1, return the inside border, otherwise
686   *     the outside border.
687   *
688   *   destroy ::
689   *     A Boolean.  If~1, the source glyph object is destroyed
690   *     on success.
691   *
692   * @return:
693   *    FreeType error code.  0~means success.
694   *
695   * @note:
696   *   The source glyph is untouched in case of error.
697   */
698  FT_EXPORT( FT_Error )
699  FT_Glyph_StrokeBorder( FT_Glyph    *pglyph,
700                         FT_Stroker   stroker,
701                         FT_Bool      inside,
702                         FT_Bool      destroy );
703
704 /* */
705
706FT_END_HEADER
707
708#endif /* __FT_STROKE_H__ */
709
710
711/* END */
712
713
714/* Local Variables: */
715/* coding: utf-8    */
716/* End:             */