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