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