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