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

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

First import

File size: 29.3 KB
Line 
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 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
34FT_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 Bezier 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 sucess.                              */
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_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 Bezier 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 Bezier 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  /* <InOut>                                                               */
318  /*    outline  :: A handle to the target outline.                        */
319  /*                                                                       */
320  /* <Input>                                                               */
321  /*    strength :: How strong the glyph is emboldened.  Expressed in      */
322  /*                26.6 pixel format.                                     */
323  /*                                                                       */
324  /* <Return>                                                              */
325  /*    FreeType error code.  0 means success.                             */
326  /*                                                                       */
327  FT_EXPORT_DEF( FT_Error )
328  FT_Outline_Embolden( FT_Outline*  outline,
329                       FT_Pos       strength );
330
331
332  /*************************************************************************/
333  /*                                                                       */
334  /* <Function>                                                            */
335  /*    FT_Outline_Reverse                                                 */
336  /*                                                                       */
337  /* <Description>                                                         */
338  /*    Reverses the drawing direction of an outline.  This is used to     */
339  /*    ensure consistent fill conventions for mirrored glyphs.            */
340  /*                                                                       */
341  /* <InOut>                                                               */
342  /*    outline :: A pointer to the target outline descriptor.             */
343  /*                                                                       */
344  /* <Note>                                                                */
345  /*    This functions toggles the bit flag `FT_OUTLINE_REVERSE_FILL' in   */
346  /*    the outline's `flags' field.                                       */
347  /*                                                                       */
348  /*    It shouldn't be used by a normal client application, unless it     */
349  /*    knows what it is doing.                                            */
350  /*                                                                       */
351  FT_EXPORT( void )
352  FT_Outline_Reverse( FT_Outline*  outline );
353
354
355  /*************************************************************************/
356  /*                                                                       */
357  /* <Function>                                                            */
358  /*    FT_Outline_Get_Bitmap                                              */
359  /*                                                                       */
360  /* <Description>                                                         */
361  /*    Renders an outline within a bitmap.  The outline's image is simply */
362  /*    OR-ed to the target bitmap.                                        */
363  /*                                                                       */
364  /* <Input>                                                               */
365  /*    library :: A handle to a FreeType library object.                  */
366  /*                                                                       */
367  /*    outline :: A pointer to the source outline descriptor.             */
368  /*                                                                       */
369  /* <Output>                                                              */
370  /*    abitmap :: A pointer to the target bitmap descriptor.              */
371  /*                                                                       */
372  /* <Return>                                                              */
373  /*    FreeType error code.  0 means success.                             */
374  /*                                                                       */
375  /* <Note>                                                                */
376  /*    This function does NOT CREATE the bitmap, it only renders an       */
377  /*    outline image within the one you pass to it!                       */
378  /*                                                                       */
379  /*    It will use the raster correponding to the default glyph format.   */
380  /*                                                                       */
381  FT_EXPORT( FT_Error )
382  FT_Outline_Get_Bitmap( FT_Library        library,
383                         FT_Outline*       outline,
384                         const FT_Bitmap  *abitmap );
385
386
387  /*************************************************************************/
388  /*                                                                       */
389  /* <Function>                                                            */
390  /*    FT_Outline_Render                                                  */
391  /*                                                                       */
392  /* <Description>                                                         */
393  /*    Renders an outline within a bitmap using the current scan-convert. */
394  /*    This functions uses an FT_Raster_Params structure as an argument,  */
395  /*    allowing advanced features like direct composition, translucency,  */
396  /*    etc.                                                               */
397  /*                                                                       */
398  /* <Input>                                                               */
399  /*    library :: A handle to a FreeType library object.                  */
400  /*                                                                       */
401  /*    outline :: A pointer to the source outline descriptor.             */
402  /*                                                                       */
403  /* <InOut>                                                               */
404  /*    params  :: A pointer to a FT_Raster_Params structure used to       */
405  /*               describe the rendering operation.                       */
406  /*                                                                       */
407  /* <Return>                                                              */
408  /*    FreeType error code.  0 means success.                             */
409  /*                                                                       */
410  /* <Note>                                                                */
411  /*    You should know what you are doing and how FT_Raster_Params works  */
412  /*    to use this function.                                              */
413  /*                                                                       */
414  /*    The field `params.source' will be set to `outline' before the scan */
415  /*    converter is called, which means that the value you give to it is  */
416  /*    actually ignored.                                                  */
417  /*                                                                       */
418  FT_EXPORT( FT_Error )
419  FT_Outline_Render( FT_Library         library,
420                     FT_Outline*        outline,
421                     FT_Raster_Params*  params );
422
423
424 /**************************************************************************
425  *
426  * @enum:
427  *   FT_Orientation
428  * 
429  * @description:
430  *   A list of values used to describe an outline's contour orientation.
431  *
432  *   The TrueType and Postscript specifications use different conventions
433  *   to determine whether outline contours should be filled or unfilled.
434  *   
435  * @values:
436  *   FT_ORIENTATION_TRUETYPE ::
437  *     According to the TrueType specification, clockwise contours must
438  *     be filled, and counter-clockwise ones must be unfilled.
439  *
440  *   FT_ORIENTATION_POSTSCRIPT ::
441  *     According to the Postscript specification, counter-clockwise contours
442  *     must be filled, and clockwise ones must be unfilled.
443  *
444  *   FT_ORIENTATION_FILL_RIGHT ::
445  *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
446  *     remember that in TrueType, everything that is to the right of
447  *     the drawing direction of a contour must be filled.
448  *
449  *   FT_ORIENTATION_FILL_LEFT ::
450  *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
451  *     remember that in Postscript, everything that is to the left of
452  *     the drawing direction of a contour must be filled.
453  */
454  typedef enum
455  {
456    FT_ORIENTATION_TRUETYPE   = 0,
457    FT_ORIENTATION_POSTSCRIPT = 1,
458    FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
459    FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT
460 
461  } FT_Orientation;
462
463
464 /**************************************************************************
465  *
466  * @function:
467  *   FT_Outline_Get_Orientation
468  * 
469  * @description:
470  *   This function analyzes a glyph outline and tries to compute its
471  *   fill orientation (see @FT_Orientation).  This is done by computing
472  *   the direction of each global horizontal and/or vertical extrema
473  *   within the outline.
474  *
475  *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
476  *   outlines.
477  *
478  * @input:
479  *   outline ::
480  *     A handle to the source outline.
481  *
482  * @return:
483  *   The orientation.
484  *
485  */
486  FT_EXPORT( FT_Orientation )
487  FT_Outline_Get_Orientation( FT_Outline*  outline );
488
489
490  /* */
491
492
493FT_END_HEADER
494
495#endif /* __FTOUTLN_H__ */
496
497
498/* END */
Note: See TracBrowser for help on using the repository browser.