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 | |
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 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 | |
575 | FT_END_HEADER |
576 | |
577 | #endif /* FTOUTLN_H_ */ |
578 | |
579 | |
580 | /* END */ |
581 | |
582 | |
583 | /* Local Variables: */ |
584 | /* coding: utf-8 */ |
585 | /* End: */ |
586 | |