Debian Codegraph @

podofo/3rdparty/adobe/afdko/include/absfont.h

raw
1 /* Copyright 2014 Adobe Systems Incorporated (http://www.adobe.com/). All Rights Reserved.
2 This software is licensed as OpenSource, under the Apache License, Version 2.0.
3 This license is available at: http://opensource.org/licenses/Apache-2.0. */
4
5 #ifndef ABSFONT_H
6 #define ABSFONT_H
7
8 #include "ctlshare.h"
9 #include "dynarr.h"
10 #include "safetime.h"
11 #include "../resource/txops.h"
12
13 #define ABF_VERSION CTL_MAKE_VERSION(1, 0, 54)
14
15 #include <stdint.h>
16 #include <stdio.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /* Abstract Font Library
23 =====================
24 This library provides an abstract representation of a font that is suitable
25 for describing Type 1, CID-keyed, TrueType fonts. Global font information is
26 specified by a number of "dict" structures that loosely correspond to
27 PostScript font dictionaries. Glyph information is specified by a set of
28 callbacks that convey glyph data between various CoreType libraries. */
29
30 #define ABF_EMPTY_ARRAY 0
31 #define ABF_UNSET_PTR 0
32 #define ABF_UNSET_INT -1
33 #define ABF_UNSET_REAL -1.0
34
35 /* These macros specify initial field values that may later be distinguished
36 from explicitly set values. */
37
38 typedef struct abfFontDict_ abfFontDict;
39 typedef struct /* FontMatrix */
40 {
41 long cnt; /* ABF_EMPTY_ARRAY */
42 float array[6];
43 } abfFontMatrix;
44
45 typedef struct /* String */
46 {
47 char *ptr; /* ABF_UNSET_PTR */
48 long impl; /* ABF_UNSET_INT */
49 } abfString;
50
51 /* Textual data is represented by the abfString type which contains a
52 null-terminated C string pointer field (ptr), and an
53 implementation-specific numeric field (impl).
54
55 The CoreType libraries always use the ptr field externally and only make use
56 of the impl field for internal implementation purposes. A client may use the
57 impl field as they see fit since it will always be reinitialized by a
58 library that makes use of it. */
59
60 enum /* srcFontType values */
61 {
62 abfSrcFontTypeType1Name,
63 abfSrcFontTypeType1CID,
64 abfSrcFontTypeCFFName,
65 abfSrcFontTypeCFFCID,
66 abfSrcFontTypeSVGName,
67 abfSrcFontTypeUFOName,
68 abfSrcFontTypeTrueType,
69 abfSrcFontTypeUFOCID,
70 };
71
72 typedef struct
73 {
74 long flags; /* 0 */
75 #define ABF_CID_FONT (1 << 0) /* CID-keyed font */
76 #define ABF_SYN_FONT (1 << 1) /* Synthetic font */
77 #define ABF_SING_FONT (1 << 2) /* SING glyphlet font */
78 long srcFontType; /* ABF_UNSET_INT */
79 char *filename; /* ABF_UNSET_PTR */
80 long UnitsPerEm; /* 1000 */
81 long nGlyphs; /* ABF_UNSET_INT */
82 } abfSupplement;
83
84 /* Supplementary data that has not traditionally been stored in font outline
85 data is specified in the abfSupplement data structure. The "flags" field
86 will be consistently set and used by all libraries.
87
88 The remaining supplementary fields are primarily intended for implementation
89 use and will only be set if a library can do so reliably. Accordingly,
90 clients shouldn't rely on these values but are free to use these fields as
91 they see fit.
92
93 CID-keyed fonts are indicated by setting the ABF_CID_FONT flag bit to 1
94 and specifying CID-specific data via the abfTopDict.cid fields.
95
96 Synthetic fonts are indicated by setting the ABF_SYN_FONT flag bit to 1
97 and the SynBaseFontName field records the FontName of the font that the
98 synthetic variant is based on. */
99
100 enum /* OrigFontType field values */
101 {
102 abfOrigFontTypeType1,
103 abfOrigFontTypeCID,
104 abfOrigFontTypeTrueType,
105 abfOrigFontTypeOCF,
106 abfOrigFontTypeUFO
107 };
108
109 /* item variation store */
110 struct var_itemVariationStore_;
111 typedef struct var_itemVariationStore_ *var_itemVariationStore;
112
113 /* Top dictionary data. Comments indicate default/initial values. */
114 typedef struct
115 {
116 abfString version; /* Unset */
117 abfString Notice; /* Unset */
118 abfString Copyright; /* Unset */
119 abfString FullName; /* Unset */
120 abfString FamilyName; /* Unset */
121 abfString Weight; /* Unset */
122 long isFixedPitch; /* 0=false */
123 float ItalicAngle; /* 0. */
124 float UnderlinePosition; /* -100. */
125 float UnderlineThickness; /* 50. */
126 long UniqueID; /* ABF_UNSET_INT */
127 float FontBBox[4]; /* 0. 0. 0. 0. */
128 float StrokeWidth; /* 0. */
129 struct
130 {
131 long cnt; /* ABF_EMPTY_ARRAY */
132 long array[16];
133 } XUID;
134 abfString PostScript; /* Unset (CFF PostScript op value) */
135 abfString BaseFontName; /* Unset (Acrobat) */
136 struct
137 {
138 long cnt; /* ABF_EMPTY_ARRAY */
139 long array[15];
140 } BaseFontBlend;
141 long FSType; /* ABF_UNSET_INT */
142 long OrigFontType; /* ABF_UNSET_INT */
143 long WasEmbedded; /* 0=false */
144 abfString SynBaseFontName; /* Unset */
145 struct /* CID-specific extensions */
146 {
147 abfFontMatrix FontMatrix; /* 1. 0. 0. 1. 0. 0. */
148 abfString CIDFontName; /* Unset */
149 abfString Registry; /* Unset */
150 abfString Ordering; /* Unset */
151 long Supplement; /* ABF_UNSET_INT */
152 float CIDFontVersion; /* 0. */
153 long CIDFontRevision; /* 0 */
154 long CIDCount; /* 8720 */
155 long UIDBase; /* ABF_UNSET_INT */
156 } cid;
157 struct /* Font dict array */
158 {
159 long cnt; /* Value set by client to match array */
160 abfFontDict *array; /* Array allocated by client to match cnt */
161 } FDArray;
162 abfSupplement sup; /* Supplementary data */
163 unsigned short maxstack; /* Supplementary data */
164 var_itemVariationStore varStore;
165 } abfTopDict;
166
167 /* Private dictionary data. Comments indicate default/initial values. */
168
169 typedef struct
170 {
171 /* Used to hold stack items from a font with blended values */
172 float value;
173 int numBlends;
174 float *blendValues;
175 } abfOpEntry;
176
177 typedef struct
178 {
179 /* Used to hold stack items from a font with blended values */
180 float value;
181 int hasBlend;
182 float blendValues[CFF2_MAX_OP_STACK];
183 } abfBlendArg;
184
185 typedef struct
186 {
187 long cnt; /* ABF_EMPTY_ARRAY */
188 abfOpEntry array[CFF2_MAX_OP_STACK];
189 } abfOpEntryArray;
190
191 typedef struct
192 {
193 /* Note that even for a font with blended values,
194 the non-blended values are always set, using the values from the default font.
195 */
196 struct
197 {
198 long cnt; /* ABF_EMPTY_ARRAY */
199 float array[96];
200 } BlueValues;
201 struct
202 {
203 long cnt; /* ABF_EMPTY_ARRAY */
204 float array[96];
205 } OtherBlues;
206 struct
207 {
208 long cnt; /* ABF_EMPTY_ARRAY */
209 float array[96];
210 } FamilyBlues;
211 struct
212 {
213 long cnt; /* ABF_EMPTY_ARRAY */
214 float array[96];
215 } FamilyOtherBlues;
216 float BlueScale; /* 0.039625 */
217 float BlueShift; /* 7 */
218 float BlueFuzz; /* 1 */
219 float StdHW; /* ABF_UNSET_REAL */
220 float StdVW; /* ABF_UNSET_REAL */
221 struct
222 {
223 long cnt; /* ABF_EMPTY_ARRAY */
224 float array[96];
225 } StemSnapH;
226 struct
227 {
228 long cnt; /* ABF_EMPTY_ARRAY */
229 float array[96];
230 } StemSnapV;
231 long ForceBold; /* 0=false */
232 long LanguageGroup; /* 0 */
233 float ExpansionFactor; /* 0.06 */
234 float initialRandomSeed; /* 0. */
235 unsigned short vsindex;
236 int numRegions;
237 struct
238 {
239 abfOpEntryArray BlueValues;
240 abfOpEntryArray OtherBlues;
241 abfOpEntryArray FamilyBlues;
242 abfOpEntryArray FamilyOtherBlues;
243 abfOpEntry BlueScale;
244 abfOpEntry BlueShift;
245 abfOpEntry BlueFuzz;
246 abfOpEntry StdHW;
247 abfOpEntry StdVW;
248 abfOpEntryArray StemSnapH;
249 abfOpEntryArray StemSnapV;
250 } blendValues;
251 } abfPrivateDict;
252
253 /* Font dictionary data. Comments indicate default/initial values. */
254 struct abfFontDict_ {
255 abfString FontName; /* Unset (top level in name-keyed) */
256 long PaintType; /* 0 (top level in name-keyed) */
257 abfFontMatrix FontMatrix; /* .001 0. 0. .001 0. 0. (top in name-keyed) */
258 abfPrivateDict Private;
259 };
260
261 /* The data structures described here represent Postscript dictionary data for
262 name-keyed (traditional Type 1) and CID-keyed fonts. The PostScript
263 representation is translated to a C language representation as follows:
264
265 PostScript name-keyed C-struct name-keyed
266 --------------------- -------------------
267 font dict abfTopDict fields (excluding cid fields)
268 FDArray[0].FontName
269 FDArray[0].PaintType
270 FDArray[0].FontMatrix
271 Private dict FDArray[0].Private
272
273 PostScript CID-keyed C-struct CID-keyed
274 -------------------- ------------------
275 CIDFont dict abfTopDict fields (including cid fields)
276 FDArray[0] FDArray[0]
277 font dict
278 Private dict
279 FDArray[1] FDArray[1]
280 font dict
281 Private dict
282 ...
283 FDArray[N-1] FDArray[N-1]
284 font dict
285 Private dict
286
287 It can be seen that there is a direct mapping for CID-keyed fonts but the
288 name-keyed fonts are represented using a single element FDArray whose font
289 dict fields are treated as an extension of the font dict. */
290
291 void abfInitAllDicts(abfTopDict *top);
292 void abfInitTopDict(abfTopDict *top);
293 void abfInitFontDict(abfFontDict *font);
294
295 /* The client is responsible for allocating the font dictionary data structures
296 in memory and correctly initializing the abfTopDict.FDArray.cnt fields to
297 specify the number of element allocated in the abfTopDict.FDArray.array.
298 This will be 1 for name-keyed fonts and >=1 (the number being dependent on
299 the complexity of the font) for CID-keyed fonts. Once this has been done
300 abfInitAllDicts() may be called to initialize the entire data structure to
301 the values shown in the comments. Alternatively, the abfInitTopDict() and
302 abfInitFontDict() may be called to selectively initialize the top dictionary
303 or a single font dictionary, respectively.
304
305 For example, the dictionary data structures for a name-keyed font may be
306 created and initialized as follows (ignoring malloc failures!):
307
308 abfTopDict *top = malloc(sizeof(abfTopDict));
309 top->FDArray.cnt = 1;
310 top->FDArray.array = malloc(top->FDArray.cnt * sizeof(abfFontDict));
311 abfInitAllDicts(top);
312
313 CID fonts may be similarly handled except that the font dictionary array
314 will typically have more than one element. */
315
316 typedef struct abfErrCallbacks_ abfErrCallbacks;
317 struct abfErrCallbacks_ {
318 void *ctx;
319 void (*report_error)(abfErrCallbacks *cb, int err_code, int iFD);
320 };
321
322 void abfCheckAllDicts(abfErrCallbacks *cb, abfTopDict *top);
323
324 /* abfCheckAllDicts() is will check contents of all the dictionaries passed via
325 the "top" parameter. Any errors arising during the analysis will be called
326 back using the abfErrCallbacks structure passed via the "cb" parameter,
327 which may be NULL to turn off reporting. The "ctx" field of this structure
328 can be used to provide the callee with a context if one is needed, and the
329 "report_error" field provides the address of the error callback function.
330 This function provides the client context via the "ctx" parameter, the error
331 code via the "err_code" parameter, and the index of the font dictionary via
332 the "iFD" parameter. If the font dictionary index isn't applicable to the
333 error or if the font only has a single font dictionary the "iFD" parameter
334 is set to -1.
335
336 Error codes are enumerated in the abferr.h file and may be converted to
337 strings via abfErrStr() described below. */
338
339 int abfIsDefaultFontMatrix(const abfFontMatrix *FontMatrix);
340
341 /* abfIsDefaultMatrix() returns 1 if the "FontMatrix" parameter represents the
342 default matrix (.001 0 0 .001 0 0) and returns 0 otherwise. */
343
344 /* --------------------------- Font Merge Support -------------------------- */
345
346 int abfCompareTopDicts(abfTopDict *top1, abfTopDict *top2);
347
348 /* abfCompareTopDicts() will compare two top dicts to see if they are similar
349 enough to merge. It returns 0 if they can be merged else 1.
350
351 Fields in the top dict are checked for name-keyed and cid-keyed fonts but
352 the font and private dicts are compared for name-keyed fonts only.
353
354 FontNames are NOT checked.
355
356 For CID-keyed fonts, registry and order are checked, but not supplement. */
357
358 int abfCompareFontDicts(abfFontDict *font1, abfFontDict *font2);
359
360 /* abfCompareFontDicts() will compare two font dicts to see if they are
361 similar enough to merge. It returns 0 if they can be merged else 1.
362
363 abfCompareFontDicts() compares the FontName, FontMatrix, and all the
364 BlueValues.
365
366 abfCompareFontDicts() is used in the destination font writing module to
367 compare FDArrays of fonts with more than one element in the FDArray,
368 CID fonts. */
369
370 /* ---------------------------- Glyph Callbacks ---------------------------- */
371
372 /* Several libraries share the following glyph callback definitions and are
373 used whenever glyph information is passed from one component to the next. */
374
375 typedef struct abfEncoding_ abfEncoding;
376 struct abfEncoding_ /* Encoding node */
377 {
378 abfEncoding *next;
379 unsigned long code;
380 #define ABF_GLYPH_UNENC 0xffffffffUL /* Unencoded glyph */
381 };
382
383 typedef struct /* Glyph information */
384 {
385 short flags; /* Attribute flags */
386 #define ABF_GLYPH_CID (1 << 0) /* Glyph from CID-keyed font */
387 #define ABF_GLYPH_SEEN (1 << 1) /* Path data already returned to client */
388 #define ABF_GLYPH_UNICODE (1 << 2) /* Encoding is Unicode */
389 #define ABF_GLYPH_LANG_1 (1 << 3) /* Render with LanguageGroup 1 rules */
390 unsigned short tag; /* Unique tag */
391 abfString gname; /* Name-keyed: glyph name */
392 abfEncoding encoding; /* Name-keyed: encoding list */
393 unsigned short cid; /* CID-keyed: CID */
394 uint16_t iFD; /* CID-keyed: FD index */
395 ctlRegion sup; /* Supplementary data */
396 struct {
397 unsigned short vsindex;
398 unsigned short maxstack;
399 unsigned short numRegions;
400 float *blendDeltaArgs;
401 } blendInfo; /* Supplementary data */
402 } abfGlyphInfo;
403
404 /* The "flags" field specifies glyph attributes. Libraries may augment this
405 definition by specifying additional bits (see specific library API for
406 details).
407
408 The "tag" field is used to identify the glyph being processed in a font-
409 technology-specific way. The tag is incremented for each glyph processed,
410 starting from zero. Thus, the last glyph processed is assigned a tag value
411 that is one less than the number of glyphs in the font.
412
413 For OTF or TTF fonts that tag is the same as the glyph index. For a
414 naked-CID font it is derived by counting non-empty intervals in the CIDMap,
415 starting from CID 0. Thus, in a full set CID-keyed font the tag and CID will
416 be the same for each glyph. For a Type 1 font it is the order number of the
417 charstring in the CharStrings dictionary, starting from 0.
418
419 Warning: the tag values assigned to glyphs in a font may change if the font
420 is updated or subset.
421
422 If the font is CID-keyed the ABF_GLYPH_CID bit in the "flags" field is set
423 and the "cid" and "iFD" fields specify the CID and FD index, respectively.
424
425 If the font is name-keyed the ABF_GLYPH_CID bit is clear and the "gname" and
426 "encoding" fields specify the glyph name and encoding, respectively. The
427 glyph is unencoded if the "encoding.code" field is equal to ABF_GLYPH_UNENC.
428 Otherwise, the "encoding" field specifies the first node in an encoding
429 list. (Glyphs having more than one encoding (multiple encoding nodes) are
430 rare.)
431
432 All the glyphs for one font are either name-keyed or CID-keyed.
433
434 The ABF_GLYPH_SEEN bit in the flags field is set if the path data for this
435 glyph has already been returned to the client. It is primarily intended to
436 by used when fetching seac components in a font subset so as to avoid
437 repeated glyph definitions.
438
439 The ABF_GLYPH_LANG_1 bit indicates that the glyph is rendered with
440 LanguageGroup 1 rules. It is simply a copy of the value of the LanguageGroup
441 field taken from the corresponding Private dictionary. It is used by the
442 t1write library in order to determine the encoding of counter stem hints.
443
444 The "sup" field specifies the stream region corresponding to the charstring
445 data for the glyph. */
446
447 void abfInitGlyphInfo(abfGlyphInfo *info);
448
449 /* abfInitGlyphInfo() is provided for client convenience and initializes the
450 "info" parameter to a standard safe state. */
451
452 typedef struct abfGlyphCallbacks_ abfGlyphCallbacks;
453
454 struct abfGlyphCallbacks_ {
455 void *direct_ctx;
456 void *indirect_ctx;
457 abfGlyphInfo *info;
458 int (*beg)(abfGlyphCallbacks *cb, abfGlyphInfo *info);
459 void (*width)(abfGlyphCallbacks *cb, float hAdv);
460 void (*move)(abfGlyphCallbacks *cb, float x0, float y0);
461 void (*line)(abfGlyphCallbacks *cb, float x1, float y1);
462 void (*curve)(abfGlyphCallbacks *cb,
463 float x1, float y1,
464 float x2, float y2,
465 float x3, float y3);
466 void (*stem)(abfGlyphCallbacks *cb,
467 int flags, float edge0, float edge1);
468 void (*flex)(abfGlyphCallbacks *cb, float depth,
469 float x1, float y1,
470 float x2, float y2,
471 float x3, float y3,
472 float x4, float y4,
473 float x5, float y5,
474 float x6, float y6);
475 void (*genop)(abfGlyphCallbacks *cb, int cnt, float *args, int op);
476 void (*seac)(abfGlyphCallbacks *cb,
477 float adx, float ady, int bchar, int achar);
478 void (*end)(abfGlyphCallbacks *cb);
479 void (*moveVF)(abfGlyphCallbacks *cb, abfBlendArg *x0, abfBlendArg *y0);
480 void (*lineVF)(abfGlyphCallbacks *cb, abfBlendArg *x1, abfBlendArg *y1);
481 void (*curveVF)(abfGlyphCallbacks *cb,
482 abfBlendArg *x1, abfBlendArg *y1,
483 abfBlendArg *x2, abfBlendArg *y2,
484 abfBlendArg *x3, abfBlendArg *y3);
485 void (*stemVF)(abfGlyphCallbacks *cb,
486 int flags, abfBlendArg *edge0, abfBlendArg *edge1);
487 };
488
489 /* beg() is called to begin a new glyph definition and end() is called to
490 terminate that definition. Between these bracketing calls the other
491 callbacks may be called zero or more times. All beg() implementations are
492 required to copy their "info" parameter to the "info" field of callback
493 structure so that it is available to other callback functions.
494
495 The width() callback is called with the horizontal advance width of the
496 glyph.
497
498 Marking glyphs are drawn as an outline which is simply a sequence of
499 coordinate points that describe a path (which may be empty for non-marking
500 glyphs such as space). A path is composed of one or more subpaths that
501 describe closed regions. Each subpath is composed of a straight and curved
502 segments. (See TN#5177 for a detailed description of glyph path and hint
503 specification.)
504
505 Path data is specified by absolute coordinates in character space units.
506
507 Each subpath must begin with a call to move() in order to specify the
508 starting coordinate of the subpath via its parameters.
509
510 line() and curve() extend the path with a line or Bezier curve segments,
511 respectively, that are drawn from last point on the last segment or from the
512 point specified with move().
513
514 The stem() and flex() callbacks are used to pass hinting information back to
515 the client. These callbacks will typically be interleaved with the path
516 construction callbacks described above. Note that the flex() callback
517 specifies both path as well as hint information.
518
519 stem() specifies the absolute edge positions of a hint stem. The "flags"
520 parameter specifies stem attributes and additional hinting information as
521 follows: */
522
523 enum {
524 ABF_VERT_STEM = 1 << 0,
525 ABF_CNTR_STEM = 1 << 1,
526 ABF_STEM3_STEM = 1 << 2,
527 ABF_NEW_HINTS = 1 << 3,
528 ABF_NEW_GROUP = 1 << 4
529 };
530
531 /* The ABF_VERT_STEM bit specifies a vertical stem direction if set and
532 horizontal if clear.
533
534 When the ABF_CNTR_STEM bit is set it specifies that the stem participates in
535 global coloring counter (white space) control.
536
537 When the ABF_STEM3_STEM bit is set it specifies that the stem participates
538 in h/vstem3 counter control.
539
540 When the ABF_NEW_HINTS bit is set it specifies that a hint substitution
541 (previous hint map cleared) should be performed before the new stem is added
542 to the hint map.
543
544 When the ABF_NEW_GROUP bit is set it specifies that a new global coloring
545 counter group should be started before the new stem is added.
546
547 These bits may be combined as follows:
548
549 ABF_VERT_STEM / ABF_NEW_HINTS h/vstem
550 ABF_VERT_STEM / ABF_STEM3_STEM / ABF_NEW_HINTS h/vstem3
551 ABF_VERT_STEM / ABF_CNTR_STEM / ABF_NEW_GROUP global coloring
552
553 The calculation edge1-edge0 computes the width of the stem which MUST be
554 positive except for two special cases which specify an edge (rather that
555 stem) hint: */
556
557 enum {
558 ABF_EDGE_HINT_LO = -21, /* Bottom/left edge hint delta */
559 ABF_EDGE_HINT_HI = -20 /* Top/right edge hint delta */
560 };
561
562 /* Edge hints are not permitted for stems that set the ABF_CNTR_STEM bit.
563
564 flex() describes two adjoining curves with coordinates 1-3 and 4-6 and the
565 flex depth via the "depth" parameter.
566
567 The stem() and flex() callback functions may be disabled by setting them to
568 NULL if hint information is of no interest to the client. In this case the
569 two curve components of flex features will be called back to the client via
570 two consecutive curve() callbacks.
571
572 genop() permits general, non-path, non-hint operator to be passed to a
573 client. The "cnt" parameter specifies the number of arguments passed via
574 the "args" array. The "cnt" parameter may be 0. The "op" parameter specifies
575 the operator type as defined in txops.h.
576
577 The seac() function is used to specify a seac operator (see "Adobe Type 1
578 Font Format", however, the asb operand in the book description has been
579 combined with the adx operand in this function). This operator supports the
580 specification a new glyph as a composite of two others. It is normally used
581 to construct accented glyphs. The "bchar" and "achar" parameters specify
582 names of the the base glyph and accent glyph via encodings in the standard
583 encoding table, respectively. The "adx" and "ady" parameters specify the
584 translation that should be applied to the accent glyph relative to the base
585 glyph. */
586
587 enum /* Callback return values */
588 {
589 ABF_CONT_RET,
590 ABF_WIDTH_RET,
591 ABF_SKIP_RET,
592 ABF_QUIT_RET,
593 ABF_FAIL_RET
594 };
595
596 /* A typical application of this callback set is to provide a link between a
597 glyph data source like a font reading library (the caller), and a glyph data
598 sink like a font writing library (the callee). The "direct_ctx" field can be
599 used to provide the callee with a context if one is needed.
600
601 The callee may control the caller by the value returned from the beg()
602 callback. A return of ABF_WIDTH_RET will skip the remainder of the current
603 glyph after the width() callback has been called. A return of ABF_SKIP_RET
604 skips the remainder of the glyph definition for the current glyph (no
605 further callbacks will be called for the current glyph). A return of
606 ABF_QUIT_RET quits processing of the current font (no further callbacks will
607 be called for the current or subsequent glyphs). A return of ABF_CONT_RET
608 continues normal operation.
609
610 Callee control via callback return values affords very flexible control of
611 the information that is parsed by the caller. For example, the callee may
612 subset the font by returning ABF_CONT_RET from the beg() callback only for
613 glyphs in the subset and ABF_SKIP_RET otherwise. A important optimization
614 the callee might make is to keep track of which glyphs have been subset and
615 issue ABF_QUIT_RET when all subset glyphs have been seen. ABF_FAIL_RET is
616 returned from the callee if a fatal error is encountered during glyph
617 processing. */
618
619 typedef int (*abfGlyphBegCallback)(abfGlyphCallbacks *cb, abfGlyphInfo *info);
620
621 /* Another possible configuration is to have a client provide the glue layer
622 between the two libraries described above. Glyph subset filtering can then
623 be implemented in this layer by defining a beg() function that calls the
624 callee library's beg() function only for glyphs in a the subset. The
625 "indirect_ctx" field is provided if this client layer needs its own context.
626 The abfGlyphBegCallback typedef is provided as a convenience for clients
627 that need to implement this approach.
628
629 The required components of a glyph callback sequence are: beg(), width(),
630 and end(), in that order. The call to width() must immediately follow the
631 call to beg(). Marking glyphs will also make calls to move(), line(), and
632 curve(). Hinted glyphs may make calls the stem() and/or flex(). Finally,
633 some glyphs may make calls to genop() and/or seac().
634
635 Some of the facilities provided below or in other libraries may make an
636 abfGlyphCallbacks set template available that the client may use to directly
637 call the glyph callback functions. When such a template exist it is
638 guaranteed to have valid function address for all the glyph callbacks even
639 if the facility ignores some of the calls. Thus, a client doesn't need to
640 check the function addresses against NULL before calling them.
641
642 The "info" field points to the "info" parameter that was passed to the beg()
643 callback at the start of a glyph. The various beg() callback implementations
644 are required to copy this value when they are called. */
645
646 /* ------------------------ Abstract Font Descriptor ----------------------- */
647
648 #include "abfdesc.h"
649
650 typedef struct
651 {
652 long CharstringType;
653 long lenSubrArray;
654 float defaultWidthX;
655 float nominalWidthX;
656 } abfFontDescSpecialValues;
657
658 typedef struct abfFontDescCallbacks_ abfFontDescCallbacks;
659 struct abfFontDescCallbacks_ {
660 void *ctx;
661 void (*getSpecialValues)(abfFontDescCallbacks *cb, int iFD,
662 abfFontDescSpecialValues *sv);
663 };
664
665 abfFontDescHeader *abfNewFontDesc(ctlMemoryCallbacks *mem_cb,
666 abfFontDescCallbacks *desc_cb,
667 long lenGSubrArray,
668 abfTopDict *top);
669
670 void abfFreeFontDesc(ctlMemoryCallbacks *mem_cb, abfFontDescHeader *hdr);
671
672 /* abfNewFontDesc() makes a font descriptor from the information supplied via
673 its parameters that is suitable for use with the abfSetUpValues() function
674 in the buildch library. Most of the information needed to do this is
675 obtained via "top" parameter which would normally be obtained by calling one
676 of the BegFont() functions in the font parsing libraries.
677
678 However, additional non-abstract information is also required that is
679 obtained using the callbacks passed via the "desc_cb" parameter. The
680 getSpecialValues() callback is called several times for each font dict. This
681 callback must supply values for the fields in the abfFontDescSpecialValues
682 struct for the font dict specified by the "iFD" parameter.
683
684 The "CharstringType" field must have a value of 1 or 2 indicating Type 1 or
685 Type 2 charstrings, respectively. The "lenSubrArray" field continues the
686 count of the local subroutines or 0 if there are none. The "defaultWidthX"
687 and "nominalWidthX" fields contain the values of associated with the
688 corresponding operators in the CFF Private DICT or 0 if the operators are
689 not present in the font.
690
691 The count of the global subroutines in the font is passed via the
692 "lenGSubrArray" parameter which must be set to 0 if there are none.
693
694 The client passes a set of memory callback functions (described in
695 ctlshare.h) to the library via "mem_cb" parameter. These are used to
696 allocate a single block of memory for the font descriptor which is returned
697 by the function. The client should free this memory when the font descriptor
698 is no longer needed by calling abfFreeFontDesc().
699
700 abfNewFontDesc() returns a NULL pointer if the font descriptor could not be
701 created. */
702
703 float *abfGetFontDescMatrix(abfFontDescHeader *hdr, int iFD);
704
705 /* abfGetFontDescMatrix() returns a pointer to the 6-element FontMatrix array
706 of values. The "iFD" parameter selects the element from which to extract the
707 FontMatrix from the font descriptor. NULL is returned if either the element
708 didn't contain a FontMatrix (because it matched the default) or the "iFD"
709 parameter was invalid. */
710
711 /* ------------------------- Glyph Metrics Facility ------------------------ */
712
713 /* The bounding box and width metrics for a glyph may be determined using the
714 interface defined in this section. */
715
716 typedef struct abfMetricsCtx_ *abfMetricsCtx;
717 struct abfMetricsCtx_ {
718 long flags; /* Control flags */
719 #define ABF_MTX_TRANSFORM (1 << 0) /* Apply matrix to path */
720 float matrix[6]; /* Transformation matrix */
721 int err_code; /* Result code */
722 struct /* Real glyph metrics */
723 {
724 float left;
725 float bottom;
726 float right;
727 float top;
728 float hAdv;
729 } real_mtx;
730 struct /* Integer glyph metrics */
731 {
732 long left;
733 long bottom;
734 long right;
735 long top;
736 long hAdv;
737 } int_mtx;
738 float x; /* Last segment x end-point */
739 float y; /* Last segment y end-point */
740 };
741
742 /* abfMetricsCtx is an abstract font metrics context that is created by the
743 client and used by the facility to keep intermediate data and return the
744 results to the client.
745
746 The "flags" field (which must be initialized) allows the client control of
747 the facility by setting bits as follows:
748
749 ABF_MTX_TRANSFORM - transform path using the "matrix" field. The client must
750 initialize the "matrix" field appropriately when using this option. */
751
752 extern const abfGlyphCallbacks abfGlyphMetricsCallbacks;
753
754 /* abfGlyphMetricsCallbacks is a glyph callback set template that will compute
755 bounding box and horizontal advance width metrics for data passed to these
756 callbacks. The facility may be used as follows:
757
758 struct abfMetricsCtx_ ctx;
759 abfGlyphCallbacks cb = abfGlyphMetricsCallbacks; // copy template
760
761 ctx.flags = 0; // or set ABF_MTX_TRANSFORM and ctx.matrix
762 cb.direct_ctx = &ctx; // set metrics context
763
764 // parse charstring and call cb functions, e.g. with t1cParse()
765 // result now in metrics context
766
767 if (ctx.err_code != abfSuccess)
768 // handle error
769 else
770 // real glyph metrics available in ctx.real_mtx
771 // integer glyph metrics available in ctx.int_mtx
772
773 */
774
775 /* --------------------------- Font Dump Support --------------------------- */
776
777 /* An abstract font may be dumped in a human-readable text format using the
778 interface defined in this section. */
779
780 typedef struct abfDumpCtx_ *abfDumpCtx;
781 struct abfDumpCtx_ {
782 FILE *fp; /* Output stream */
783 int flags; /* Control flags */
784 int level; /* Dump level */
785 int left; /* Columns left in line (characters) */
786 int excludeSubset;
787 int fdCnt; /* Index of font dict to dump or -1 for all dicts */
788 int *fdArray; /* Index of font dict to dump or -1 for all dicts */
789 };
790
791 /* abfDumpCtx is the abstract font dumping context. It must be created by the
792 client and then initialized appropriately before each dump. It is
793 subsequently passed to abfDumpBegFont() and used to set the "direct_ctx"
794 field in the abfGlyphCallbacks structure.
795
796 The "fp" field specifies an open stream to which the dump data will be
797 written.
798
799 The "flags" field is for internal use only.
800
801 The "level" field may be used to set the reporting level for font data:
802
803 0 dict data
804 1 dict data; glyph data (very short)
805 2 dict data; glyph data (short)
806 3 dict data; glyph data (long)
807 4 glyph data (very short)
808 5 glyph data (short)
809 6 glyph data (long)
810
811 The "left" field is for internal use only.
812
813 The "fd" field specifies the index of the font dict to dump. If you want to
814 dump all dicts set this field to -1. */
815
816 void abfDumpBegFont(abfDumpCtx h, abfTopDict *top);
817
818 /* abfDumpFont() dumps the dictionaries pointed to by the "top" parameter. */
819
820 extern const abfGlyphCallbacks abfGlyphDumpCallbacks;
821
822 /* abfDumpGlyphCallbacks is a glyph callback set template that will dump the
823 data passed to these callbacks when they are called by the client using the
824 level previously set in the context. Clients should make a copy of this data
825 structure and set "direct_ctx" field to the context they created and
826 initialized. */
827
828 /* --------------------------- Font Draw Support --------------------------- */
829
830 /* An abstract font may be printed to a PostScript using the interface defined
831 in this section. */
832
833 typedef struct abfDrawCtx_ *abfDrawCtx;
834 struct abfDrawCtx_ {
835 long flags; /* Control flags */
836 #define ABF_FLIP_TICS (1 << 0) /* Flip coord tics to other side of path */
837 #define ABF_SHOW_BY_ENC (1 << 1) /* Show by 8-bit encoding */
838 #define ABF_NO_LABELS (1 << 2) /* Don't show numeric labels */
839 #define ABF_DUPLEX_PRINT (1 << 3) /* Prepend duplex print enable */
840 FILE *fp; /* Output stream */
841 int level; /* Draw level */
842 int showglyph; /* Show the current glyph */
843 struct /* Metric data */
844 {
845 struct abfMetricsCtx_ ctx;
846 abfGlyphCallbacks cb;
847 } metrics;
848 struct /* Tile mode data */
849 {
850 int h; /* h origin */
851 int v; /* v origin */
852 } tile;
853 struct /* Glyph data */
854 {
855 float hAdv;
856 float scale; /* Glyph drawing scale factor (points/unit) */
857 } glyph;
858 struct /* Path data */
859 {
860 float bx; /* Last point */
861 float by;
862 float cx; /* Last but one point */
863 float cy;
864 float fx; /* First point in path */
865 float fy;
866 float sx; /* Second point in path */
867 float sy;
868 int cnt; /* Point count */
869 int moves;
870 int lines;
871 int curves;
872 } path;
873 int pageno; /* Page number */
874 abfTopDict *top;
875 };
876
877 /* abfDrawCtx is the abstract font drawing context. It must be created by the
878 client and then initialized appropriately before each font is processed. It
879 is subsequently passed to abfDrawBegFont() and used to set the "direct_ctx"
880 field in the abfGlyphCallbacks structure.
881 xxx more */
882
883 void abfDrawBegFont(abfDrawCtx h, abfTopDict *top);
884 void abfDrawEndFont(abfDrawCtx h);
885
886 /* abfDrawFont() draws the dictionaries pointed to by the "top" parameter. */
887
888 extern const abfGlyphCallbacks abfGlyphDrawCallbacks;
889
890 /* abfDrawGlyphCallbacks is a glyph callback set template that will draw the
891 data passed to these callbacks when they are called by the client using the
892 level previously set in the context. Clients should make a copy of this data
893 structure and set "direct_ctx" field to the context they created and
894 initialized. */
895
896 /* ------------------------------ AFM Support ------------------------------ */
897
898 /* A simple Adobe Font Metrics (AFM) file may be generated from an abstract
899 font using the interfaces described in this section. This facility is
900 primarily intended for checking and debugging purposes. It should not be
901 used as a means of generating production quality AFM files since conformance
902 to the AFM specification (TN#5004) is not guaranteed. */
903
904 typedef struct abfAFMCtx_ *abfAFMCtx;
905 struct abfAFMCtx_ {
906 FILE *fp; /* Output stream */
907 FILE *tmp_fp; /* temporary output stream */
908 int err_code;
909 struct /* glyph metrics */
910 {
911 struct abfMetricsCtx_ ctx;
912 abfGlyphCallbacks cb;
913 } glyph_metrics;
914 struct /* aggregate font bounding box metrics */
915 {
916 int16_t left;
917 int16_t bottom;
918 int16_t right;
919 int16_t top;
920 } font_bbox;
921 };
922
923 void abfAFMBegFont(abfAFMCtx h);
924 void abfAFMEndFont(abfAFMCtx h, abfTopDict *top);
925
926 extern const abfGlyphCallbacks abfGlyphAFMCallbacks;
927
928 /* ----------------------------- Path Support ------------------------------ */
929
930 /* Glyph outlines may be manipulated using the functions defined in this
931 section. */
932
933 typedef struct abfCtx_ *abfCtx;
934 abfCtx abfNew(ctlMemoryCallbacks *mem_cb, CTL_CHECK_ARGS_DCL);
935
936 #define ABF_CHECK_ARGS CTL_CHECK_ARGS_CALL(ABF_VERSION)
937
938 /* abfNew() initializes the path component of the abstract font library and
939 returns an opaque context (abfCtx) that is subsequently passed to all the
940 other library functions (or NULL if the library cannot be initialized). It
941 must be the first function in this section of the library to be called by
942 the client. The client passes a set of memory callback functions (described
943 in ctlshare.h) to the library via "mem_cb" parameter.
944
945 The ABF_CHECK_ARGS macro is passed as the last parameter to abfNew() in
946 order to perform a client/library compatibility check. */
947
948 int abfBegFont(abfCtx h, abfTopDict *top);
949
950 /* abfBegFont() is called to initialize a new font. */
951
952 int abfEndFont(abfCtx h, long flags, abfGlyphCallbacks *glyph_cb);
953
954 enum /* abfEndFont(flags) bits */
955 {
956 ABF_PATH_REMOVE_OVERLAP = 1 << 0 /* Remove overlapping paths */
957 };
958
959 extern const abfGlyphCallbacks abfGlyphPathCallbacks;
960
961 /* abfEndFont() is called to end the new font that was begun with a call to
962 abfBegFont(). Between these two calls one or more glyphs may be accumulated
963 by calling the glyph callbacks (see above for description) defined in
964 abfGlyphPathCallbacks.
965
966 The action of calling abfEndFont() causes the accumulated glyphs to be
967 processed according to the action specified via the "flags" parameter. After
968 the glyphs have been processed, a new (possibly unmodified) path is then
969 returned to the client using another set of glyph callbacks passed via the
970 "glyph_cb" parameter. */
971
972 int abfFree(abfCtx h);
973
974 /* abfFree() destroys the library context and all the resources allocated to
975 it. */
976
977 enum {
978 #undef CTL_DCL_ERR
979 #define CTL_DCL_ERR(name, string) name,
980 #include "abferr.h"
981 abfErrCount
982 };
983
984 /* Library functions return either zero (abfSuccess) to indicate success or a
985 positive non-zero error code that is defined in the above enumeration that
986 is built from abferr.h. */
987
988 char *abfErrStr(int err_code);
989
990 /* abfErrStr() maps the "errcode" parameter to a null-terminated error
991 string. */
992
993 void abfGetVersion(ctlVersionCallbacks *cb);
994
995 /* abfGetVersion() returns the library version number and name via the client
996 callbacks passed with the "cb" parameter (see ctlshare.h). */
997
998 #ifdef __cplusplus
999 }
1000 #endif
1001
1002 #endif /* ABSFONT_H */