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 (C) 1996-2021 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 <freetype/freetype.h>
25
26#ifdef FREETYPE_H
27#error "freetype.h of FreeType 1 has been loaded!"
28#error "Please fix the directory search order for header files"
29#error "so that freetype.h of FreeType 2 is found first."
30#endif
31
32
33FT_BEGIN_HEADER
34
35
36 /**************************************************************************
37 *
38 * @section:
39 * outline_processing
40 *
41 * @title:
42 * Outline Processing
43 *
44 * @abstract:
45 * Functions to create, transform, and render vectorial glyph images.
46 *
47 * @description:
48 * This section contains routines used to create and destroy scalable
49 * glyph images known as 'outlines'. These can also be measured,
50 * transformed, and converted into bitmaps and pixmaps.
51 *
52 * @order:
53 * FT_Outline
54 * FT_Outline_New
55 * FT_Outline_Done
56 * FT_Outline_Copy
57 * FT_Outline_Translate
58 * FT_Outline_Transform
59 * FT_Outline_Embolden
60 * FT_Outline_EmboldenXY
61 * FT_Outline_Reverse
62 * FT_Outline_Check
63 *
64 * FT_Outline_Get_CBox
65 * FT_Outline_Get_BBox
66 *
67 * FT_Outline_Get_Bitmap
68 * FT_Outline_Render
69 * FT_Outline_Decompose
70 * FT_Outline_Funcs
71 * FT_Outline_MoveToFunc
72 * FT_Outline_LineToFunc
73 * FT_Outline_ConicToFunc
74 * FT_Outline_CubicToFunc
75 *
76 * FT_Orientation
77 * FT_Outline_Get_Orientation
78 *
79 * FT_OUTLINE_XXX
80 *
81 */
82
83
84 /**************************************************************************
85 *
86 * @function:
87 * FT_Outline_Decompose
88 *
89 * @description:
90 * Walk over an outline's structure to decompose it into individual
91 * segments and Bezier arcs. This function also emits 'move to'
92 * operations to indicate the start of new contours in the outline.
93 *
94 * @input:
95 * outline ::
96 * A pointer to the source target.
97 *
98 * func_interface ::
99 * A table of 'emitters', i.e., function pointers called during
100 * decomposition to indicate path operations.
101 *
102 * @inout:
103 * user ::
104 * A typeless pointer that is passed to each emitter during the
105 * decomposition. It can be 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 'move
113 * to' operation followed by 'line to' to the same point. In most cases,
114 * it is best to filter this out before using the outline for stroking
115 * purposes (otherwise it would result in a visible dot when round caps
116 * are used).
117 *
118 * Similarly, the function returns success for an empty outline also
119 * (doing nothing, this is, not calling any emitter); if necessary, you
120 * should filter this out, too.
121 */
122 FT_EXPORT( FT_Error )
123 FT_Outline_Decompose( FT_Outline* outline,
124 const FT_Outline_Funcs* func_interface,
125 void* user );
126
127
128 /**************************************************************************
129 *
130 * @function:
131 * FT_Outline_New
132 *
133 * @description:
134 * Create a new outline of a given size.
135 *
136 * @input:
137 * library ::
138 * A handle to the library object from where the outline is allocated.
139 * Note however that the new outline will **not** necessarily be
140 * **freed**, when destroying the library, by @FT_Done_FreeType.
141 *
142 * numPoints ::
143 * The maximum number of points within the outline. Must be smaller
144 * than or equal to 0xFFFF (65535).
145 *
146 * numContours ::
147 * The maximum number of contours within the outline. This value must
148 * be in the range 0 to `numPoints`.
149 *
150 * @output:
151 * anoutline ::
152 * A handle to the new outline.
153 *
154 * @return:
155 * FreeType error code. 0~means success.
156 *
157 * @note:
158 * The reason why this function takes a `library` parameter is simply to
159 * use the library's memory allocator.
160 */
161 FT_EXPORT( FT_Error )
162 FT_Outline_New( FT_Library library,
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 ::
178 * A handle of the library object used to allocate the outline.
179 *
180 * outline ::
181 * A pointer to the outline object to be discarded.
182 *
183 * @return:
184 * FreeType error code. 0~means success.
185 *
186 * @note:
187 * If the outline's 'owner' field is not set, only the outline descriptor
188 * will be released.
189 */
190 FT_EXPORT( FT_Error )
191 FT_Outline_Done( FT_Library library,
192 FT_Outline* outline );
193
194
195 /**************************************************************************
196 *
197 * @function:
198 * FT_Outline_Check
199 *
200 * @description:
201 * Check the contents of an outline descriptor.
202 *
203 * @input:
204 * outline ::
205 * A handle to a source outline.
206 *
207 * @return:
208 * FreeType error code. 0~means success.
209 *
210 * @note:
211 * An empty outline, or an outline with a single point only is also
212 * valid.
213 */
214 FT_EXPORT( FT_Error )
215 FT_Outline_Check( FT_Outline* outline );
216
217
218 /**************************************************************************
219 *
220 * @function:
221 * FT_Outline_Get_CBox
222 *
223 * @description:
224 * Return an outline's 'control box'. The control box encloses all the
225 * outline's points, including Bezier control points. Though it
226 * coincides with the exact bounding box for most glyphs, it can be
227 * slightly larger in some situations (like when rotating an outline that
228 * contains Bezier outside arcs).
229 *
230 * Computing the control box is very fast, while getting the bounding box
231 * can take much more time as it needs to walk over all segments and arcs
232 * in the outline. To get the latter, you can use the 'ftbbox'
233 * component, which is dedicated to this single task.
234 *
235 * @input:
236 * outline ::
237 * A pointer to the source outline descriptor.
238 *
239 * @output:
240 * acbox ::
241 * 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 ::
261 * A pointer to the target outline descriptor.
262 *
263 * @input:
264 * xOffset ::
265 * The horizontal offset.
266 *
267 * yOffset ::
268 * The vertical offset.
269 */
270 FT_EXPORT( void )
271 FT_Outline_Translate( const FT_Outline* outline,
272 FT_Pos xOffset,
273 FT_Pos yOffset );
274
275
276 /**************************************************************************
277 *
278 * @function:
279 * FT_Outline_Copy
280 *
281 * @description:
282 * Copy an outline into another one. Both objects must have the same
283 * sizes (number of points & number of contours) when this function is
284 * called.
285 *
286 * @input:
287 * source ::
288 * A handle to the source outline.
289 *
290 * @output:
291 * target ::
292 * A handle to the target outline.
293 *
294 * @return:
295 * FreeType error code. 0~means success.
296 */
297 FT_EXPORT( FT_Error )
298 FT_Outline_Copy( const FT_Outline* source,
299 FT_Outline *target );
300
301
302 /**************************************************************************
303 *
304 * @function:
305 * FT_Outline_Transform
306 *
307 * @description:
308 * Apply a simple 2x2 matrix to all of an outline's points. Useful for
309 * applying rotations, slanting, flipping, etc.
310 *
311 * @inout:
312 * outline ::
313 * A pointer to the target outline descriptor.
314 *
315 * @input:
316 * matrix ::
317 * A pointer to the transformation matrix.
318 *
319 * @note:
320 * You can use @FT_Outline_Translate if you need to translate the
321 * outline's points.
322 */
323 FT_EXPORT( void )
324 FT_Outline_Transform( const FT_Outline* outline,
325 const FT_Matrix* matrix );
326
327
328 /**************************************************************************
329 *
330 * @function:
331 * FT_Outline_Embolden
332 *
333 * @description:
334 * Embolden an outline. The new outline will be at most 4~times
335 * `strength` pixels wider and higher. You may think of the left and
336 * bottom borders as unchanged.
337 *
338 * Negative `strength` values to reduce the outline thickness are
339 * possible also.
340 *
341 * @inout:
342 * outline ::
343 * A handle to the target outline.
344 *
345 * @input:
346 * strength ::
347 * How strong the glyph is emboldened. Expressed in 26.6 pixel format.
348 *
349 * @return:
350 * FreeType error code. 0~means success.
351 *
352 * @note:
353 * The used algorithm to increase or decrease the thickness of the glyph
354 * doesn't change the number of points; this means that certain
355 * situations like acute angles or intersections are sometimes handled
356 * incorrectly.
357 *
358 * If you need 'better' metrics values you should call
359 * @FT_Outline_Get_CBox or @FT_Outline_Get_BBox.
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 * @example:
365 * ```
366 * FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );
367 *
368 * if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE )
369 * FT_Outline_Embolden( &face->glyph->outline, strength );
370 * ```
371 *
372 */
373 FT_EXPORT( FT_Error )
374 FT_Outline_Embolden( FT_Outline* outline,
375 FT_Pos strength );
376
377
378 /**************************************************************************
379 *
380 * @function:
381 * FT_Outline_EmboldenXY
382 *
383 * @description:
384 * Embolden an outline. The new outline will be `xstrength` pixels wider
385 * and `ystrength` pixels higher. Otherwise, it is similar to
386 * @FT_Outline_Embolden, which uses the same strength in both directions.
387 *
388 * @since:
389 * 2.4.10
390 */
391 FT_EXPORT( FT_Error )
392 FT_Outline_EmboldenXY( FT_Outline* outline,
393 FT_Pos xstrength,
394 FT_Pos ystrength );
395
396
397 /**************************************************************************
398 *
399 * @function:
400 * FT_Outline_Reverse
401 *
402 * @description:
403 * Reverse the drawing direction of an outline. This is used to ensure
404 * consistent fill conventions for mirrored glyphs.
405 *
406 * @inout:
407 * outline ::
408 * A pointer to the target outline descriptor.
409 *
410 * @note:
411 * This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in the
412 * outline's `flags` field.
413 *
414 * It shouldn't be used by a normal client application, unless it knows
415 * what it is doing.
416 */
417 FT_EXPORT( void )
418 FT_Outline_Reverse( FT_Outline* outline );
419
420
421 /**************************************************************************
422 *
423 * @function:
424 * FT_Outline_Get_Bitmap
425 *
426 * @description:
427 * Render an outline within a bitmap. The outline's image is simply
428 * OR-ed to the target bitmap.
429 *
430 * @input:
431 * library ::
432 * A handle to a FreeType library object.
433 *
434 * outline ::
435 * A pointer to the source outline descriptor.
436 *
437 * @inout:
438 * abitmap ::
439 * A pointer to the target bitmap descriptor.
440 *
441 * @return:
442 * FreeType error code. 0~means success.
443 *
444 * @note:
445 * This function does **not create** the bitmap, it only renders an
446 * outline image within the one you pass to it! Consequently, the
447 * various fields in `abitmap` should be set accordingly.
448 *
449 * It will use the raster corresponding to the default glyph format.
450 *
451 * The value of the `num_grays` field in `abitmap` is ignored. If you
452 * select the gray-level rasterizer, and you want less than 256 gray
453 * levels, you have to use @FT_Outline_Render directly.
454 */
455 FT_EXPORT( FT_Error )
456 FT_Outline_Get_Bitmap( FT_Library library,
457 FT_Outline* outline,
458 const FT_Bitmap *abitmap );
459
460
461 /**************************************************************************
462 *
463 * @function:
464 * FT_Outline_Render
465 *
466 * @description:
467 * Render an outline within a bitmap using the current scan-convert.
468 *
469 * @input:
470 * library ::
471 * A handle to a FreeType library object.
472 *
473 * outline ::
474 * A pointer to the source outline descriptor.
475 *
476 * @inout:
477 * params ::
478 * A pointer to an @FT_Raster_Params structure used to describe the
479 * rendering operation.
480 *
481 * @return:
482 * FreeType error code. 0~means success.
483 *
484 * @note:
485 * This advanced function uses @FT_Raster_Params as an argument.
486 * The field `params.source` will be set to `outline` before the scan
487 * converter is called, which means that the value you give to it is
488 * actually ignored. Either `params.target` must point to preallocated
489 * bitmap, or @FT_RASTER_FLAG_DIRECT must be set in `params.flags`
490 * allowing FreeType rasterizer to be used for direct composition,
491 * translucency, etc. See @FT_Raster_Params for more details.
492 */
493 FT_EXPORT( FT_Error )
494 FT_Outline_Render( FT_Library library,
495 FT_Outline* outline,
496 FT_Raster_Params* params );
497
498
499 /**************************************************************************
500 *
501 * @enum:
502 * FT_Orientation
503 *
504 * @description:
505 * A list of values used to describe an outline's contour orientation.
506 *
507 * The TrueType and PostScript specifications use different conventions
508 * to determine whether outline contours should be filled or unfilled.
509 *
510 * @values:
511 * FT_ORIENTATION_TRUETYPE ::
512 * According to the TrueType specification, clockwise contours must be
513 * filled, and counter-clockwise ones must be unfilled.
514 *
515 * FT_ORIENTATION_POSTSCRIPT ::
516 * According to the PostScript specification, counter-clockwise
517 * contours must be filled, and clockwise ones must be unfilled.
518 *
519 * FT_ORIENTATION_FILL_RIGHT ::
520 * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
521 * remember that in TrueType, everything that is to the right of the
522 * drawing direction of a contour must be filled.
523 *
524 * FT_ORIENTATION_FILL_LEFT ::
525 * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
526 * remember that in PostScript, everything that is to the left of the
527 * drawing direction of a contour must be filled.
528 *
529 * FT_ORIENTATION_NONE ::
530 * The orientation cannot be determined. That is, different parts of
531 * the glyph have different orientation.
532 *
533 */
534 typedef enum FT_Orientation_
535 {
536 FT_ORIENTATION_TRUETYPE = 0,
537 FT_ORIENTATION_POSTSCRIPT = 1,
538 FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
539 FT_ORIENTATION_FILL_LEFT = FT_ORIENTATION_POSTSCRIPT,
540 FT_ORIENTATION_NONE
541
542 } FT_Orientation;
543
544
545 /**************************************************************************
546 *
547 * @function:
548 * FT_Outline_Get_Orientation
549 *
550 * @description:
551 * This function analyzes a glyph outline and tries to compute its fill
552 * orientation (see @FT_Orientation). This is done by integrating the
553 * total area covered by the outline. The positive integral corresponds
554 * to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT is
555 * returned. The negative integral corresponds to the counter-clockwise
556 * orientation and @FT_ORIENTATION_TRUETYPE is returned.
557 *
558 * Note that this will return @FT_ORIENTATION_TRUETYPE for empty
559 * outlines.
560 *
561 * @input:
562 * outline ::
563 * A handle to the source outline.
564 *
565 * @return:
566 * The orientation.
567 *
568 */
569 FT_EXPORT( FT_Orientation )
570 FT_Outline_Get_Orientation( FT_Outline* outline );
571
572
573 /* */
574
575
576FT_END_HEADER
577
578#endif /* FTOUTLN_H_ */
579
580
581/* END */
582
583
584/* Local Variables: */
585/* coding: utf-8 */
586/* End: */
587

source code of include/freetype2/freetype/ftoutln.h