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