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