projects / reactos.git / blob
? search:


fd69f2829293255a204a56dfa0b46f4a26836375
[reactos.git] / reactos / lib / 3rdparty / freetype / include / freetype / ftoutln.h
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: */
A free Windows-compatible Operating System