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