Debian Codegraph @

podofo/3rdparty/adobe/afdko/include/sfntread.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 SFNTREAD_H
6 #define SFNTREAD_H
7
8 #include "ctlshare.h"
9
10 #define SFR_VERSION CTL_MAKE_VERSION(1, 0, 7)
11
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15
16 /* sfnt Format Table Handler
17 =========================
18 This library provides facilities for reading and returning table information
19 found in the header of sfnt-formatted data.
20
21 This library is initialized with a single call to sfrNew() which allocates
22 an opaque context (sfrCtx) which is passed to subsequent functions and is
23 destroyed by a single call to sfrFree(). Thus, multiple contexts may be
24 concurrently allocated permitting operation in a multi-threaded environment.
25
26 A new font is opened and the header is parsed and cached by calling
27 sfrBegFont(). Table data described by the sfrTable data structure may then
28 be accessed by using the sfrGetNextTable() and the sfrGetTableByTag()
29 functions. Finally, a font may be closed by calling sfrEndFont().
30
31 The library also provides support for reading TrueType Collections via the
32 sfrGetNextTTCOffset() function. */
33
34 typedef struct sfrCtx_ *sfrCtx;
35 sfrCtx sfrNew(ctlMemoryCallbacks *mem_cb, ctlStreamCallbacks *stm_cb,
36 CTL_CHECK_ARGS_DCL);
37
38 #define SFR_CHECK_ARGS CTL_CHECK_ARGS_CALL(SFR_VERSION)
39
40 /* sfrNew() initializes the library and returns an opaque context (sfrCtx) that
41 is subsequently passed to all the other library functions. It must be the
42 first function in the library to be called by the client. The client passes
43 a set of memory and stream callback functions (described in ctlshare.h) to
44 the library via the "mem_cb" and "stm_cb" parameters. If the library
45 couldn't be initialized, NULL is returned.
46
47 The SFR_CHECK_ARGS macro is passed as the last parameter to sfrNew() in
48 order to perform a client/library compatibility check. */
49
50 int sfrBegFont(sfrCtx h, void *stm, long origin, ctlTag *sfnt_tag);
51
52 /* sfrBegFont() is called to initiate a new sfnt parse. The "stm" parameter
53 controls source stream usage (described in ctlshare.h). If NULL, the
54 function will open the default source stream identified by SFR_SRC_STEAM_ID
55 in sfrBegFont() and close it in sfrEndFont(). If non-NULL, the client must
56 open the source stream and pass the stream object to the function via the
57 "stm" parameter, and must also close the stream after sfrEndFont() is
58 called. The "origin" parameter specifies the stream offset of the first byte
59 of the sfnt header. This offset is added to subsequent table offsets
60 returned to the client. The "sfnt_tag" parameter gets the 4-byte version tag
61 field from the sfnt header. If it doesn't match one of the known sfnt types,
62 listed below, the function returns an error. */
63
64 #define sfr_v1_0_tag CTL_TAG(0, 1, 0, 0) /* TrueType version 1.0 */
65
66 #define sfr_true_tag CTL_TAG('t', 'r', 'u', 'e') /* TrueType */
67 #define sfr_OTTO_tag CTL_TAG('O', 'T', 'T', 'O') /* OTF */
68 #define sfr_typ1_tag CTL_TAG('t', 'y', 'p', '1') /* Type 1 GX */
69 #define sfr_ttcf_tag CTL_TAG('t', 't', 'c', 'f') /* TrueType Collection */
70
71 /* A version tag of 'ttcf' indicates that the data represents a TrueType
72 Collection rather than a single sfnt. In this case the client must call
73 sfrGetNextTTCOffset() to obtain an offset of one of the sfnt members of the
74 collection. */
75
76 long sfrGetNextTTCOffset(sfrCtx h);
77
78 /* sfrGetNextTTCOffset() is called to iterate through the offsets in TrueType
79 Collection table directory. It must only be called if a previous call to
80 sfrBegFont() returned a version tag value of 'ttcf'. Repeated calls to
81 sfrGetNextTTCOffset() return successive offsets from the table directory
82 stating with the first. When all the offsets in the table directory have
83 been returned, the function returns 0 indicating the end of the list. The
84 next call will then wrap round to the beginning of the list and return the
85 first offset again.
86
87 A non-zero offset returned by sfrGetNextTTCOffset() can be passed as the
88 origin parameter to sfrBegFont() in order to parse one of the members of a
89 TrueType collection. Alternating calls to sfrGetNextTTCOffset() and
90 sfrBegFont() allow each TrueType Collection member sfnt to be parsed in
91 turn.
92
93 Note that the "stm" parameter is ignored in all but the first call to
94 sfrBegFont() when navigating TTC streams.
95
96 The offset returned by sfrGetNextTTCOffset() are adjusted by adding the
97 "origin" parameter passed to sfrBegFont() so that it always specifies the
98 absolute source data stream offset of the member sfnt. */
99
100 typedef struct
101 {
102 ctlTag tag;
103 unsigned long checksum;
104 unsigned long offset;
105 unsigned long length;
106 } sfrTable;
107
108 /* The sfrTable data structure represents the per-table data that is read from
109 the sfnt table directory and returned to the client. The "offset" field is
110 adjusted by adding the "origin" parameter passed to sfrBegFont() so that it
111 always specifies the absolute source data stream offset of the table
112 identified by the "tag" field. */
113
114 sfrTable *sfrGetNextTable(sfrCtx h);
115
116 /* sfrGetNextTable() is called to iterate through all the tables in the table
117 directory of the sfnt. It must only be called if the last call to
118 sfrBegFont() returned a valid tag whose value wasn't 'ttcf'. Repeated calls
119 to sfrGetNextTable() return successive table directory entries starting with
120 the first. When all the entries in the table directory have been returned,
121 the function returns NULL indicating the end of the list. The next call will
122 then wrap round to the beginning of the list and return the first entry
123 again. */
124
125 sfrTable *sfrGetTableByTag(sfrCtx h, ctlTag tag);
126
127 /* sfrGetTableByTag() may be called to obtain the table directory entry for a
128 table specified by the "tag" parameter. NULL is returned if there is no
129 matching table.
130
131 When the client has obtained a non-NULL table directory entry by calling
132 either sfrGetNextTable() or sfrGetTableByTag() the table data can be
133 accessed by seeking to the offset given by the "offset" field. This offset
134 is automatically converted from a relative offset to and absolute offset by
135 adding in the "origin" offset supplied to the sfrBegFont() call. */
136
137 int sfrEndFont(sfrCtx h);
138
139 /* sfrEndFont() is called to terminate the current sfnt parse initiated by
140 sfrBegFont(). */
141
142 void sfrFree(sfrCtx h);
143
144 /* sfrFree() destroys the library context and all the resources allocated to
145 it. */
146
147 enum {
148 #undef CTL_DCL_ERR
149 #define CTL_DCL_ERR(name, string) name,
150 #include "sfrerr.h"
151 sfrErrCount
152 };
153
154 /* Library functions return either zero (sfrSuccess) to indicate success or a
155 positive non-zero error code that is defined in the above enumeration that
156 is built from sfrerr.h. */
157
158 char *sfrErrStr(int err_code);
159
160 /* sfrErrStr() maps the "err_code" parameter to a null-terminated error
161 string. */
162
163 void sfrGetVersion(ctlVersionCallbacks *cb);
164
165 /* sfrGetVersion() returns the library version number and name via the client
166 callbacks passed with the "cb" parameter (see ctlshare.h). */
167
168 #ifdef __cplusplus
169 }
170 #endif
171
172 #endif /* SFNTREAD_H */