vrshoot
view libs/ft2static/freetype/ftstroke.h @ 1:e7ca128b8713
looks nice :)
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Sun, 02 Feb 2014 00:35:22 +0200 |
| parents | |
| children |
line source
1 /***************************************************************************/
2 /* */
3 /* ftstroke.h */
4 /* */
5 /* FreeType path stroker (specification). */
6 /* */
7 /* Copyright 2002, 2003, 2004, 2005, 2006, 2008, 2009 by */
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
9 /* */
10 /* This file is part of the FreeType project, and may only be used, */
11 /* modified, and distributed under the terms of the FreeType project */
12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
13 /* this file you indicate that you have read the license and */
14 /* understand and accept it fully. */
15 /* */
16 /***************************************************************************/
19 #ifndef __FT_STROKE_H__
20 #define __FT_STROKE_H__
22 #include <ft2build.h>
23 #include FT_OUTLINE_H
24 #include FT_GLYPH_H
27 FT_BEGIN_HEADER
30 /************************************************************************
31 *
32 * @section:
33 * glyph_stroker
34 *
35 * @title:
36 * Glyph Stroker
37 *
38 * @abstract:
39 * Generating bordered and stroked glyphs.
40 *
41 * @description:
42 * This component generates stroked outlines of a given vectorial
43 * glyph. It also allows you to retrieve the `outside' and/or the
44 * `inside' borders of the stroke.
45 *
46 * This can be useful to generate `bordered' glyph, i.e., glyphs
47 * displayed with a coloured (and anti-aliased) border around their
48 * shape.
49 */
52 /**************************************************************
53 *
54 * @type:
55 * FT_Stroker
56 *
57 * @description:
58 * Opaque handler to a path stroker object.
59 */
60 typedef struct FT_StrokerRec_* FT_Stroker;
63 /**************************************************************
64 *
65 * @enum:
66 * FT_Stroker_LineJoin
67 *
68 * @description:
69 * These values determine how two joining lines are rendered
70 * in a stroker.
71 *
72 * @values:
73 * FT_STROKER_LINEJOIN_ROUND ::
74 * Used to render rounded line joins. Circular arcs are used
75 * to join two lines smoothly.
76 *
77 * FT_STROKER_LINEJOIN_BEVEL ::
78 * Used to render beveled line joins; i.e., the two joining lines
79 * are extended until they intersect.
80 *
81 * FT_STROKER_LINEJOIN_MITER ::
82 * Same as beveled rendering, except that an additional line
83 * break is added if the angle between the two joining lines
84 * is too closed (this is useful to avoid unpleasant spikes
85 * in beveled rendering).
86 */
87 typedef enum FT_Stroker_LineJoin_
88 {
89 FT_STROKER_LINEJOIN_ROUND = 0,
90 FT_STROKER_LINEJOIN_BEVEL,
91 FT_STROKER_LINEJOIN_MITER
93 } FT_Stroker_LineJoin;
96 /**************************************************************
97 *
98 * @enum:
99 * FT_Stroker_LineCap
100 *
101 * @description:
102 * These values determine how the end of opened sub-paths are
103 * rendered in a stroke.
104 *
105 * @values:
106 * FT_STROKER_LINECAP_BUTT ::
107 * The end of lines is rendered as a full stop on the last
108 * point itself.
109 *
110 * FT_STROKER_LINECAP_ROUND ::
111 * The end of lines is rendered as a half-circle around the
112 * last point.
113 *
114 * FT_STROKER_LINECAP_SQUARE ::
115 * The end of lines is rendered as a square around the
116 * last point.
117 */
118 typedef enum FT_Stroker_LineCap_
119 {
120 FT_STROKER_LINECAP_BUTT = 0,
121 FT_STROKER_LINECAP_ROUND,
122 FT_STROKER_LINECAP_SQUARE
124 } FT_Stroker_LineCap;
127 /**************************************************************
128 *
129 * @enum:
130 * FT_StrokerBorder
131 *
132 * @description:
133 * These values are used to select a given stroke border
134 * in @FT_Stroker_GetBorderCounts and @FT_Stroker_ExportBorder.
135 *
136 * @values:
137 * FT_STROKER_BORDER_LEFT ::
138 * Select the left border, relative to the drawing direction.
139 *
140 * FT_STROKER_BORDER_RIGHT ::
141 * Select the right border, relative to the drawing direction.
142 *
143 * @note:
144 * Applications are generally interested in the `inside' and `outside'
145 * borders. However, there is no direct mapping between these and the
146 * `left' and `right' ones, since this really depends on the glyph's
147 * drawing orientation, which varies between font formats.
148 *
149 * You can however use @FT_Outline_GetInsideBorder and
150 * @FT_Outline_GetOutsideBorder to get these.
151 */
152 typedef enum FT_StrokerBorder_
153 {
154 FT_STROKER_BORDER_LEFT = 0,
155 FT_STROKER_BORDER_RIGHT
157 } FT_StrokerBorder;
160 /**************************************************************
161 *
162 * @function:
163 * FT_Outline_GetInsideBorder
164 *
165 * @description:
166 * Retrieve the @FT_StrokerBorder value corresponding to the
167 * `inside' borders of a given outline.
168 *
169 * @input:
170 * outline ::
171 * The source outline handle.
172 *
173 * @return:
174 * The border index. @FT_STROKER_BORDER_RIGHT for empty or invalid
175 * outlines.
176 */
177 FT_EXPORT( FT_StrokerBorder )
178 FT_Outline_GetInsideBorder( FT_Outline* outline );
181 /**************************************************************
182 *
183 * @function:
184 * FT_Outline_GetOutsideBorder
185 *
186 * @description:
187 * Retrieve the @FT_StrokerBorder value corresponding to the
188 * `outside' borders of a given outline.
189 *
190 * @input:
191 * outline ::
192 * The source outline handle.
193 *
194 * @return:
195 * The border index. @FT_STROKER_BORDER_LEFT for empty or invalid
196 * outlines.
197 */
198 FT_EXPORT( FT_StrokerBorder )
199 FT_Outline_GetOutsideBorder( FT_Outline* outline );
202 /**************************************************************
203 *
204 * @function:
205 * FT_Stroker_New
206 *
207 * @description:
208 * Create a new stroker object.
209 *
210 * @input:
211 * library ::
212 * FreeType library handle.
213 *
214 * @output:
215 * astroker ::
216 * A new stroker object handle. NULL in case of error.
217 *
218 * @return:
219 * FreeType error code. 0~means success.
220 */
221 FT_EXPORT( FT_Error )
222 FT_Stroker_New( FT_Library library,
223 FT_Stroker *astroker );
226 /**************************************************************
227 *
228 * @function:
229 * FT_Stroker_Set
230 *
231 * @description:
232 * Reset a stroker object's attributes.
233 *
234 * @input:
235 * stroker ::
236 * The target stroker handle.
237 *
238 * radius ::
239 * The border radius.
240 *
241 * line_cap ::
242 * The line cap style.
243 *
244 * line_join ::
245 * The line join style.
246 *
247 * miter_limit ::
248 * The miter limit for the FT_STROKER_LINEJOIN_MITER style,
249 * expressed as 16.16 fixed point value.
250 *
251 * @note:
252 * The radius is expressed in the same units as the outline
253 * coordinates.
254 */
255 FT_EXPORT( void )
256 FT_Stroker_Set( FT_Stroker stroker,
257 FT_Fixed radius,
258 FT_Stroker_LineCap line_cap,
259 FT_Stroker_LineJoin line_join,
260 FT_Fixed miter_limit );
263 /**************************************************************
264 *
265 * @function:
266 * FT_Stroker_Rewind
267 *
268 * @description:
269 * Reset a stroker object without changing its attributes.
270 * You should call this function before beginning a new
271 * series of calls to @FT_Stroker_BeginSubPath or
272 * @FT_Stroker_EndSubPath.
273 *
274 * @input:
275 * stroker ::
276 * The target stroker handle.
277 */
278 FT_EXPORT( void )
279 FT_Stroker_Rewind( FT_Stroker stroker );
282 /**************************************************************
283 *
284 * @function:
285 * FT_Stroker_ParseOutline
286 *
287 * @description:
288 * A convenience function used to parse a whole outline with
289 * the stroker. The resulting outline(s) can be retrieved
290 * later by functions like @FT_Stroker_GetCounts and @FT_Stroker_Export.
291 *
292 * @input:
293 * stroker ::
294 * The target stroker handle.
295 *
296 * outline ::
297 * The source outline.
298 *
299 * opened ::
300 * A boolean. If~1, the outline is treated as an open path instead
301 * of a closed one.
302 *
303 * @return:
304 * FreeType error code. 0~means success.
305 *
306 * @note:
307 * If `opened' is~0 (the default), the outline is treated as a closed
308 * path, and the stroker generates two distinct `border' outlines.
309 *
310 * If `opened' is~1, the outline is processed as an open path, and the
311 * stroker generates a single `stroke' outline.
312 *
313 * This function calls @FT_Stroker_Rewind automatically.
314 */
315 FT_EXPORT( FT_Error )
316 FT_Stroker_ParseOutline( FT_Stroker stroker,
317 FT_Outline* outline,
318 FT_Bool opened );
321 /**************************************************************
322 *
323 * @function:
324 * FT_Stroker_BeginSubPath
325 *
326 * @description:
327 * Start a new sub-path in the stroker.
328 *
329 * @input:
330 * stroker ::
331 * The target stroker handle.
332 *
333 * to ::
334 * A pointer to the start vector.
335 *
336 * open ::
337 * A boolean. If~1, the sub-path is treated as an open one.
338 *
339 * @return:
340 * FreeType error code. 0~means success.
341 *
342 * @note:
343 * This function is useful when you need to stroke a path that is
344 * not stored as an @FT_Outline object.
345 */
346 FT_EXPORT( FT_Error )
347 FT_Stroker_BeginSubPath( FT_Stroker stroker,
348 FT_Vector* to,
349 FT_Bool open );
352 /**************************************************************
353 *
354 * @function:
355 * FT_Stroker_EndSubPath
356 *
357 * @description:
358 * Close the current sub-path in the stroker.
359 *
360 * @input:
361 * stroker ::
362 * The target stroker handle.
363 *
364 * @return:
365 * FreeType error code. 0~means success.
366 *
367 * @note:
368 * You should call this function after @FT_Stroker_BeginSubPath.
369 * If the subpath was not `opened', this function `draws' a
370 * single line segment to the start position when needed.
371 */
372 FT_EXPORT( FT_Error )
373 FT_Stroker_EndSubPath( FT_Stroker stroker );
376 /**************************************************************
377 *
378 * @function:
379 * FT_Stroker_LineTo
380 *
381 * @description:
382 * `Draw' a single line segment in the stroker's current sub-path,
383 * from the last position.
384 *
385 * @input:
386 * stroker ::
387 * The target stroker handle.
388 *
389 * to ::
390 * A pointer to the destination point.
391 *
392 * @return:
393 * FreeType error code. 0~means success.
394 *
395 * @note:
396 * You should call this function between @FT_Stroker_BeginSubPath and
397 * @FT_Stroker_EndSubPath.
398 */
399 FT_EXPORT( FT_Error )
400 FT_Stroker_LineTo( FT_Stroker stroker,
401 FT_Vector* to );
404 /**************************************************************
405 *
406 * @function:
407 * FT_Stroker_ConicTo
408 *
409 * @description:
410 * `Draw' a single quadratic Bézier in the stroker's current sub-path,
411 * from the last position.
412 *
413 * @input:
414 * stroker ::
415 * The target stroker handle.
416 *
417 * control ::
418 * A pointer to a Bézier control point.
419 *
420 * to ::
421 * A pointer to the destination point.
422 *
423 * @return:
424 * FreeType error code. 0~means success.
425 *
426 * @note:
427 * You should call this function between @FT_Stroker_BeginSubPath and
428 * @FT_Stroker_EndSubPath.
429 */
430 FT_EXPORT( FT_Error )
431 FT_Stroker_ConicTo( FT_Stroker stroker,
432 FT_Vector* control,
433 FT_Vector* to );
436 /**************************************************************
437 *
438 * @function:
439 * FT_Stroker_CubicTo
440 *
441 * @description:
442 * `Draw' a single cubic Bézier in the stroker's current sub-path,
443 * from the last position.
444 *
445 * @input:
446 * stroker ::
447 * The target stroker handle.
448 *
449 * control1 ::
450 * A pointer to the first Bézier control point.
451 *
452 * control2 ::
453 * A pointer to second Bézier control point.
454 *
455 * to ::
456 * A pointer to the destination point.
457 *
458 * @return:
459 * FreeType error code. 0~means success.
460 *
461 * @note:
462 * You should call this function between @FT_Stroker_BeginSubPath and
463 * @FT_Stroker_EndSubPath.
464 */
465 FT_EXPORT( FT_Error )
466 FT_Stroker_CubicTo( FT_Stroker stroker,
467 FT_Vector* control1,
468 FT_Vector* control2,
469 FT_Vector* to );
472 /**************************************************************
473 *
474 * @function:
475 * FT_Stroker_GetBorderCounts
476 *
477 * @description:
478 * Call this function once you have finished parsing your paths
479 * with the stroker. It returns the number of points and
480 * contours necessary to export one of the `border' or `stroke'
481 * outlines generated by the stroker.
482 *
483 * @input:
484 * stroker ::
485 * The target stroker handle.
486 *
487 * border ::
488 * The border index.
489 *
490 * @output:
491 * anum_points ::
492 * The number of points.
493 *
494 * anum_contours ::
495 * The number of contours.
496 *
497 * @return:
498 * FreeType error code. 0~means success.
499 *
500 * @note:
501 * When an outline, or a sub-path, is `closed', the stroker generates
502 * two independent `border' outlines, named `left' and `right'.
503 *
504 * When the outline, or a sub-path, is `opened', the stroker merges
505 * the `border' outlines with caps. The `left' border receives all
506 * points, while the `right' border becomes empty.
507 *
508 * Use the function @FT_Stroker_GetCounts instead if you want to
509 * retrieve the counts associated to both borders.
510 */
511 FT_EXPORT( FT_Error )
512 FT_Stroker_GetBorderCounts( FT_Stroker stroker,
513 FT_StrokerBorder border,
514 FT_UInt *anum_points,
515 FT_UInt *anum_contours );
518 /**************************************************************
519 *
520 * @function:
521 * FT_Stroker_ExportBorder
522 *
523 * @description:
524 * Call this function after @FT_Stroker_GetBorderCounts to
525 * export the corresponding border to your own @FT_Outline
526 * structure.
527 *
528 * Note that this function appends the border points and
529 * contours to your outline, but does not try to resize its
530 * arrays.
531 *
532 * @input:
533 * stroker ::
534 * The target stroker handle.
535 *
536 * border ::
537 * The border index.
538 *
539 * outline ::
540 * The target outline handle.
541 *
542 * @note:
543 * Always call this function after @FT_Stroker_GetBorderCounts to
544 * get sure that there is enough room in your @FT_Outline object to
545 * receive all new data.
546 *
547 * When an outline, or a sub-path, is `closed', the stroker generates
548 * two independent `border' outlines, named `left' and `right'
549 *
550 * When the outline, or a sub-path, is `opened', the stroker merges
551 * the `border' outlines with caps. The `left' border receives all
552 * points, while the `right' border becomes empty.
553 *
554 * Use the function @FT_Stroker_Export instead if you want to
555 * retrieve all borders at once.
556 */
557 FT_EXPORT( void )
558 FT_Stroker_ExportBorder( FT_Stroker stroker,
559 FT_StrokerBorder border,
560 FT_Outline* outline );
563 /**************************************************************
564 *
565 * @function:
566 * FT_Stroker_GetCounts
567 *
568 * @description:
569 * Call this function once you have finished parsing your paths
570 * with the stroker. It returns the number of points and
571 * contours necessary to export all points/borders from the stroked
572 * outline/path.
573 *
574 * @input:
575 * stroker ::
576 * The target stroker handle.
577 *
578 * @output:
579 * anum_points ::
580 * The number of points.
581 *
582 * anum_contours ::
583 * The number of contours.
584 *
585 * @return:
586 * FreeType error code. 0~means success.
587 */
588 FT_EXPORT( FT_Error )
589 FT_Stroker_GetCounts( FT_Stroker stroker,
590 FT_UInt *anum_points,
591 FT_UInt *anum_contours );
594 /**************************************************************
595 *
596 * @function:
597 * FT_Stroker_Export
598 *
599 * @description:
600 * Call this function after @FT_Stroker_GetBorderCounts to
601 * export all borders to your own @FT_Outline structure.
602 *
603 * Note that this function appends the border points and
604 * contours to your outline, but does not try to resize its
605 * arrays.
606 *
607 * @input:
608 * stroker ::
609 * The target stroker handle.
610 *
611 * outline ::
612 * The target outline handle.
613 */
614 FT_EXPORT( void )
615 FT_Stroker_Export( FT_Stroker stroker,
616 FT_Outline* outline );
619 /**************************************************************
620 *
621 * @function:
622 * FT_Stroker_Done
623 *
624 * @description:
625 * Destroy a stroker object.
626 *
627 * @input:
628 * stroker ::
629 * A stroker handle. Can be NULL.
630 */
631 FT_EXPORT( void )
632 FT_Stroker_Done( FT_Stroker stroker );
635 /**************************************************************
636 *
637 * @function:
638 * FT_Glyph_Stroke
639 *
640 * @description:
641 * Stroke a given outline glyph object with a given stroker.
642 *
643 * @inout:
644 * pglyph ::
645 * Source glyph handle on input, new glyph handle on output.
646 *
647 * @input:
648 * stroker ::
649 * A stroker handle.
650 *
651 * destroy ::
652 * A Boolean. If~1, the source glyph object is destroyed
653 * on success.
654 *
655 * @return:
656 * FreeType error code. 0~means success.
657 *
658 * @note:
659 * The source glyph is untouched in case of error.
660 */
661 FT_EXPORT( FT_Error )
662 FT_Glyph_Stroke( FT_Glyph *pglyph,
663 FT_Stroker stroker,
664 FT_Bool destroy );
667 /**************************************************************
668 *
669 * @function:
670 * FT_Glyph_StrokeBorder
671 *
672 * @description:
673 * Stroke a given outline glyph object with a given stroker, but
674 * only return either its inside or outside border.
675 *
676 * @inout:
677 * pglyph ::
678 * Source glyph handle on input, new glyph handle on output.
679 *
680 * @input:
681 * stroker ::
682 * A stroker handle.
683 *
684 * inside ::
685 * A Boolean. If~1, return the inside border, otherwise
686 * the outside border.
687 *
688 * destroy ::
689 * A Boolean. If~1, the source glyph object is destroyed
690 * on success.
691 *
692 * @return:
693 * FreeType error code. 0~means success.
694 *
695 * @note:
696 * The source glyph is untouched in case of error.
697 */
698 FT_EXPORT( FT_Error )
699 FT_Glyph_StrokeBorder( FT_Glyph *pglyph,
700 FT_Stroker stroker,
701 FT_Bool inside,
702 FT_Bool destroy );
704 /* */
706 FT_END_HEADER
708 #endif /* __FT_STROKE_H__ */
711 /* END */
714 /* Local Variables: */
715 /* coding: utf-8 */
716 /* End: */