1 /***************************************************************************/
5 /* Support for the FT_Outline type used to store glyph shapes of */
6 /* most scalable font formats (specification). */
8 /* Copyright 1996-2016 by */
9 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
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. */
17 /***************************************************************************/
25 #include FT_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."
37 /*************************************************************************/
40 /* outline_processing */
43 /* Outline Processing */
46 /* Functions to create, transform, and render vectorial glyph images. */
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. */
58 /* FT_Outline_Translate */
59 /* FT_Outline_Transform */
60 /* FT_Outline_Embolden */
61 /* FT_Outline_EmboldenXY */
62 /* FT_Outline_Reverse */
63 /* FT_Outline_Check */
65 /* FT_Outline_Get_CBox */
66 /* FT_Outline_Get_BBox */
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 */
78 /* FT_Outline_Get_Orientation */
82 /*************************************************************************/
85 /*************************************************************************/
88 /* FT_Outline_Decompose */
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. */
96 /* outline :: A pointer to the source target. */
98 /* func_interface :: A table of `emitters', i.e., function pointers */
99 /* called during decomposition to indicate path */
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 */
109 /* FreeType error code. 0~means success. */
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). */
118 FT_EXPORT( FT_Error
)
119 FT_Outline_Decompose( FT_Outline
* outline
,
120 const FT_Outline_Funcs
* func_interface
,
124 /*************************************************************************/
130 /* Create a new outline of a given size. */
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. */
138 /* numPoints :: The maximum number of points within the outline. */
139 /* Must be smaller than or equal to 0xFFFF (65535). */
141 /* numContours :: The maximum number of contours within the outline. */
142 /* This value must be in the range 0 to `numPoints'. */
145 /* anoutline :: A handle to the new outline. */
148 /* FreeType error code. 0~means success. */
151 /* The reason why this function takes a `library' parameter is simply */
152 /* to use the library's memory allocator. */
154 FT_EXPORT( FT_Error
)
155 FT_Outline_New( FT_Library library
,
158 FT_Outline
*anoutline
);
161 FT_EXPORT( FT_Error
)
162 FT_Outline_New_Internal( FT_Memory memory
,
165 FT_Outline
*anoutline
);
168 /*************************************************************************/
171 /* FT_Outline_Done */
174 /* Destroy an outline created with @FT_Outline_New. */
177 /* library :: A handle of the library object used to allocate the */
180 /* outline :: A pointer to the outline object to be discarded. */
183 /* FreeType error code. 0~means success. */
186 /* If the outline's `owner' field is not set, only the outline */
187 /* descriptor will be released. */
189 /* The reason why this function takes an `library' parameter is */
190 /* simply to use ft_mem_free(). */
192 FT_EXPORT( FT_Error
)
193 FT_Outline_Done( FT_Library library
,
194 FT_Outline
* outline
);
197 FT_EXPORT( FT_Error
)
198 FT_Outline_Done_Internal( FT_Memory memory
,
199 FT_Outline
* outline
);
202 /*************************************************************************/
205 /* FT_Outline_Check */
208 /* Check the contents of an outline descriptor. */
211 /* outline :: A handle to a source outline. */
214 /* FreeType error code. 0~means success. */
216 FT_EXPORT( FT_Error
)
217 FT_Outline_Check( FT_Outline
* outline
);
220 /*************************************************************************/
223 /* FT_Outline_Get_CBox */
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). */
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. */
238 /* outline :: A pointer to the source outline descriptor. */
241 /* acbox :: The outline's control box. */
244 /* See @FT_Glyph_Get_CBox for a discussion of tricky fonts. */
247 FT_Outline_Get_CBox( const FT_Outline
* outline
,
251 /*************************************************************************/
254 /* FT_Outline_Translate */
257 /* Apply a simple translation to the points of an outline. */
260 /* outline :: A pointer to the target outline descriptor. */
263 /* xOffset :: The horizontal offset. */
265 /* yOffset :: The vertical offset. */
268 FT_Outline_Translate( const FT_Outline
* outline
,
273 /*************************************************************************/
276 /* FT_Outline_Copy */
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. */
284 /* source :: A handle to the source outline. */
287 /* target :: A handle to the target outline. */
290 /* FreeType error code. 0~means success. */
292 FT_EXPORT( FT_Error
)
293 FT_Outline_Copy( const FT_Outline
* source
,
294 FT_Outline
*target
);
297 /*************************************************************************/
300 /* FT_Outline_Transform */
303 /* Apply a simple 2x2 matrix to all of an outline's points. Useful */
304 /* for applying rotations, slanting, flipping, etc. */
307 /* outline :: A pointer to the target outline descriptor. */
310 /* matrix :: A pointer to the transformation matrix. */
313 /* You can use @FT_Outline_Translate if you need to translate the */
314 /* outline's points. */
317 FT_Outline_Transform( const FT_Outline
* outline
,
318 const FT_Matrix
* matrix
);
321 /*************************************************************************/
324 /* FT_Outline_Embolden */
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. */
331 /* Negative `strength' values to reduce the outline thickness are */
335 /* outline :: A handle to the target outline. */
338 /* strength :: How strong the glyph is emboldened. Expressed in */
339 /* 26.6 pixel format. */
342 /* FreeType error code. 0~means success. */
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. */
350 /* If you need `better' metrics values you should call */
351 /* @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. */
356 /* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); */
357 /* if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) */
358 /* FT_Outline_Embolden( &face->glyph->outline, strength ); */
361 /* To get meaningful results, font scaling values must be set with */
362 /* functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */
364 FT_EXPORT( FT_Error
)
365 FT_Outline_Embolden( FT_Outline
* outline
,
369 /*************************************************************************/
372 /* FT_Outline_EmboldenXY */
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 */
380 FT_EXPORT( FT_Error
)
381 FT_Outline_EmboldenXY( FT_Outline
* outline
,
386 /*************************************************************************/
389 /* FT_Outline_Reverse */
392 /* Reverse the drawing direction of an outline. This is used to */
393 /* ensure consistent fill conventions for mirrored glyphs. */
396 /* outline :: A pointer to the target outline descriptor. */
399 /* This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in */
400 /* the outline's `flags' field. */
402 /* It shouldn't be used by a normal client application, unless it */
403 /* knows what it is doing. */
406 FT_Outline_Reverse( FT_Outline
* outline
);
409 /*************************************************************************/
412 /* FT_Outline_Get_Bitmap */
415 /* Render an outline within a bitmap. The outline's image is simply */
416 /* OR-ed to the target bitmap. */
419 /* library :: A handle to a FreeType library object. */
421 /* outline :: A pointer to the source outline descriptor. */
424 /* abitmap :: A pointer to the target bitmap descriptor. */
427 /* FreeType error code. 0~means success. */
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. */
434 /* It will use the raster corresponding to the default glyph format. */
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. */
440 FT_EXPORT( FT_Error
)
441 FT_Outline_Get_Bitmap( FT_Library library
,
443 const FT_Bitmap
*abitmap
);
446 /*************************************************************************/
449 /* FT_Outline_Render */
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, */
458 /* library :: A handle to a FreeType library object. */
460 /* outline :: A pointer to the source outline descriptor. */
463 /* params :: A pointer to an @FT_Raster_Params structure used to */
464 /* describe the rendering operation. */
467 /* FreeType error code. 0~means success. */
470 /* You should know what you are doing and how @FT_Raster_Params works */
471 /* to use this function. */
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. */
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. */
482 FT_EXPORT( FT_Error
)
483 FT_Outline_Render( FT_Library library
,
485 FT_Raster_Params
* params
);
488 /**************************************************************************
494 * A list of values used to describe an outline's contour orientation.
496 * The TrueType and PostScript specifications use different conventions
497 * to determine whether outline contours should be filled or unfilled.
500 * FT_ORIENTATION_TRUETYPE ::
501 * According to the TrueType specification, clockwise contours must
502 * be filled, and counter-clockwise ones must be unfilled.
504 * FT_ORIENTATION_POSTSCRIPT ::
505 * According to the PostScript specification, counter-clockwise contours
506 * must be filled, and clockwise ones must be unfilled.
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.
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.
518 * FT_ORIENTATION_NONE ::
519 * The orientation cannot be determined. That is, different parts of
520 * the glyph have different orientation.
523 typedef enum FT_Orientation_
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
,
534 /**************************************************************************
537 * FT_Outline_Get_Orientation
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.
547 * Note that this will return @FT_ORIENTATION_TRUETYPE for empty
552 * A handle to the source outline.
558 FT_EXPORT( FT_Orientation
)
559 FT_Outline_Get_Orientation( FT_Outline
* outline
);
566 #endif /* FTOUTLN_H_ */
572 /* Local Variables: */