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