1 /***************************************************************************/
2 /* */
3 /* ftsystem.h */
4 /* */
5 /* FreeType low-level system interface definition (specification). */
6 /* */
7 /* Copyright 1996-2018 by */
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
9 /* */
10 /* This file is part of the FreeType project, and may only be used, */
11 /* modified, and distributed under the terms of the FreeType project */
12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
13 /* this file you indicate that you have read the license and */
14 /* understand and accept it fully. */
15 /* */
16 /***************************************************************************/
17
18
19 #ifndef FTSYSTEM_H_
20 #define FTSYSTEM_H_
21
22
23 #include <ft2build.h>
24
25
26 FT_BEGIN_HEADER
27
28
29 /*************************************************************************/
30 /* */
31 /* <Section> */
32 /* system_interface */
33 /* */
34 /* <Title> */
35 /* System Interface */
36 /* */
37 /* <Abstract> */
38 /* How FreeType manages memory and i/o. */
39 /* */
40 /* <Description> */
41 /* This section contains various definitions related to memory */
42 /* management and i/o access. You need to understand this */
43 /* information if you want to use a custom memory manager or you own */
44 /* i/o streams. */
45 /* */
46 /*************************************************************************/
47
48
49 /*************************************************************************/
50 /* */
51 /* M E M O R Y M A N A G E M E N T */
52 /* */
53 /*************************************************************************/
54
55
56 /*************************************************************************
57 *
58 * @type:
59 * FT_Memory
60 *
61 * @description:
62 * A handle to a given memory manager object, defined with an
63 * @FT_MemoryRec structure.
64 *
65 */
66 typedef struct FT_MemoryRec_* FT_Memory;
67
68
69 /*************************************************************************
70 *
71 * @functype:
72 * FT_Alloc_Func
73 *
74 * @description:
75 * A function used to allocate `size' bytes from `memory'.
76 *
77 * @input:
78 * memory ::
79 * A handle to the source memory manager.
80 *
81 * size ::
82 * The size in bytes to allocate.
83 *
84 * @return:
85 * Address of new memory block. 0~in case of failure.
86 *
87 */
88 typedef void*
89 (*FT_Alloc_Func)( FT_Memory memory,
90 long size );
91
92
93 /*************************************************************************
94 *
95 * @functype:
96 * FT_Free_Func
97 *
98 * @description:
99 * A function used to release a given block of memory.
100 *
101 * @input:
102 * memory ::
103 * A handle to the source memory manager.
104 *
105 * block ::
106 * The address of the target memory block.
107 *
108 */
109 typedef void
110 (*FT_Free_Func)( FT_Memory memory,
111 void* block );
112
113
114 /*************************************************************************
115 *
116 * @functype:
117 * FT_Realloc_Func
118 *
119 * @description:
120 * A function used to re-allocate a given block of memory.
121 *
122 * @input:
123 * memory ::
124 * A handle to the source memory manager.
125 *
126 * cur_size ::
127 * The block's current size in bytes.
128 *
129 * new_size ::
130 * The block's requested new size.
131 *
132 * block ::
133 * The block's current address.
134 *
135 * @return:
136 * New block address. 0~in case of memory shortage.
137 *
138 * @note:
139 * In case of error, the old block must still be available.
140 *
141 */
142 typedef void*
143 (*FT_Realloc_Func)( FT_Memory memory,
144 long cur_size,
145 long new_size,
146 void* block );
147
148
149 /*************************************************************************
150 *
151 * @struct:
152 * FT_MemoryRec
153 *
154 * @description:
155 * A structure used to describe a given memory manager to FreeType~2.
156 *
157 * @fields:
158 * user ::
159 * A generic typeless pointer for user data.
160 *
161 * alloc ::
162 * A pointer type to an allocation function.
163 *
164 * free ::
165 * A pointer type to an memory freeing function.
166 *
167 * realloc ::
168 * A pointer type to a reallocation function.
169 *
170 */
171 struct FT_MemoryRec_
172 {
173 void* user;
174 FT_Alloc_Func alloc;
175 FT_Free_Func free;
176 FT_Realloc_Func realloc;
177 };
178
179
180 /*************************************************************************/
181 /* */
182 /* I / O M A N A G E M E N T */
183 /* */
184 /*************************************************************************/
185
186
187 /*************************************************************************
188 *
189 * @type:
190 * FT_Stream
191 *
192 * @description:
193 * A handle to an input stream.
194 *
195 * @also:
196 * See @FT_StreamRec for the publicly accessible fields of a given
197 * stream object.
198 *
199 */
200 typedef struct FT_StreamRec_* FT_Stream;
201
202
203 /*************************************************************************
204 *
205 * @struct:
206 * FT_StreamDesc
207 *
208 * @description:
209 * A union type used to store either a long or a pointer. This is used
210 * to store a file descriptor or a `FILE*' in an input stream.
211 *
212 */
213 typedef union FT_StreamDesc_
214 {
215 long value;
216 void* pointer;
217
218 } FT_StreamDesc;
219
220
221 /*************************************************************************
222 *
223 * @functype:
224 * FT_Stream_IoFunc
225 *
226 * @description:
227 * A function used to seek and read data from a given input stream.
228 *
229 * @input:
230 * stream ::
231 * A handle to the source stream.
232 *
233 * offset ::
234 * The offset of read in stream (always from start).
235 *
236 * buffer ::
237 * The address of the read buffer.
238 *
239 * count ::
240 * The number of bytes to read from the stream.
241 *
242 * @return:
243 * The number of bytes effectively read by the stream.
244 *
245 * @note:
246 * This function might be called to perform a seek or skip operation
247 * with a `count' of~0. A non-zero return value then indicates an
248 * error.
249 *
250 */
251 typedef unsigned long
252 (*FT_Stream_IoFunc)( FT_Stream stream,
253 unsigned long offset,
254 unsigned char* buffer,
255 unsigned long count );
256
257
258 /*************************************************************************
259 *
260 * @functype:
261 * FT_Stream_CloseFunc
262 *
263 * @description:
264 * A function used to close a given input stream.
265 *
266 * @input:
267 * stream ::
268 * A handle to the target stream.
269 *
270 */
271 typedef void
272 (*FT_Stream_CloseFunc)( FT_Stream stream );
273
274
275 /*************************************************************************
276 *
277 * @struct:
278 * FT_StreamRec
279 *
280 * @description:
281 * A structure used to describe an input stream.
282 *
283 * @input:
284 * base ::
285 * For memory-based streams, this is the address of the first stream
286 * byte in memory. This field should always be set to NULL for
287 * disk-based streams.
288 *
289 * size ::
290 * The stream size in bytes.
291 *
292 * In case of compressed streams where the size is unknown before
293 * actually doing the decompression, the value is set to 0x7FFFFFFF.
294 * (Note that this size value can occur for normal streams also; it is
295 * thus just a hint.)
296 *
297 * pos ::
298 * The current position within the stream.
299 *
300 * descriptor ::
301 * This field is a union that can hold an integer or a pointer. It is
302 * used by stream implementations to store file descriptors or `FILE*'
303 * pointers.
304 *
305 * pathname ::
306 * This field is completely ignored by FreeType. However, it is often
307 * useful during debugging to use it to store the stream's filename
308 * (where available).
309 *
310 * read ::
311 * The stream's input function.
312 *
313 * close ::
314 * The stream's close function.
315 *
316 * memory ::
317 * The memory manager to use to preload frames. This is set
318 * internally by FreeType and shouldn't be touched by stream
319 * implementations.
320 *
321 * cursor ::
322 * This field is set and used internally by FreeType when parsing
323 * frames.
324 *
325 * limit ::
326 * This field is set and used internally by FreeType when parsing
327 * frames.
328 *
329 */
330 typedef struct FT_StreamRec_
331 {
332 unsigned char* base;
333 unsigned long size;
334 unsigned long pos;
335
336 FT_StreamDesc descriptor;
337 FT_StreamDesc pathname;
338 FT_Stream_IoFunc read;
339 FT_Stream_CloseFunc close;
340
341 FT_Memory memory;
342 unsigned char* cursor;
343 unsigned char* limit;
344
345 } FT_StreamRec;
346
347 /* */
348
349
350 FT_END_HEADER
351
352 #endif /* FTSYSTEM_H_ */
353
354
355 /* END */