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