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