XFA: merge patch from CL 817753002
[pdfium.git] / core / include / thirdparties / freetype / freetype / 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-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 "freetype.h"
26
27 #ifdef FREETYPE_H
28 #error "freetype.h of FreeType 1 has been loaded!"
29 #error "Please fix the directory search order for header files"
30 #error "so that freetype.h of FreeType 2 is found first."
31 #endif
32
33
34 FT_BEGIN_HEADER
35
36
37   /*************************************************************************/
38   /*                                                                       */
39   /* <Section>                                                             */
40   /*    outline_processing                                                 */
41   /*                                                                       */
42   /* <Title>                                                               */
43   /*    Outline Processing                                                 */
44   /*                                                                       */
45   /* <Abstract>                                                            */
46   /*    Functions to create, transform, and render vectorial glyph images. */
47   /*                                                                       */
48   /* <Description>                                                         */
49   /*    This section contains routines used to create and destroy scalable */
50   /*    glyph images known as `outlines'.  These can also be measured,     */
51   /*    transformed, and converted into bitmaps and pixmaps.               */
52   /*                                                                       */
53   /* <Order>                                                               */
54   /*    FT_Outline                                                         */
55   /*    FT_OUTLINE_FLAGS                                                   */
56   /*    FT_Outline_New                                                     */
57   /*    FT_Outline_Done                                                    */
58   /*    FT_Outline_Copy                                                    */
59   /*    FT_Outline_Translate                                               */
60   /*    FT_Outline_Transform                                               */
61   /*    FT_Outline_Embolden                                                */
62   /*    FT_Outline_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
550 FT_END_HEADER
551
552 #endif /* __FTOUTLN_H__ */
553
554
555 /* END */
556
557
558 /* Local Variables: */
559 /* coding: utf-8    */
560 /* End:             */