]>
Commit | Line | Data |
---|---|---|
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 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_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: */ |