| 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 */ |