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