Debian Codegraph @

podofo/3rdparty/adobe/afdko/include/t1read.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 T1READ_H
6 #define T1READ_H
7
8 #include "ctlshare.h"
9
10 #define T1R_VERSION CTL_MAKE_VERSION(1, 0, 45)
11
12 #include "absfont.h"
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 /* Type 1 (PostScript) Font Parser Library
19 =======================================
20 This library parses parses single master, multiple master, synthetic, and
21 CID-keyed Type 1 fonts.
22
23 This library is initialized with a single call to t1rNew() that allocates
24 an opaque context (t1rCtx) which is passed to subsequent functions and is
25 destroyed by a single call to t1rFree(). Thus, multiple contexts may be
26 concurrently allocated permitting operation in a multi-threaded environment.
27
28 Each font parse is begun by calling t1rBegFont() and completed by calling
29 t1rEndFont(). Between these calls one or more glyphs may be parsed with the
30 t1rIterateGlyphs(), t1rGetGlyphByTag(), t1rGetGlyphByName(),
31 t1rGetGlyphByCID() or t1cGetByStdEnc() functions. Weight vector and
32 subroutine information may be obtained by calling t1rGetWV() and
33 t1rGetSubrs(), respectively.
34
35 Multiple master fonts are always snapshot to a client-supplied instance that
36 is set via t1rBegFont().
37
38 Memory management and source data functions are provided by two sets of
39 client-supplied callbacks described in ctlshare.h. */
40
41 typedef struct t1rCtx_ *t1rCtx;
42 t1rCtx t1rNew(ctlMemoryCallbacks *mem_cb, ctlStreamCallbacks *stm_cb,
43 CTL_CHECK_ARGS_DCL);
44
45 #define T1R_CHECK_ARGS CTL_CHECK_ARGS_CALL(T1R_VERSION)
46
47 /* t1rNew() initializes the library and returns an opaque context (t1rCtx) that
48 is subsequently passed to all the other library functions. It must be the
49 first function in the library to be called by the client. The client passes
50 a set of memory and stream callback functions (described in ctlshare.h) to
51 the library via the mem_cb and stm_cb parameters.
52
53 The T1R_CHECK_ARGS macro is passed as the last parameter to t1rNew() in
54 order to perform a client/library compatibility check.
55
56 The temporary data stream (T1R_TMP_STREAM_ID) and the optional debug data
57 stream (T1R_DBG_STREAM_ID) are opened by this call. The debug stream
58 provides more detailed error and warning messages than is available via
59 t1rErrStr(). If the client doesn't require the debug data stream NULL should
60 be returned from its stream open call. */
61
62 int t1rBegFont(t1rCtx h,
63 long flags, long origin, abfTopDict **top, float *UDV);
64
65 #define T1R_UPDATE_OPS (1 << 0)
66 #define T1R_USE_MATRIX (1 << 1)
67 #define T1R_DUMP_TOKENS (1 << 2)
68 #define T1R_KEEP_CID_CSTRS (1 << 3)
69 #define T1R_NO_UDV_CLAMPING (1 << 4)
70 #define T1R_SEEN_GLYPH (1 << 7) /* have seen a glyph */
71
72 /* t1rBegFont() is called to initiate a new font parse. The source data stream
73 (T1R_SRC_STREAM_ID) is opened, positioned at the offset specified by the
74 "origin" parameter, the PostScript source is parsed, and selected
75 dictionary values are stored in the data structure pointed to by the "top"
76 parameter (which will remain stable until t1rEndFont() is called). If eexec
77 or charstring encryption is present it is removed. Charstring and subroutine
78 data is then stored in the temporary stream for subsequent parsing.
79
80 The "flags" parameter allows client control over the parse by setting bits
81 as follows:
82
83 T1C_UPDATE_OPS - charstrings using the deprecated seac operator are
84 converted to a regular path by combining the component glyphs and the
85 deprecated dotsection operator is removed
86
87 T1C_USE_MATRIX - transform charstring path coordinates using the font's own
88 FontMatrix. This facility would not normally be used during font format
89 conversion since it is generally better to leave the path coordinates
90 unmodified and specify a non-default matrix in the font. However, it is
91 useful for drawing and manipulating glyph outline data
92
93 T1R_DUMP_TOKENS - dump PostScript tokens to stdout as they are parsed.
94 Useful for debugging bad PostScript font files.
95
96 T1R_KEEP_CID_CSTRS - In normal operation CID charstrings are decrypted and
97 copied to a fixed position in the tmp stream for the purpose of parsing the
98 charstring data. Thus charstring data in the tmp stream is normally only
99 valid while the glyph is called back. This is an optimization that limits
100 the total size of the tmp stream for potentially large CID fonts. However,
101 this may be undesirable behavior for some specialized clients, e.g. a
102 rasterizer, and therefore it may be overridden by setting this flag.
103
104 The "UDV" parameter specifies the User Design Vector to be used in
105 snapshotting a multiple master font. If NULL, the font is snapshot at the
106 default instance. The parameter may be set to NULL for non-multiple master
107 fonts.
108 */
109
110 int t1rIterateGlyphs(t1rCtx h, abfGlyphCallbacks *glyph_cb);
111
112 /* t1rIterateGlyphs() is called to iterate through all the glyph data in the
113 font. (The number of glyphs in the font is passed back to the client via the
114 "top" parameter to t1rBegFont() in the "sup.nGlyphs" field.) Glyph data is
115 passed back to the client via the callbacks specified via the "glyph_cb"
116 parameter (see absfont.h).
117
118 Each glyph is introduced by calling the beg() glyph callback. The "info"
119 parameter passed by this call provides a means of identifying each glyph.
120
121 For CID-keyed fonts the "tag" field is the order number of the charstring in
122 the data section starting with 0 and the "cid" field specifies the glyph's
123 CID. (Thus, the tag and cid fields will generally differ for subset
124 CID-keyed fonts.)
125
126 For name-keyed fonts the "tag" field is the order number of the charstring
127 in the CharStrings dictionary, starting from 0 and the "gname" field
128 specifies the glyph's name.
129
130 The client can control whether path data is read or ignored by the value
131 returned from the beg() callback and can thus use this interface to select a
132 subset of glyphs or just enumerate the glyph set without reading any path
133 data. */
134
135 int t1rGetGlyphByTag(t1rCtx h,
136 unsigned short tag, abfGlyphCallbacks *glyph_cb);
137 int t1rGetGlyphByName(t1rCtx h,
138 char *gname, abfGlyphCallbacks *glyph_cb);
139 int t1rGetGlyphByCID(t1rCtx h,
140 unsigned short cid, abfGlyphCallbacks *glyph_cb);
141
142 /* t1rGetGlyphByTag(), t1rGetGlyphByName(), t1rGetGlyphByCID() are called
143 obtain glyph data from a glyph selected by its tag (described above), its
144 name, or its CID, respectively. The glyph name is specified by as a
145 null-terminated string via the "gname" parameter.
146
147 These functions return t1rErrNoGlyph if the requested glyph is not present
148 in the font or the access method is incompatible with the font type. */
149
150 int t1rGetGlyphByStdEnc(t1rCtx h, int stdcode, abfGlyphCallbacks *glyph_cb);
151
152 /* t1rGetGlyphByStdEnc() is called to obtain glyph data from a glyph selected
153 by its standard encoding specified by the "stdcode" parameter (which is
154 really an alias for a standard glyph name). It is primarily intended to be
155 used when the client is subsetting a font that contains glyphs composed
156 using the seac operator. When a client selects such a glyph they must ensure
157 that the base and accent glyphs are also present in the subset. This may be
158 achieved by calling t1rGetGlyphByStdEnc() with the "bchar" and "achar"
159 parameters from the seac() glyph callback taking special note of the
160 ABF_GLYPH_SEEN flags parameter so that repeated glyph definitions are
161 avoided. */
162
163 int t1rResetGlyphs(t1rCtx h);
164
165 /* t1rResetGlyphs() may be called at any time after the t1rIterateGlyphs() or
166 t1rGetGlyphBy*() functions have been called to reset the record of the
167 glyphs seen (called back) by the client. This is achieved by clearing the
168 ABF_GLYPH_SEEN bit in the abfGlyphInfo flags field of each glyph.
169
170 A client wishing to have direct access to the charstring data may do so by
171 utilizing the tmp stream (T1R_TMP_STREAM_ID) offsets for subroutines and
172 charstrings. The per-Private-dictionary subroutine data is available via
173 t1rGetSubrs() (see below). The per-glyph charstring information is available
174 in the "abfGlyphInfo.sup" field. In order to obtain per-glyph region data
175 the client must ask for glyph data via one of the 5 functions specified
176 above and then issue an ABF_SKIP_RET from the glyphBeg() callback so that
177 the charstring is not parsed and called back in the usual manner. */
178
179 const float *t1rGetWV(t1rCtx h, long *nMasters);
180
181 /* t1rGetWV() returns the weight vector that was computed from the user design
182 vector supplied via the "UDV" parameter passed to t1rBegFont(). The weight
183 vector is returned as a pointer to an array of "nMasters" elements. The
184 "nMasters" parameter is set to 0 and the function returns NULL for single
185 master fonts. */
186
187 const ctlSubrs *t1rGetSubrs(t1rCtx h, int iFD, const ctlRegion **region);
188
189 /* t1rGetSubrs() returns per-Private-dictionary subroutine offset data for the
190 font dictionary specified by the "iFD" parameter. Temporary stream
191 (T1R_TMP_STREAM_ID) offsets are returned by this functions via the ctlSubrs
192 and ctlRegion structures. If the "iFD" is invalid the "region" parameter is
193 set to NULL and the function returns NULL. */
194
195 int t1rEndFont(t1rCtx h);
196
197 /* t1rEndFont() is called to terminate a font parse initiated with
198 t1rBegFont(). The source data stream is closed. */
199
200 void t1rFree(t1rCtx h);
201
202 /* t1rFree() destroys the library context and all the resources allocated to
203 it. The temporary and debug data streams are closed. */
204
205 enum {
206 #undef CTL_DCL_ERR
207 #define CTL_DCL_ERR(name, string) name,
208 #include "t1rerr.h"
209 t1rErrCount
210 };
211
212 /* Library functions return either zero (t1rSuccess) to indicate success or a
213 positive non-zero error code that is defined in the above enumeration that
214 is built from t1rerr.h. */
215
216 char *t1rErrStr(int err_code);
217
218 /* t1rErrStr() maps the "err_code" parameter to a null-terminated error
219 string. */
220
221 void t1rGetVersion(ctlVersionCallbacks *cb);
222
223 /* t1rGetVersion() returns the library version number and name via the client
224 callbacks passed with the "cb" parameter (see ctlshare.h). */
225
226 #ifdef __cplusplus
227 }
228 #endif
229
230 #endif /* T1READ_H */