4 * Copyright (C) 2011-2014 by Werner Lemberg.
6 * This file is part of the ttfautohint library, and may only be used,
7 * modified, and distributed under the terms given in `COPYING'. By
8 * continuing to use, modify, or distribute this file you indicate that you
9 * have read `COPYING' and understand and accept it fully.
11 * The file `COPYING' mentioned in the previous paragraph is distributed
12 * with the ttfautohint library.
16 /* originally file `afhints.h' (2011-Mar-28) from FreeType */
18 /* heavily modified 2011 by Werner Lemberg <wl@gnu.org> */
29 #define xxTA_SORT_SEGMENTS
32 /* the definition of outline glyph hints; these are shared */
33 /* by all writing system analysis routines (until now) */
35 typedef enum TA_Dimension_
37 TA_DIMENSION_HORZ
= 0, /* x coordinates, i.e. vert. segments & edges */
38 TA_DIMENSION_VERT
= 1, /* y coordinates, i.e. horz. segments & edges */
39 TA_DIMENSION_MAX
/* do not remove */
43 /* hint directions -- the values are computed so that two vectors */
44 /* are in opposite directions iff `dir1 + dir2 == 0' */
46 typedef enum TA_Direction_
57 * The following explanations are mostly taken from the article
59 * Real-Time Grid Fitting of Typographic Outlines
61 * by David Turner and Werner Lemberg
63 * http://www.tug.org/TUGboat/Articles/tb24-3/lemberg.pdf
65 * with appropriate updates.
70 * `ta_{cjk,latin,...}_hints_compute_segments' are the functions to
71 * find segments in an outline.
73 * A segment is a series of consecutive points that are approximately
74 * aligned along a coordinate axis. The analysis to do so is specific
75 * to a writing system.
77 * A segment must have at least two points, except in the case of
78 * `fake' segments that are generated to hint metrics appropriately,
79 * and which consist of a single point.
84 * `ta_{cjk,latin,...}_hints_compute_edges' are the functions to find
87 * As soon as segments are defined, the auto-hinter groups them into
88 * edges. An edge corresponds to a single position on the main
89 * dimension that collects one or more segments (allowing for a small
92 * As an example, the `latin' writing system first tries to grid-fit
93 * edges, then to align segments on the edges unless it detects that
103 * +------<-----+ +-----<------+
107 * +--------------->------------------+
113 * Stems are detected by `ta_{cjk,latin,...}_hint_edges'.
115 * Segments need to be `linked' to other ones in order to detect stems.
116 * A stem is made of two segments that face each other in opposite
117 * directions and that are sufficiently close to each other. Using
118 * vocabulary from the TrueType specification, stem segments form a
121 * In the above ASCII drawing, the horizontal segments are BC, DE, and
122 * FG; the vertical segments are AB, CD, EF, and GH.
124 * Each segment has at most one `best' candidate to form a black
125 * distance, or no candidate at all. Notice that two distinct segments
126 * can have the same candidate, which frequently means a serif.
128 * A stem is recognized by the following condition:
130 * best segment_1 = segment_2 && best segment_2 = segment_1
132 * The best candidate is stored in field `link' in structure
135 * In the above ASCII drawing, the best candidate for both AB and CD is
136 * GH, while the best candidate for GH is AB. Similarly, the best
137 * candidate for EF and GH is AB, while the best candidate for AB is
140 * The detection and handling of stems is dependent on the writing
146 * Serifs are detected by `ta_{cjk,latin,...}_hint_edges'.
148 * In comparison to a stem, a serif (as handled by the auto-hinter
149 * module which takes care of the `latin' writing system) has
151 * best segment_1 = segment_2 && best segment_2 != segment_1
153 * where segment_1 corresponds to the serif segment (CD and EF in the
154 * above ASCII drawing).
156 * The best candidate is stored in field `serif' in structure
157 * `TA_Segment' (and `link' is set to NULL).
162 * A point is called `touched' if it has been processed somehow by the
163 * auto-hinter. It basically means that it shouldn't be moved again
164 * (or moved only under certain constraints to preserve the already
165 * applied processing).
168 * Flat and round segments
170 * Segments are `round' or `flat', depending on the series of points
171 * that define them. A segment is round if the next and previous point
172 * of an extremum (which can be either a single point or sequence of
173 * points) are both conic or cubic control points. Otherwise, a
174 * segment with an extremum is flat.
179 * Experience has shown that points which are not part of an edge need
180 * to be interpolated linearly between their two closest edges, even if
181 * these are not part of the contour of those particular points.
182 * Typical candidates for this are
184 * - angle points (i.e., points where the `in' and `out' direction
187 * - inflection points (i.e., where the `in' and `out' angles are the
188 * same, but the curvature changes sign) [currently, such points
189 * aren't handled in the auto-hinter]
191 * `ta_glyph_hints_align_strong_points' is the function which takes
192 * care of such situations; it is equivalent to the TrueType `IP'
193 * hinting instruction.
198 * Other points in the outline must be interpolated using the
199 * coordinates of their previous and next unfitted contour neighbours.
200 * These are called `weak points' and are touched by the function
201 * `ta_glyph_hints_align_weak_points', equivalent to the TrueType `IUP'
202 * hinting instruction. Typical candidates are control points and
203 * points on the contour without a major direction.
205 * The major effect is to reduce possible distortion caused by
206 * alignment of edges and strong points, thus weak points are processed
207 * after strong points.
211 /* point hint flags */
212 #define TA_FLAG_NONE 0
214 /* point type flags */
215 #define TA_FLAG_CONIC (1 << 0)
216 #define TA_FLAG_CUBIC (1 << 1)
217 #define TA_FLAG_CONTROL (TA_FLAG_CONIC | TA_FLAG_CUBIC)
219 /* point extremum flags */
220 #define TA_FLAG_EXTREMA_X (1 << 2)
221 #define TA_FLAG_EXTREMA_Y (1 << 3)
223 /* point roundness flags */
224 #define TA_FLAG_ROUND_X (1 << 4)
225 #define TA_FLAG_ROUND_Y (1 << 5)
227 /* point touch flags */
228 #define TA_FLAG_TOUCH_X (1 << 6)
229 #define TA_FLAG_TOUCH_Y (1 << 7)
231 /* candidates for weak interpolation have this flag set */
232 #define TA_FLAG_WEAK_INTERPOLATION (1 << 8)
234 /* all inflection points in the outline have this flag set */
235 #define TA_FLAG_INFLECTION (1 << 9)
238 /* edge hint flags */
239 #define TA_EDGE_NORMAL 0
240 #define TA_EDGE_ROUND (1 << 0)
241 #define TA_EDGE_SERIF (1 << 1)
242 #define TA_EDGE_DONE (1 << 2)
243 #define TA_EDGE_NEUTRAL (1 << 3)
246 typedef struct TA_PointRec_
* TA_Point
;
247 typedef struct TA_SegmentRec_
* TA_Segment
;
248 typedef struct TA_EdgeRec_
* TA_Edge
;
251 typedef struct TA_PointRec_
253 FT_UShort flags
; /* point flags used by hinter */
254 FT_Char in_dir
; /* direction of inwards vector */
255 FT_Char out_dir
; /* direction of outwards vector */
257 FT_Pos ox
, oy
; /* original, scaled position */
258 FT_Short fx
, fy
; /* original, unscaled position (in font units) */
259 FT_Pos x
, y
; /* current position */
260 FT_Pos u
, v
; /* current (x,y) or (y,x) depending on context */
262 TA_Point next
; /* next point in contour */
263 TA_Point prev
; /* previous point in contour */
267 typedef struct TA_SegmentRec_
269 FT_Byte flags
; /* edge/segment flags for this segment */
270 FT_Char dir
; /* segment direction */
271 FT_Short pos
; /* position of segment */
272 FT_Short min_coord
; /* minimum coordinate of segment */
273 FT_Short max_coord
; /* maximum coordinate of segment */
274 FT_Short height
; /* the hinted segment height */
276 TA_Edge edge
; /* the segment's parent edge */
277 TA_Segment edge_next
; /* link to next segment in parent edge */
279 TA_Segment link
; /* (stem) link segment */
280 TA_Segment serif
; /* primary segment for serifs */
281 FT_Pos num_linked
; /* number of linked segments */
282 FT_Pos score
; /* used during stem matching */
283 FT_Pos len
; /* used during stem matching */
285 TA_Point first
; /* first point in edge segment */
286 TA_Point last
; /* last point in edge segment */
290 typedef struct TA_EdgeRec_
292 FT_Short fpos
; /* original, unscaled position (in font units) */
293 FT_Pos opos
; /* original, scaled position */
294 FT_Pos pos
; /* current position */
296 FT_Byte flags
; /* edge flags */
297 FT_Char dir
; /* edge direction */
298 FT_Fixed scale
; /* used to speed up interpolation between edges */
300 TA_Width blue_edge
; /* non-NULL if this is a blue edge */
301 FT_UInt best_blue_idx
; /* for the hinting recorder callback */
302 FT_Bool best_blue_is_shoot
; /* for the hinting recorder callback */
304 TA_Edge link
; /* link edge */
305 TA_Edge serif
; /* primary edge for serifs */
306 FT_Short num_linked
; /* number of linked edges */
307 FT_Int score
; /* used during stem matching */
309 TA_Segment first
; /* first segment in edge */
310 TA_Segment last
; /* last segment in edge */
314 typedef struct TA_AxisHintsRec_
316 FT_Int num_segments
; /* number of used segments */
317 FT_Int max_segments
; /* number of allocated segments */
318 TA_Segment segments
; /* segments array */
319 #ifdef TA_SORT_SEGMENTS
323 FT_Int num_edges
; /* number of used edges */
324 FT_Int max_edges
; /* number of allocated edges */
325 TA_Edge edges
; /* edges array */
327 TA_Direction major_dir
; /* either vertical or horizontal */
328 } TA_AxisHintsRec
, *TA_AxisHints
;
331 typedef enum TA_Action_
348 ta_anchor_round_serif
,
353 ta_adjust_round_serif
,
355 ta_adjust_bound_serif
,
356 ta_adjust_bound_round
,
357 ta_adjust_bound_round_serif
,
371 ta_stem_bound_round_serif
,
374 ta_serif_lower_bound
,
375 ta_serif_upper_bound
,
376 ta_serif_upper_lower_bound
,
379 ta_serif_anchor_lower_bound
,
380 ta_serif_anchor_upper_bound
,
381 ta_serif_anchor_upper_lower_bound
,
384 ta_serif_link1_lower_bound
,
385 ta_serif_link1_upper_bound
,
386 ta_serif_link1_upper_lower_bound
,
389 ta_serif_link2_lower_bound
,
390 ta_serif_link2_upper_bound
,
391 ta_serif_link2_upper_lower_bound
,
398 (*TA_Hints_Recorder
)(TA_Action action
,
401 void* arg1
, /* TA_Point or TA_Edge */
405 TA_Edge upper_bound
);
407 typedef struct TA_GlyphHintsRec_
415 FT_Int max_points
; /* number of allocated points */
416 FT_Int num_points
; /* number of used points */
417 TA_Point points
; /* points array */
419 FT_Int max_contours
; /* number of allocated contours */
420 FT_Int num_contours
; /* number of used contours */
421 TA_Point
* contours
; /* contours array */
423 TA_AxisHintsRec axis
[TA_DIMENSION_MAX
];
425 FT_UInt32 scaler_flags
; /* copy of scaler flags */
426 FT_UInt32 other_flags
; /* free for style-specific implementations */
427 TA_StyleMetrics metrics
;
429 FT_Pos xmin_delta
; /* used for warping */
432 TA_Hints_Recorder recorder
;
437 #define TA_HINTS_TEST_SCALER(h, f) \
438 ((h)->scaler_flags & (f))
439 #define TA_HINTS_TEST_OTHER(h, f) \
440 ((h)->other_flags & (f))
445 #define TA_HINTS_DO_HORIZONTAL(h) \
446 (!_ta_debug_disable_horz_hints \
447 && !TA_HINTS_TEST_SCALER(h, TA_SCALER_FLAG_NO_HORIZONTAL))
449 #define TA_HINTS_DO_VERTICAL(h) \
450 (!_ta_debug_disable_vert_hints \
451 && !TA_HINTS_TEST_SCALER(h, TA_SCALER_FLAG_NO_VERTICAL))
453 #define TA_HINTS_DO_ADVANCE(h) \
454 !TA_HINTS_TEST_SCALER(h, TA_SCALER_FLAG_NO_ADVANCE)
456 #define TA_HINTS_DO_BLUES(h) \
457 (!_ta_debug_disable_blue_hints)
459 #else /* !TA_DEBUG */
461 #define TA_HINTS_DO_HORIZONTAL(h) \
462 !TA_HINTS_TEST_SCALER(h, TA_SCALER_FLAG_NO_HORIZONTAL)
464 #define TA_HINTS_DO_VERTICAL(h) \
465 !TA_HINTS_TEST_SCALER(h, TA_SCALER_FLAG_NO_VERTICAL)
467 #define TA_HINTS_DO_ADVANCE(h) \
468 !TA_HINTS_TEST_SCALER(h, TA_SCALER_FLAG_NO_ADVANCE)
470 #define TA_HINTS_DO_BLUES(h) \
473 #endif /* !TA_DEBUG */
477 ta_direction_compute(FT_Pos dx
,
482 ta_axis_hints_new_segment(TA_AxisHints axis
,
483 TA_Segment
* asegment
);
486 ta_axis_hints_new_edge(TA_AxisHints axis
,
493 ta_glyph_hints_dump_points(TA_GlyphHints hints
);
496 ta_glyph_hints_dump_segments(TA_GlyphHints hints
);
499 ta_glyph_hints_dump_edges(TA_GlyphHints hints
);
503 ta_glyph_hints_init(TA_GlyphHints hints
);
506 ta_glyph_hints_rescale(TA_GlyphHints hints
,
507 TA_StyleMetrics metrics
);
510 ta_glyph_hints_reload(TA_GlyphHints hints
,
511 FT_Outline
* outline
);
514 ta_glyph_hints_save(TA_GlyphHints hints
,
515 FT_Outline
* outline
);
518 ta_glyph_hints_align_edge_points(TA_GlyphHints hints
,
522 ta_glyph_hints_align_strong_points(TA_GlyphHints hints
,
526 ta_glyph_hints_align_weak_points(TA_GlyphHints hints
,
529 #ifdef TA_CONFIG_OPTION_USE_WARPER
531 ta_glyph_hints_scale_dim(TA_GlyphHints hints
,
538 ta_glyph_hints_done(TA_GlyphHints hints
);
541 #define TA_SEGMENT_LEN(seg) \
542 ((seg)->max_coord - (seg)->min_coord)
544 #define TA_SEGMENT_DIST(seg1, seg2) \
545 (((seg1)->pos > (seg2)->pos) ? (seg1)->pos - (seg2)->pos \
546 : (seg2)->pos - (seg1)->pos)
552 #endif /* __TAHINTS_H__ */
555 /* end of tahints.h */