Debian Codegraph @

podofo/3rdparty/adobe/afdko/include/cffread.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 PUBLIC_CFFREAD_H
6 #define PUBLIC_CFFREAD_H
7
8 #include "ctlshare.h"
9
10 #define CFR_VERSION CTL_MAKE_VERSION(2, 1, 3)
11
12 #include "absfont.h"
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 /* Compact Font Format (CFF) Parser Library
19 ========================================
20 This library parses information in CFF FontSets containing only one single
21 master or CID-keyed font.
22
23 This library is initialized with a single call to cfrNew() which allocates
24 an opaque context (cfrCtx) which is passed to subsequent functions and is
25 destroyed by a single call to cfrFree(). Thus, multiple contexts may be
26 concurrently allocated permitting operation in a multi-threaded environment.
27
28 A new font is opened and parsed and top level font data is returned by
29 calling cfrBegFont(). Glyph data may then be accessed using the
30 cfrIterateGlyphs(), cfrGetGlyphByTag(), cfrGetGlyphByName(),
31 cfrGetGlyphByCID() or t1cGetByStdEnc() functions.
32
33 The regions of the source stream occupied by various CFF data structs may be
34 obtained by calling cfrGetSingleRegions() and cfrGetRepeatRegions(). The
35 values associated with the "defaultWidthX" and "nominalWidthX" DICT
36 operators may be obtained by calling cfrGetWidths().
37
38 Finally, a font may be closed by calling cfrEndFont(). */
39
40 typedef struct cfrCtx_ *cfrCtx;
41 cfrCtx cfrNew(ctlMemoryCallbacks *mem_cb, ctlStreamCallbacks *stm_cb,
42 CTL_CHECK_ARGS_DCL);
43
44 #define CFR_CHECK_ARGS CTL_CHECK_ARGS_CALL(CFR_VERSION)
45
46 /* cfrNew() initializes the library and returns an opaque context (cfrCtx) that
47 is subsequently passed to all the other library functions. It must be the
48 first function in the library to be called by the client. The client passes
49 a set of memory and stream callback functions (described in ctlshare.h) to
50 the library via the mem_cb and stm_cb parameters.
51
52 The CFR_CHECK_ARGS macro is passed as the last parameter to cfrNew() in
53 order to perform a client/library compatibility check.
54
55 The optional debug data stream (CFR_DBG_STREAM_ID) is opened by this call.
56 The debug stream provides more detailed error and warning messages than is
57 available via cfrErrStr(). If the client doesn't require the debug data
58 stream, NULL should be returned from its stream open call. */
59
60 int cfrBegFont(cfrCtx h, long flags, long origin, int ttcIndex, abfTopDict **top, float *UDV);
61
62 #define CFR_UPDATE_OPS (1 << 0)
63 #define CFR_USE_MATRIX (1 << 1)
64 #define CFR_NO_ENCODING (1 << 2)
65 #define CFR_SHALLOW_READ (1 << 3)
66 #define CFR_SEEN_GLYPH (1 << 6) /* have seen a glyph */
67 #define CFR_FLATTEN_VF (1 << 8)
68 #define CFR_SHORT_VF_NAME (1 << 9)
69 #define CFR_UNUSE_VF_NAMED_INSTANCE (1 << 10)
70 #define CFR_CFF2_ONLY (1<<11)
71
72 /* cfrBegFont() is called to initiate a new font parse. The source data stream
73 (CFR_SRC_STREAM_ID) is opened, positioned at the offset specified by the
74 "origin" parameter, parsed, and dictionary values are stored in the data
75 structure pointed to by the "top" parameter (which will remain stable until
76 cfrEndFont() is called).
77
78 The "origin" parameter can either be the stream offset of the first
79 byte of a CFF header or the first byte of an OpenType font (OTF), or
80 the first byte of an TTC font which contains OTF fonts. In the latter
81 two cases the library will automatically locate the CFF table and
82 seek to it before attempting to parse the CFF data.
83
84 The ttcIndex parameter selects which font to use in a TTC. This has effect
85 only when the font file is a TTC font.
86
87 The "flags" parameter allows client control over the parse by setting bits
88 as follows:
89
90 CFR_UPDATE_OPS - charstrings using the deprecated seac operator are
91 converted to a regular path by combining the component glyphs and the
92 deprecated dotsection operator is removed
93
94 CFR_USE_MATRIX - transform charstring path coordinates using the font's own
95 FontMatrix. This facility would not normally be used during font format
96 conversion since it is generally better to leave the path coordinates
97 unmodified and specify a non-default matrix in the font. However, it is
98 useful for drawing or manipulating glyph outline data.
99
100 CFR_NO_ENCODING - don't read the encoding and set all glyphs unencoded. This
101 options should be used when reading the CFF table from an OTF font since
102 the font is encoded using the data in the cmap table and not CFF table.
103
104 CFR_SHALLOW_READ - don't read FDArray or glyph related data like the
105 charstring, the charset, or the encoding data. This flag should be used when
106 the client wants to read only the following information quickly: name INDEX,
107 string INDEX, gsubrs INDEX, and top dict. Glyph access functions like
108 cfrIterateGlyphs, cfrGetGlyphByTag, cfrGetGlyphByName, cfrGetGlyphByCID may
109 not be called with a font parsed with this flag set.
110
111 CFR_FLATTEN_VF - flatten CFF2 variable font data for a given user design
112 vector.
113
114 CFR_SHORT_VF_NAME - when flattening a CFF2 variable font, a generated
115 instance PS name will be limited to 63 characters, as opposed to 127
116 characters as documented in Adobe Tech Notes 5902.
117
118 CFR_UNUSE_VF_NAMED_INSTANCE - when flattening a CFF2 variable font, the
119 instance PS name is generated from the design vector as documented in Tech
120 Notes 5902 regarding named instances in the fvar table. If the flag is
121 unset, a PS name of a named instance is used if there is a match.
122
123 CFR_CFF2_ONLY - don't read the CFF table even if it is available in the font along with CFF2.
124 This flag is assumed when CFR_FLATTEN_VF is set.
125
126 The "UDV" parameter specifies the User Design Vector to be used in
127 flattening (snapshotting) a CFF2 variable font. If NULL, the font is
128 flattened at the default instance. The parameter may be set to NULL for
129 non-variable fonts.
130 */
131
132 int cfrIterateGlyphs(cfrCtx h, abfGlyphCallbacks *glyph_cb);
133
134 /* cfrIterateGlyphs() is called to iterate through all the glyph data in the
135 font. (The number of glyphs in the font is passed back to the client via the
136 "top" parameter to cfrBegFont() in the "sup.nGlyphs" field.) Glyph data is
137 passed back to the client via the callbacks specified via the "glyph_cb"
138 parameter (see absfont.h).
139
140 Glyphs are presented to the client in glyph index order. Each glyph may be
141 identified from the "info" parameter that is passed back to the client via
142 the beg() callback (the glyph index is specified via the "tag" field).
143
144 The client can control whether path data is read or ignored by the value
145 returned from beg() and can thus use this interface to select a subset of
146 glyphs or just enumerate the glyph set without reading any path data. */
147
148 int cfrGetGlyphByTag(cfrCtx h,
149 unsigned short tag, abfGlyphCallbacks *glyph_cb);
150 int cfrGetGlyphByName(cfrCtx h,
151 char *gname, abfGlyphCallbacks *glyph_cb);
152 int cfrGetGlyphByCID(cfrCtx h,
153 unsigned short cid, abfGlyphCallbacks *glyph_cb);
154
155 /* cfrGetGlyphByTag(), cfrGetGlyphByName(), cfrGetGlyphByCID() are called
156 obtain glyph data from a glyph selected by its tag (described above), its
157 name, or its CID, respectively. The glyph name is specified by as a
158 null-terminated string via the "gname" parameter.
159
160 These functions return cfrErrNoGlyph if the requested glyph is not present
161 in the font or the access method is incompatible with the font type. */
162
163 int cfrGetGlyphByStdEnc(cfrCtx h, int stdcode, abfGlyphCallbacks *glyph_cb);
164
165 /* cfrGetGlyphByStdEnc() is called to obtain glyph data from a glyph selected
166 by its standard encoding specified by the "stdcode" parameter (which is
167 really an alias for a standard glyph name). It is primarily intended to be
168 used when the client is subsetting a font that contains glyphs composed
169 using the seac operator. When a client selects such a glyph they must ensure
170 that the base and accent glyphs are also present in the subset. This may be
171 achieved by calling cfrGetStdEncGlyph() with the "bchar" and "achar"
172 parameters from the seac() glyph callback taking special note of the
173 ABF_GLYPH_SEEN flags parameter so that repeated glyph definitions are
174 avoided. */
175
176 int cfrResetGlyphs(cfrCtx h);
177
178 /* cfrResetGlyphs() may be called at any time after the cfrIterateGlyphs() or
179 cfrGetGlyphBy*() functions have been called to reset the record of the
180 glyphs seen (called back) by the client. This is achieved by clearing the
181 ABF_GLYPH_SEEN bit in the abfGlyphInfo flags field of each glyph.
182
183 A client wishing to have direct access to the charstring data may do so by
184 utilizing the source stream (CFR_SRC_STREAM_ID) offsets for subroutines and
185 charstrings. The regions of the source stream occupied by the global subr
186 INDEX and the local subr INDEX are available via cfrGetSingleRegions() and
187 cfrGetRepeatRegions(). The per-glyph charstring information is available in
188 the "abfGlyphInfo.sup" field. In order to obtain per-glyph offset data the
189 client must ask for glyph data via one of the 5 functions specified above
190 and then issue an ABF_SKIP_RET from the glyphBeg() callback so that the
191 charstring is not parsed and called back in the usual manner. */
192
193 typedef struct
194 {
195 ctlRegion Header;
196 ctlRegion NameINDEX;
197 ctlRegion TopDICTINDEX;
198 ctlRegion StringINDEX;
199 ctlRegion GlobalSubrINDEX;
200 ctlRegion Encoding;
201 ctlRegion Charset;
202 ctlRegion FDSelect;
203 ctlRegion VarStore;
204 ctlRegion CharStringsINDEX;
205 ctlRegion FDArrayINDEX;
206 } cfrSingleRegions;
207
208 const cfrSingleRegions *cfrGetSingleRegions(cfrCtx h);
209
210 /* cfrGetSingleRegions() is called to get the src stream regions occupied by
211 the CFF data struct identified by its field name. This functions returns a
212 pointer to a structure containing regions that appear only once per-font.
213
214 Note: The "Encoding" and "Charset" regions need special processing because
215 the "begin" field of the region either contains a predefined encoding or
216 charset value or it contains the stream offset of a custom encoding. In the
217 former case the "end" field of the region contains -1 and in the later case
218 it contains the byte following the custom encoding.
219
220 Predefined encoding and charset values are enumerated in dictops.h. */
221
222 typedef struct
223 {
224 ctlRegion PrivateDICT;
225 ctlRegion LocalSubrINDEX;
226 } cfrRepeatRegions;
227
228 const cfrRepeatRegions *cfrGetRepeatRegions(cfrCtx h, int iFD);
229
230 /* cfrGetRepeatRegions() is called to get the src stream regions occupied by
231 the CFF data struct identified by its field name. This function returns a
232 pointer to a structure containing regions in the FDArray that may appear
233 more than once per-font. The "iFD" parameter selects the font dictionary
234 containing the regions to be returned. If the "iFD" parameter is invalid a
235 NULL pointer is returned.
236
237 Note: a Private DICT is required but it may be empty (0-length). */
238
239 int cfrGetWidths(cfrCtx h, int iFD,
240 float *defaultWidthX, float *nominalWidthX);
241
242 /* cfrGetWidths() is called to get the values of the default and nominal widths
243 associated with a font dictionary selected by the "iFD" parameter. The
244 function returns 0 on success and 1 if the "iFD" parameter is invalid. */
245
246 const unsigned char *cfrGetStdEnc2GIDMap(cfrCtx h);
247
248 /* cfrGetStdEnc2GIDMap() returns an array of 256 elements which map character
249 codes in standard encoding to glyph indexes for the current font. It is
250 intended to be used for rasterizing glyphs that use the deprecated Type 2
251 seac specification which is encoded as a 4-operand endchar operator. Glyphs
252 in fonts using seac are expected to be ordered by their SID and therefore
253 the maximum glyph index of a glyph in standard encoding is 149 (germandbls)
254 which can easily be stored in a byte. */
255
256 int cfrEndFont(cfrCtx h);
257
258 /* cfrEndFont() is called to terminate a font parse initiated with
259 cfrBegFont(). The input stream is closed as a result of calling this
260 function. */
261
262 void cfrFree(cfrCtx h);
263
264 /* cfrFree() destroys the library context and all the resources allocated to
265 it. */
266
267 typedef long (*cfrlastResortInstanceNameCallback)(void *clientCtx, float *udv, long numAxes,
268 char *prefixStr, long prefixLen,
269 char *nameBuffer, long nameBufferLen);
270 /* CFF2 variable font last resort naming callback
271
272 If successful, the function should return a positive length of the string
273 returned in nameBuffer.
274
275 If unsuccessful, the function returns a non-positive number.
276
277 clientCtx - context pointer passed to cfrSetLastResortInstanceNameCallback
278
279 udv - user design vector specifying the variable font instance
280
281 numAxes - the number of axes, or the length of udv array
282
283 prefixStr - a null-terminated string of the variable font family name,
284 to be used as a prefix of the instance name
285
286 prefixLen - length of the prefix string
287
288 nameBuffer - string buffer where a null-terminated Postscript name of the
289 variable font instance should be returned by the client
290
291 nameBufferLen - the length of the nameBuffer (including a null-byte) */
292
293 void cfrSetLastResortInstanceNameCallback(cfrCtx h, cfrlastResortInstanceNameCallback cb, void *clientCtx);
294
295 /* cfrSetLastResortInstanceNameCallback() allows a client to provide a callback
296 function to be called when a flattened CFF2 variable font cannot be
297 determined with a named instance in the fvar table or using the algorithm
298 described in Adobe TechNotes 5902 "Generating PostScript Names for Fonts
299 Using OpenType Font Variations". The callback function is called to give the
300 client a chance to name a font instance adequately.
301
302 If no callback is provided, a last-resort instance is named as a font family
303 name prefix followed by "-<hex>" where <hex> is a hex string generated by
304 hashing the design vector of the instance. */
305
306 enum {
307 #undef CTL_DCL_ERR
308 #define CTL_DCL_ERR(name, string) name,
309 #include "cfrerr.h"
310 cfrErrCount
311 };
312
313 /* Library functions return either zero (cfrSuccess) to indicate success or a
314 positive non-zero error code that is defined in the above enumeration that
315 is built from cfrerr.h. */
316
317 char *cfrErrStr(int err_code);
318
319 /* cfrErrStr() maps the "err_code" parameter to a null-terminated error
320 string. */
321
322 void cfrGetVersion(ctlVersionCallbacks *cb);
323
324 /* cfrGetVersion() returns the library version number and name via the client
325 callbacks passed with the "cb" parameter (see ctlshare.h). */
326
327 #ifdef __cplusplus
328 }
329 #endif
330
331 #endif /* PUBLIC_CFFREAD_H */