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-2003, 2005-2012 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_EmboldenXY                                              */
63  /*    FT_Outline_Reverse                                                 */
64  /*    FT_Outline_Check                                                   */
65  /*                                                                       */
66  /*    FT_Outline_Get_CBox                                                */
67  /*    FT_Outline_Get_BBox                                                */
68  /*                                                                       */
69  /*    FT_Outline_Get_Bitmap                                              */
70  /*    FT_Outline_Render                                                  */
71  /*                                                                       */
72  /*    FT_Outline_Decompose                                               */
73  /*    FT_Outline_Funcs                                                   */
74  /*    FT_Outline_MoveTo_Func                                             */
75  /*    FT_Outline_LineTo_Func                                             */
76  /*    FT_Outline_ConicTo_Func                                            */
77  /*    FT_Outline_CubicTo_Func                                            */
78  /*                                                                       */
79  /*************************************************************************/
80
81
82  /*************************************************************************/
83  /*                                                                       */
84  /* <Function>                                                            */
85  /*    FT_Outline_Decompose                                               */
86  /*                                                                       */
87  /* <Description>                                                         */
88  /*    Walk over an outline's structure to decompose it into individual   */
89  /*    segments and Bézier arcs.  This function also emits `move to'      */
90  /*    operations to indicate the start 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  /*    Create 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 maximum number of points within the outline.    */
129  /*                   Must be smaller than or equal to 0xFFFF (65535).    */
130  /*                                                                       */
131  /*    numContours :: The maximum number of contours within the outline.  */
132  /*                   This value must be in the range 0 to `numPoints'.   */
133  /*                                                                       */
134  /* <Output>                                                              */
135  /*    anoutline   :: A handle to the new outline.                        */
136  /*                                                                       */
137  /* <Return>                                                              */
138  /*    FreeType error code.  0~means success.                             */
139  /*                                                                       */
140  /* <Note>                                                                */
141  /*    The reason why this function takes a `library' parameter is simply */
142  /*    to use the library's memory allocator.                             */
143  /*                                                                       */
144  FT_EXPORT( FT_Error )
145  FT_Outline_New( FT_Library   library,
146                  FT_UInt      numPoints,
147                  FT_Int       numContours,
148                  FT_Outline  *anoutline );
149
150
151  FT_EXPORT( FT_Error )
152  FT_Outline_New_Internal( FT_Memory    memory,
153                           FT_UInt      numPoints,
154                           FT_Int       numContours,
155                           FT_Outline  *anoutline );
156
157
158  /*************************************************************************/
159  /*                                                                       */
160  /* <Function>                                                            */
161  /*    FT_Outline_Done                                                    */
162  /*                                                                       */
163  /* <Description>                                                         */
164  /*    Destroy an outline created with @FT_Outline_New.                   */
165  /*                                                                       */
166  /* <Input>                                                               */
167  /*    library :: A handle of the library object used to allocate the     */
168  /*               outline.                                                */
169  /*                                                                       */
170  /*    outline :: A pointer to the outline object to be discarded.        */
171  /*                                                                       */
172  /* <Return>                                                              */
173  /*    FreeType error code.  0~means success.                             */
174  /*                                                                       */
175  /* <Note>                                                                */
176  /*    If the outline's `owner' field is not set, only the outline        */
177  /*    descriptor will be released.                                       */
178  /*                                                                       */
179  /*    The reason why this function takes an `library' parameter is       */
180  /*    simply to use ft_mem_free().                                       */
181  /*                                                                       */
182  FT_EXPORT( FT_Error )
183  FT_Outline_Done( FT_Library   library,
184                   FT_Outline*  outline );
185
186
187  FT_EXPORT( FT_Error )
188  FT_Outline_Done_Internal( FT_Memory    memory,
189                            FT_Outline*  outline );
190
191
192  /*************************************************************************/
193  /*                                                                       */
194  /* <Function>                                                            */
195  /*    FT_Outline_Check                                                   */
196  /*                                                                       */
197  /* <Description>                                                         */
198  /*    Check the contents of an outline descriptor.                       */
199  /*                                                                       */
200  /* <Input>                                                               */
201  /*    outline :: A handle to a source outline.                           */
202  /*                                                                       */
203  /* <Return>                                                              */
204  /*    FreeType error code.  0~means success.                             */
205  /*                                                                       */
206  FT_EXPORT( FT_Error )
207  FT_Outline_Check( FT_Outline*  outline );
208
209
210  /*************************************************************************/
211  /*                                                                       */
212  /* <Function>                                                            */
213  /*    FT_Outline_Get_CBox                                                */
214  /*                                                                       */
215  /* <Description>                                                         */
216  /*    Return an outline's `control box'.  The control box encloses all   */
217  /*    the outline's points, including Bézier control points.  Though it  */
218  /*    coincides with the exact bounding box for most glyphs, it can be   */
219  /*    slightly larger in some situations (like when rotating an outline  */
220  /*    which contains Bézier outside arcs).                               */
221  /*                                                                       */
222  /*    Computing the control box is very fast, while getting the bounding */
223  /*    box can take much more time as it needs to walk over all segments  */
224  /*    and arcs in the outline.  To get the latter, you can use the       */
225  /*    `ftbbox' component which is dedicated to this single task.         */
226  /*                                                                       */
227  /* <Input>                                                               */
228  /*    outline :: A pointer to the source outline descriptor.             */
229  /*                                                                       */
230  /* <Output>                                                              */
231  /*    acbox   :: The outline's control box.                              */
232  /*                                                                       */
233  /* <Note>                                                                */
234  /*    See @FT_Glyph_Get_CBox for a discussion of tricky fonts.           */
235  /*                                                                       */
236  FT_EXPORT( void )
237  FT_Outline_Get_CBox( const FT_Outline*  outline,
238                       FT_BBox           *acbox );
239
240
241  /*************************************************************************/
242  /*                                                                       */
243  /* <Function>                                                            */
244  /*    FT_Outline_Translate                                               */
245  /*                                                                       */
246  /* <Description>                                                         */
247  /*    Apply a simple translation to the points of an outline.            */
248  /*                                                                       */
249  /* <InOut>                                                               */
250  /*    outline :: A pointer to the target outline descriptor.             */
251  /*                                                                       */
252  /* <Input>                                                               */
253  /*    xOffset :: The horizontal offset.                                  */
254  /*                                                                       */
255  /*    yOffset :: The vertical offset.                                    */
256  /*                                                                       */
257  FT_EXPORT( void )
258  FT_Outline_Translate( const FT_Outline*  outline,
259                        FT_Pos             xOffset,
260                        FT_Pos             yOffset );
261
262
263  /*************************************************************************/
264  /*                                                                       */
265  /* <Function>                                                            */
266  /*    FT_Outline_Copy                                                    */
267  /*                                                                       */
268  /* <Description>                                                         */
269  /*    Copy an outline into another one.  Both objects must have the      */
270  /*    same sizes (number of points & number of contours) when this       */
271  /*    function is called.                                                */
272  /*                                                                       */
273  /* <Input>                                                               */
274  /*    source :: A handle to the source outline.                          */
275  /*                                                                       */
276  /* <Output>                                                              */
277  /*    target :: A handle to the target outline.                          */
278  /*                                                                       */
279  /* <Return>                                                              */
280  /*    FreeType error code.  0~means success.                             */
281  /*                                                                       */
282  FT_EXPORT( FT_Error )
283  FT_Outline_Copy( const FT_Outline*  source,
284                   FT_Outline        *target );
285
286
287  /*************************************************************************/
288  /*                                                                       */
289  /* <Function>                                                            */
290  /*    FT_Outline_Transform                                               */
291  /*                                                                       */
292  /* <Description>                                                         */
293  /*    Apply a simple 2x2 matrix to all of an outline's points.  Useful   */
294  /*    for applying rotations, slanting, flipping, etc.                   */
295  /*                                                                       */
296  /* <InOut>                                                               */
297  /*    outline :: A pointer to the target outline descriptor.             */
298  /*                                                                       */
299  /* <Input>                                                               */
300  /*    matrix  :: A pointer to the transformation matrix.                 */
301  /*                                                                       */
302  /* <Note>                                                                */
303  /*    You can use @FT_Outline_Translate if you need to translate the     */
304  /*    outline's points.                                                  */
305  /*                                                                       */
306  FT_EXPORT( void )
307  FT_Outline_Transform( const FT_Outline*  outline,
308                        const FT_Matrix*   matrix );
309
310
311  /*************************************************************************/
312  /*                                                                       */
313  /* <Function>                                                            */
314  /*    FT_Outline_Embolden                                                */
315  /*                                                                       */
316  /* <Description>                                                         */
317  /*    Embolden an outline.  The new outline will be at most 4~times      */
318  /*    `strength' pixels wider and higher.  You may think of the left and */
319  /*    bottom borders as unchanged.                                       */
320  /*                                                                       */
321  /*    Negative `strength' values to reduce the outline thickness are     */
322  /*    possible also.                                                     */
323  /*                                                                       */
324  /* <InOut>                                                               */
325  /*    outline  :: A handle to the target outline.                        */
326  /*                                                                       */
327  /* <Input>                                                               */
328  /*    strength :: How strong the glyph is emboldened.  Expressed in      */
329  /*                26.6 pixel format.                                     */
330  /*                                                                       */
331  /* <Return>                                                              */
332  /*    FreeType error code.  0~means success.                             */
333  /*                                                                       */
334  /* <Note>                                                                */
335  /*    The used algorithm to increase or decrease the thickness of the    */
336  /*    glyph doesn't change the number of points; this means that certain */
337  /*    situations like acute angles or intersections are sometimes        */
338  /*    handled incorrectly.                                               */
339  /*                                                                       */
340  /*    If you need `better' metrics values you should call                */
341  /*    @FT_Outline_Get_CBox or @FT_Outline_Get_BBox.                      */
342  /*                                                                       */
343  /*    Example call:                                                      */
344  /*                                                                       */
345  /*    {                                                                  */
346  /*      FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );                   */
347  /*      if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE )             */
348  /*        FT_Outline_Embolden( &face->slot->outline, strength );         */
349  /*    }                                                                  */
350  /*                                                                       */
351  FT_EXPORT( FT_Error )
352  FT_Outline_Embolden( FT_Outline*  outline,
353                       FT_Pos       strength );
354
355
356  /*************************************************************************/
357  /*                                                                       */
358  /* <Function>                                                            */
359  /*    FT_Outline_EmboldenXY                                              */
360  /*                                                                       */
361  /* <Description>                                                         */
362  /*    Embolden an outline.  The new outline will be `xstrength' pixels   */
363  /*    wider and `ystrength' pixels higher.  Otherwise, it is similar to  */
364  /*    @FT_Outline_Embolden, which uses the same strength in both         */
365  /*    directions.                                                        */
366  /*                                                                       */
367  FT_EXPORT( FT_Error )
368  FT_Outline_EmboldenXY( FT_Outline*  outline,
369                         FT_Pos       xstrength,
370                         FT_Pos       ystrength );
371
372
373  /*************************************************************************/
374  /*                                                                       */
375  /* <Function>                                                            */
376  /*    FT_Outline_Reverse                                                 */
377  /*                                                                       */
378  /* <Description>                                                         */
379  /*    Reverse the drawing direction of an outline.  This is used to      */
380  /*    ensure consistent fill conventions for mirrored glyphs.            */
381  /*                                                                       */
382  /* <InOut>                                                               */
383  /*    outline :: A pointer to the target outline descriptor.             */
384  /*                                                                       */
385  /* <Note>                                                                */
386  /*    This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in     */
387  /*    the outline's `flags' field.                                       */
388  /*                                                                       */
389  /*    It shouldn't be used by a normal client application, unless it     */
390  /*    knows what it is doing.                                            */
391  /*                                                                       */
392  FT_EXPORT( void )
393  FT_Outline_Reverse( FT_Outline*  outline );
394
395
396  /*************************************************************************/
397  /*                                                                       */
398  /* <Function>                                                            */
399  /*    FT_Outline_Get_Bitmap                                              */
400  /*                                                                       */
401  /* <Description>                                                         */
402  /*    Render an outline within a bitmap.  The outline's image is simply  */
403  /*    OR-ed to the target bitmap.                                        */
404  /*                                                                       */
405  /* <Input>                                                               */
406  /*    library :: A handle to a FreeType library object.                  */
407  /*                                                                       */
408  /*    outline :: A pointer to the source outline descriptor.             */
409  /*                                                                       */
410  /* <InOut>                                                               */
411  /*    abitmap :: A pointer to the target bitmap descriptor.              */
412  /*                                                                       */
413  /* <Return>                                                              */
414  /*    FreeType error code.  0~means success.                             */
415  /*                                                                       */
416  /* <Note>                                                                */
417  /*    This function does NOT CREATE the bitmap, it only renders an       */
418  /*    outline image within the one you pass to it!  Consequently, the    */
419  /*    various fields in `abitmap' should be set accordingly.             */
420  /*                                                                       */
421  /*    It will use the raster corresponding to the default glyph format.  */
422  /*                                                                       */
423  /*    The value of the `num_grays' field in `abitmap' is ignored.  If    */
424  /*    you select the gray-level rasterizer, and you want less than 256   */
425  /*    gray levels, you have to use @FT_Outline_Render directly.          */
426  /*                                                                       */
427  FT_EXPORT( FT_Error )
428  FT_Outline_Get_Bitmap( FT_Library        library,
429                         FT_Outline*       outline,
430                         const FT_Bitmap  *abitmap );
431
432
433  /*************************************************************************/
434  /*                                                                       */
435  /* <Function>                                                            */
436  /*    FT_Outline_Render                                                  */
437  /*                                                                       */
438  /* <Description>                                                         */
439  /*    Render an outline within a bitmap using the current scan-convert.  */
440  /*    This function uses an @FT_Raster_Params structure as an argument,  */
441  /*    allowing advanced features like direct composition, translucency,  */
442  /*    etc.                                                               */
443  /*                                                                       */
444  /* <Input>                                                               */
445  /*    library :: A handle to a FreeType library object.                  */
446  /*                                                                       */
447  /*    outline :: A pointer to the source outline descriptor.             */
448  /*                                                                       */
449  /* <InOut>                                                               */
450  /*    params  :: A pointer to an @FT_Raster_Params structure used to     */
451  /*               describe the rendering operation.                       */
452  /*                                                                       */
453  /* <Return>                                                              */
454  /*    FreeType error code.  0~means success.                             */
455  /*                                                                       */
456  /* <Note>                                                                */
457  /*    You should know what you are doing and how @FT_Raster_Params works */
458  /*    to use this function.                                              */
459  /*                                                                       */
460  /*    The field `params.source' will be set to `outline' before the scan */
461  /*    converter is called, which means that the value you give to it is  */
462  /*    actually ignored.                                                  */
463  /*                                                                       */
464  /*    The gray-level rasterizer always uses 256 gray levels.  If you     */
465  /*    want less gray levels, you have to provide your own span callback. */
466  /*    See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the   */
467  /*    @FT_Raster_Params structure for more details.                      */
468  /*                                                                       */
469  FT_EXPORT( FT_Error )
470  FT_Outline_Render( FT_Library         library,
471                     FT_Outline*        outline,
472                     FT_Raster_Params*  params );
473
474
475 /**************************************************************************
476  *
477  * @enum:
478  *   FT_Orientation
479  *
480  * @description:
481  *   A list of values used to describe an outline's contour orientation.
482  *
483  *   The TrueType and PostScript specifications use different conventions
484  *   to determine whether outline contours should be filled or unfilled.
485  *
486  * @values:
487  *   FT_ORIENTATION_TRUETYPE ::
488  *     According to the TrueType specification, clockwise contours must
489  *     be filled, and counter-clockwise ones must be unfilled.
490  *
491  *   FT_ORIENTATION_POSTSCRIPT ::
492  *     According to the PostScript specification, counter-clockwise contours
493  *     must be filled, and clockwise ones must be unfilled.
494  *
495  *   FT_ORIENTATION_FILL_RIGHT ::
496  *     This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
497  *     remember that in TrueType, everything that is to the right of
498  *     the drawing direction of a contour must be filled.
499  *
500  *   FT_ORIENTATION_FILL_LEFT ::
501  *     This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
502  *     remember that in PostScript, everything that is to the left of
503  *     the drawing direction of a contour must be filled.
504  *
505  *   FT_ORIENTATION_NONE ::
506  *     The orientation cannot be determined.  That is, different parts of
507  *     the glyph have different orientation.
508  *
509  */
510  typedef enum  FT_Orientation_
511  {
512    FT_ORIENTATION_TRUETYPE   = 0,
513    FT_ORIENTATION_POSTSCRIPT = 1,
514    FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
515    FT_ORIENTATION_FILL_LEFT  = FT_ORIENTATION_POSTSCRIPT,
516    FT_ORIENTATION_NONE
517
518  } FT_Orientation;
519
520
521 /**************************************************************************
522  *
523  * @function:
524  *   FT_Outline_Get_Orientation
525  *
526  * @description:
527  *   This function analyzes a glyph outline and tries to compute its
528  *   fill orientation (see @FT_Orientation).  This is done by computing
529  *   the direction of each global horizontal and/or vertical extrema
530  *   within the outline.
531  *
532  *   Note that this will return @FT_ORIENTATION_TRUETYPE for empty
533  *   outlines.
534  *
535  * @input:
536  *   outline ::
537  *     A handle to the source outline.
538  *
539  * @return:
540  *   The orientation.
541  *
542  */
543  FT_EXPORT( FT_Orientation )
544  FT_Outline_Get_Orientation( FT_Outline*  outline );
545
546
547  /* */
548
549
550FT_END_HEADER
551
552#endif /* __FTOUTLN_H__ */
553
554
555/* END */
556
557
558/* Local Variables: */
559/* coding: utf-8    */
560/* End:             */
561