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