Rev Author Line No. Line
23 ovan 1 /***************************************************************************/
2 /*                                                                         */
3 /*  ftoutln.h                                                              */
4 /*                                                                         */
5 /*    Support for the FT_Outline type used to store glyph shapes of        */
6 /*    most scalable font formats (specification).                          */
7 /*                                                                         */
8 /*  Copyright 1996-2001, 2002, 2003, 2005, 2006, 2007 by                   */
9 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
10 /*                                                                         */
11 /*  This file is part of the FreeType project, and may only be used,       */
12 /*  modified, and distributed under the terms of the FreeType project      */
13 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
14 /*  this file you indicate that you have read the license and              */
15 /*  understand and accept it fully.                                        */
16 /*                                                                         */
17 /***************************************************************************/
18  
19  
20 #ifndef __FTOUTLN_H__
21 #define __FTOUTLN_H__
22  
23  
24 #include <ft2build.h>
25 #include FT_FREETYPE_H
26  
27 #ifdef FREETYPE_H
28 #error "freetype.h of FreeType 1 has been loaded!"
29 #error "Please fix the directory search order for header files"
30 #error "so that freetype.h of FreeType 2 is found first."
31 #endif
32  
33  
34 FT_BEGIN_HEADER
35  
36  
37   /*************************************************************************/
38   /*                                                                       */
39   /* <Section>                                                             */
40   /*    outline_processing                                                 */
41   /*                                                                       */
42   /* <Title>                                                               */
43   /*    Outline Processing                                                 */
44   /*                                                                       */
45   /* <Abstract>                                                            */
46   /*    Functions to create, transform, and render vectorial glyph images. */
47   /*                                                                       */
48   /* <Description>                                                         */
49   /*    This section contains routines used to create and destroy scalable */
50   /*    glyph images known as `outlines'.  These can also be measured,     */
51   /*    transformed, and converted into bitmaps and pixmaps.               */
52   /*                                                                       */
53   /* <Order>                                                               */
54   /*    FT_Outline                                                         */
55   /*    FT_OUTLINE_FLAGS                                                   */
56   /*    FT_Outline_New                                                     */
57   /*    FT_Outline_Done                                                    */
58   /*    FT_Outline_Copy                                                    */
59   /*    FT_Outline_Translate                                               */
60   /*    FT_Outline_Transform                                               */
61   /*    FT_Outline_Embolden                                                */
62   /*    FT_Outline_Reverse                                                 */
63   /*    FT_Outline_Check                                                   */
64   /*                                                                       */
65   /*    FT_Outline_Get_CBox                                                */
66   /*    FT_Outline_Get_BBox                                                */
67   /*                                                                       */
68   /*    FT_Outline_Get_Bitmap                                              */
69   /*    FT_Outline_Render                                                  */
70   /*                                                                       */
71   /*    FT_Outline_Decompose                                               */
72   /*    FT_Outline_Funcs                                                   */
73   /*    FT_Outline_MoveTo_Func                                             */
74   /*    FT_Outline_LineTo_Func                                             */
75   /*    FT_Outline_ConicTo_Func                                            */
76   /*    FT_Outline_CubicTo_Func                                            */
77   /*                                                                       */
78   /*************************************************************************/
79  
80  
81   /*************************************************************************/
82   /*                                                                       */
83   /* <Function>                                                            */
84   /*    FT_Outline_Decompose                                               */
85   /*                                                                       */
86   /* <Description>                                                         */
87   /*    Walks over an outline's structure to decompose it into individual  */
88   /*    segments and Bézier arcs.  This function is also able to emit      */
89   /*    `move to' and `close to' operations to indicate the start and end  */
90   /*    of new contours in the outline.                                    */
91   /*                                                                       */
92   /* <Input>                                                               */
93   /*    outline        :: A pointer to the source target.                  */
94   /*                                                                       */
95   /*    func_interface :: A table of `emitters', i.e,. function pointers   */
96   /*                      called during decomposition to indicate path     */
97   /*                      operations.                                      */
98   /*                                                                       */
99   /* <InOut>                                                               */
100   /*    user           :: A typeless pointer which is passed to each       */
101   /*                      emitter during the decomposition.  It can be     */
102   /*                      used to store the state during the               */
103   /*                      decomposition.                                   */
104   /*                                                                       */
105   /* <Return>                                                              */
106   /*    FreeType error code.  0 means success.                             */
107   /*                                                                       */
108   FT_EXPORT( FT_Error )
109   FT_Outline_Decompose( FT_Outline*              outline,
110                         const FT_Outline_Funcs*  func_interface,
111                         void*                    user );
112  
113  
114   /*************************************************************************/
115   /*                                                                       */
116   /* <Function>                                                            */
117   /*    FT_Outline_New                                                     */
118   /*                                                                       */
119   /* <Description>                                                         */
120   /*    Creates a new outline of a given size.                             */
121   /*                                                                       */
122   /* <Input>                                                               */
123   /*    library     :: A handle to the library object from where the       */
124   /*                   outline is allocated.  Note however that the new    */
125   /*                   outline will *not* necessarily be *freed*, when     */
126   /*                   destroying the library, by @FT_Done_FreeType.       */
127   /*                                                                       */
128   /*    numPoints   :: The maximal number of points within the outline.    */
129   /*                                                                       */
130   /*    numContours :: The maximal number of contours within the outline.  */
131   /*                                                                       */
132   /* <Output>                                                              */
133   /*    anoutline   :: A handle to the new outline.  NULL in case of       */
134   /*                   error.                                              */
135   /*                                                                       */
136   /* <Return>                                                              */
137   /*    FreeType error code.  0 means success.                             */
138   /*                                                                       */
139   /* <Note>                                                                */
140   /*    The reason why this function takes a `library' parameter is simply */
141   /*    to use the library's memory allocator.                             */
142   /*                                                                       */
143   FT_EXPORT( FT_Error )
144   FT_Outline_New( FT_Library   library,
145                   FT_UInt      numPoints,
146                   FT_Int       numContours,
147                   FT_Outline  *anoutline );
148  
149  
150   FT_EXPORT( FT_Error )
151   FT_Outline_New_Internal( FT_Memory    memory,
152                            FT_UInt      numPoints,
153                            FT_Int       numContours,
154                            FT_Outline  *anoutline );
155  
156  
157   /*************************************************************************/
158   /*                                                                       */
159   /* <Function>                                                            */
160   /*    FT_Outline_Done                                                    */
161   /*                                                                       */
162   /* <Description>                                                         */
163   /*    Destroys an outline created with @FT_Outline_New.                  */
164   /*                                                                       */
165   /* <Input>                                                               */
166   /*    library :: A handle of the library object used to allocate the     */
167   /*               outline.                                                */
168   /*                                                                       */
169   /*    outline :: A pointer to the outline object to be discarded.        */
170   /*                                                                       */
171   /* <Return>                                                              */
172   /*    FreeType error code.  0 means success.                             */
173   /*                                                                       */
174   /* <Note>                                                                */
175   /*    If the outline's `owner' field is not set, only the outline        */
176   /*    descriptor will be released.                                       */
177   /*                                                                       */
178   /*    The reason why this function takes an `library' parameter is       */
179   /*    simply to use ft_mem_free().                                       */
180   /*                                                                       */
181   FT_EXPORT( FT_Error )
182   FT_Outline_Done( FT_Library   library,
183                    FT_Outline*  outline );
184  
185  
186   FT_EXPORT( FT_Error )
187   FT_Outline_Done_Internal( FT_Memory    memory,
188                             FT_Outline*  outline );
189  
190  
191   /*************************************************************************/
192   /*                                                                       */
193   /* <Function>                                                            */
194   /*    FT_Outline_Check                                                   */
195   /*                                                                       */
196   /* <Description>                                                         */
197   /*    Check the contents of an outline descriptor.                       */
198   /*                                                                       */
199   /* <Input>                                                               */
200   /*    outline :: A handle to a source outline.                           */
201   /*                                                                       */
202   /* <Return>                                                              */
203   /*    FreeType error code.  0 means success.                             */
204   /*                                                                       */
205   FT_EXPORT( FT_Error )
206   FT_Outline_Check( FT_Outline*  outline );
207  
208  
209   /*************************************************************************/
210   /*                                                                       */
211   /* <Function>                                                            */
212   /*    FT_Outline_Get_CBox                                                */
213   /*                                                                       */
214   /* <Description>                                                         */
215   /*    Returns an outline's `control box'.  The control box encloses all  */
216   /*    the outline's points, including Bézier control points.  Though it  */
217   /*    coincides with the exact bounding box for most glyphs, it can be   */
218   /*    slightly larger in some situations (like when rotating an outline  */
219   /*    which contains Bézier outside arcs).                               */
220   /*                                                                       */
221   /*    Computing the control box is very fast, while getting the bounding */
222   /*    box can take much more time as it needs to walk over all segments  */
223   /*    and arcs in the outline.  To get the latter, you can use the       */
224   /*    `ftbbox' component which is dedicated to this single task.         */
225   /*                                                                       */
226   /* <Input>                                                               */
227   /*    outline :: A pointer to the source outline descriptor.             */
228   /*                                                                       */
229   /* <Output>                                                              */
230   /*    acbox   :: The outline's control box.                              */
231   /*                                                                       */
232   FT_EXPORT( void )
233   FT_Outline_Get_CBox( const FT_Outline*  outline,
234                        FT_BBox           *acbox );
235  
236  
237   /*************************************************************************/
238   /*                                                                       */
239   /* <Function>                                                            */
240   /*    FT_Outline_Translate                                               */
241   /*                                                                       */
242   /* <Description>                                                         */
243   /*    Applies a simple translation to the points of an outline.          */
244   /*                                                                       */
245   /* <InOut>                                                               */
246   /*    outline :: A pointer to the target outline descriptor.             */
247   /*                                                                       */
248   /* <Input>                                                               */
249   /*    xOffset :: The horizontal offset.                                  */
250   /*                                                                       */
251   /*    yOffset :: The vertical offset.                                    */
252   /*                                                                       */
253   FT_EXPORT( void )
254   FT_Outline_Translate( const FT_Outline*  outline,
255                         FT_Pos             xOffset,
256                         FT_Pos             yOffset );
257  
258  
259   /*************************************************************************/
260   /*                                                                       */
261   /* <Function>                                                            */
262   /*    FT_Outline_Copy                                                    */
263   /*                                                                       */
264   /* <Description>                                                         */
265   /*    Copies an outline into another one.  Both objects must have the    */
266   /*    same sizes (number of points & number of contours) when this       */
267   /*    function is called.                                                */
268   /*                                                                       */
269   /* <Input>                                                               */
270   /*    source :: A handle to the source outline.                          */
271   /*                                                                       */
272   /* <Output>                                                              */
273   /*    target :: A handle to the target outline.                          */
274   /*                                                                       */
275   /* <Return>                                                              */
276   /*    FreeType error code.  0 means success.                             */
277   /*                                                                       */
278   FT_EXPORT( FT_Error )
279   FT_Outline_Copy( const FT_Outline*  source,
280                    FT_Outline        *target );
281  
282  
283   /*************************************************************************/
284   /*                                                                       */
285   /* <Function>                                                            */
286   /*    FT_Outline_Transform                                               */
287   /*                                                                       */
288   /* <Description>                                                         */
289   /*    Applies a simple 2x2 matrix to all of an outline's points.  Useful */
290   /*    for applying rotations, slanting, flipping, etc.                   */
291   /*                                                                       */
292   /* <InOut>                                                               */
293   /*    outline :: A pointer to the target outline descriptor.             */
294   /*                                                                       */
295   /* <Input>                                                               */
296   /*    matrix  :: A pointer to the transformation matrix.                 */
297   /*                                                                       */
298   /* <Note>                                                                */
299   /*    You can use @FT_Outline_Translate if you need to translate the     */
300   /*    outline's points.                                                  */
301   /*                                                                       */
302   FT_EXPORT( void )
303   FT_Outline_Transform( const FT_Outline*  outline,
304                         const FT_Matrix*   matrix );
305  
306  
307   /*************************************************************************/
308   /*                                                                       */
309   /* <Function>                                                            */
310   /*    FT_Outline_Embolden                                                */
311   /*                                                                       */
312   /* <Description>                                                         */
313   /*    Emboldens an outline.  The new outline will be at most 4 times     */
314   /*    `strength' pixels wider and higher.  You may think of the left and */
315   /*    bottom borders as unchanged.                                       */
316   /*                                                                       */
317   /*    Negative `strength' values to reduce the outline thickness are     */
318   /*    possible also.                                                     */
319   /*                                                                       */
320   /* <InOut>                                                               */
321   /*    outline  :: A handle to the target outline.                        */
322   /*                                                                       */
323   /* <Input>                                                               */
324   /*    strength :: How strong the glyph is emboldened.  Expressed in      */
325   /*                26.6 pixel format.                                     */
326   /*                                                                       */
327   /* <Return>                                                              */
328   /*    FreeType error code.  0 means success.                             */
329   /*                                                                       */
330   /* <Note>                                                                */
331   /*    The used algorithm to increase or decrease the thickness of the    */
332   /*    glyph doesn't change the number of points; this means that certain */
333   /*    situations like acute angles or intersections are sometimes        */
334   /*    handled incorrectly.                                               */
335   /*                                                                       */
336   /*    Example call:                                                      */
337   /*                                                                       */
338   /*    {                                                                  */
339   /*      FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );                   */
340   /*      if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE )             */
341   /*        FT_Outline_Embolden( &face->slot->outline, strength );         */
342   /*    }                                                                  */
343   /*                                                                       */
344   FT_EXPORT( FT_Error )
345   FT_Outline_Embolden( FT_Outline*  outline,
346                        FT_Pos       strength );
347  
348  
349   /*************************************************************************/
350   /*                                                                       */
351   /* <Function>                                                            */
352   /*    FT_Outline_Reverse                                                 */
353   /*                                                                       */
354   /* <Description>                                                         */
355   /*    Reverses the drawing direction of an outline.  This is used to     */
356   /*    ensure consistent fill conventions for mirrored glyphs.            */
357   /*                                                                       */
358   /* <InOut>                                                               */
359   /*    outline :: A pointer to the target outline descriptor.             */
360   /*                                                                       */
361   /* <Note>                                                                */
362   /*    This functions toggles the bit flag @FT_OUTLINE_REVERSE_FILL in    */
363   /*    the outline's `flags' field.                                       */
364   /*                                                                       */
365   /*    It shouldn't be used by a normal client application, unless it     */
366   /*    knows what it is doing.                                            */
367   /*                                                                       */
368   FT_EXPORT( void )
369   FT_Outline_Reverse( FT_Outline*  outline );
370  
371  
372   /*************************************************************************/
373   /*                                                                       */
374   /* <Function>                                                            */
375   /*    FT_Outline_Get_Bitmap                                              */
376   /*                                                                       */
377   /* <Description>                                                         */
378   /*    Renders an outline within a bitmap.  The outline's image is simply */
379   /*    OR-ed to the target bitmap.                                        */
380   /*                                                                       */
381   /* <Input>                                                               */
382   /*    library :: A handle to a FreeType library object.                  */
383   /*                                                                       */
384   /*    outline :: A pointer to the source outline descriptor.             */
385   /*                                                                       */
386   /* <InOut>                                                               */
387   /*    abitmap :: A pointer to the target bitmap descriptor.              */
388   /*                                                                       */
389   /* <Return>                                                              */
390   /*    FreeType error code.  0 means success.                             */
391   /*                                                                       */
392   /* <Note>                                                                */
393   /*    This function does NOT CREATE the bitmap, it only renders an       */
394   /*    outline image within the one you pass to it!                       */
395   /*                                                                       */
396   /*    It will use the raster corresponding to the default glyph format.  */
397   /*                                                                       */
398   FT_EXPORT( FT_Error )
399   FT_Outline_Get_Bitmap( FT_Library        library,
400                          FT_Outline*       outline,
401                          const FT_Bitmap  *abitmap );
402  
403  
404   /*************************************************************************/
405   /*                                                                       */
406   /* <Function>                                                            */
407   /*    FT_Outline_Render                                                  */
408   /*                                                                       */
409   /* <Description>                                                         */
410   /*    Renders an outline within a bitmap using the current scan-convert. */
411   /*    This functions uses an @FT_Raster_Params structure as an argument, */
412   /*    allowing advanced features like direct composition, translucency,  */
413   /*    etc.                                                               */
414   /*                                                                       */
415   /* <Input>                                                               */
416   /*    library :: A handle to a FreeType library object.                  */
417   /*                                                                       */
418   /*    outline :: A pointer to the source outline descriptor.             */
419   /*                                                                       */
420   /* <InOut>                                                               */
421   /*    params  :: A pointer to an @FT_Raster_Params structure used to     */
422   /*               describe the rendering operation.                       */
423   /*                                                                       */
424   /* <Return>                                                              */
425   /*    FreeType error code.  0 means success.                             */
426   /*                                                                       */
427   /* <Note>                                                                */
428   /*    You should know what you are doing and how @FT_Raster_Params works */
429   /*    to use this function.                                              */
430   /*                                                                       */
431   /*    The field `params.source' will be set to `outline' before the scan */
432   /*    converter is called, which means that the value you give to it is  */
433   /*    actually ignored.                                                  */
434   /*                                                                       */
435   FT_EXPORT( FT_Error )
436   FT_Outline_Render( FT_Library         library,
437                      FT_Outline*        outline,
438                      FT_Raster_Params*  params );
439  
440  
441  /**************************************************************************
442   *
443   * @enum:
444   *   FT_Orientation
445   *
446   * @description:
447   *   A list of values used to describe an outline's contour orientation.
448   *
449   *   The TrueType and Postscript specifications use different conventions
450   *   to determine whether outline contours should be filled or unfilled.
451   *
452   * @values:
453   *   FT_ORIENTATION_TRUETYPE ::
454   *     According to the TrueType specification, clockwise contours must
455   *     be filled, and counter-clockwise ones must be unfilled.
456   *
457   *   FT_ORIENTATION_POSTSCRIPT ::
458   *     According to the Postscript specification, counter-clockwise contours
459   *     must be filled, and clockwise ones must be unfilled.
460   *
461   *   FT_ORIENTATION_FILL_RIGHT ::
462   *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
463   *     remember that in TrueType, everything that is to the right of
464   *     the drawing direction of a contour must be filled.
465   *
466   *   FT_ORIENTATION_FILL_LEFT ::
467   *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
468   *     remember that in Postscript, everything that is to the left of
469   *     the drawing direction of a contour must be filled.
470   *
471   *   FT_ORIENTATION_NONE ::
472   *     The orientation cannot be determined.  That is, different parts of
473   *     the glyph have different orientation.
474   *
475   */
476   typedef enum
477   {
478     FT_ORIENTATION_TRUETYPE   = 0,
479     FT_ORIENTATION_POSTSCRIPT = 1,
480     FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
481     FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT,
482     FT_ORIENTATION_NONE
483  
484   } FT_Orientation;
485  
486  
487  /**************************************************************************
488   *
489   * @function:
490   *   FT_Outline_Get_Orientation
491   *
492   * @description:
493   *   This function analyzes a glyph outline and tries to compute its
494   *   fill orientation (see @FT_Orientation).  This is done by computing
495   *   the direction of each global horizontal and/or vertical extrema
496   *   within the outline.
497   *
498   *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
499   *   outlines.
500   *
501   * @input:
502   *   outline ::
503   *     A handle to the source outline.
504   *
505   * @return:
506   *   The orientation.
507   *
508   */
509   FT_EXPORT( FT_Orientation )
510   FT_Outline_Get_Orientation( FT_Outline*  outline );
511  
512  
513   /* */
514  
515  
516 FT_END_HEADER
517  
518 #endif /* __FTOUTLN_H__ */
519  
520  
521 /* END */
522  
523  
524 /* Local Variables: */
525 /* coding: utf-8    */
526 /* End:             */