Clutter Engine 0.0.1
Loading...
Searching...
No Matches
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-2016 by */
9/* David Turner, Robert Wilhelm, and Werner Lemberg. */
10/* */
11/* This file is part of the FreeType project, and may only be used, */
12/* modified, and distributed under the terms of the FreeType project */
13/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
14/* this file you indicate that you have read the license and */
15/* understand and accept it fully. */
16/* */
17/***************************************************************************/
18
19
20#ifndef FTOUTLN_H_
21#define FTOUTLN_H_
22
23
24#include <ft2build.h>
25#include FT_FREETYPE_H
26
27#ifdef FREETYPE_H
28#error "freetype.h of FreeType 1 has been loaded!"
29#error "Please fix the directory search order for header files"
30#error "so that freetype.h of FreeType 2 is found first."
31#endif
32
33
34FT_BEGIN_HEADER
35
36
37 /*************************************************************************/
38 /* */
39 /* <Section> */
40 /* outline_processing */
41 /* */
42 /* <Title> */
43 /* Outline Processing */
44 /* */
45 /* <Abstract> */
46 /* Functions to create, transform, and render vectorial glyph images. */
47 /* */
48 /* <Description> */
49 /* This section contains routines used to create and destroy scalable */
50 /* glyph images known as `outlines'. These can also be measured, */
51 /* transformed, and converted into bitmaps and pixmaps. */
52 /* */
53 /* <Order> */
54 /* FT_Outline */
55 /* FT_Outline_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->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) */
358 /* FT_Outline_Embolden( &face->glyph->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
564FT_END_HEADER
565
566#endif /* FTOUTLN_H_ */
567
568
569/* END */
570
571
572/* Local Variables: */
573/* coding: utf-8 */
574/* End: */
FT_BBox_
Definition ftimage.h:116
FT_Bitmap_
Definition ftimage.h:262
FT_Matrix_
Definition fttypes.h:386
FT_Outline_Funcs_
Definition ftimage.h:629
FT_Outline_
Definition ftimage.h:335
FT_Raster_Params_
Definition ftimage.h:1008
Generated by doxygen 1.12.0