1/***************************************************************************/
2/* */
3/* ftsystem.h */
4/* */
5/* FreeType low-level system interface definition (specification). */
6/* */
7/* Copyright 1996-2001, 2002, 2005, 2010 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
26FT_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 */
196 typedef struct FT_StreamRec_* FT_Stream;
197
198
199 /*************************************************************************
200 *
201 * @struct:
202 * FT_StreamDesc
203 *
204 * @description:
205 * A union type used to store either a long or a pointer. This is used
206 * to store a file descriptor or a `FILE*' in an input stream.
207 *
208 */
209 typedef union FT_StreamDesc_
210 {
211 long value;
212 void* pointer;
213
214 } FT_StreamDesc;
215
216
217 /*************************************************************************
218 *
219 * @functype:
220 * FT_Stream_IoFunc
221 *
222 * @description:
223 * A function used to seek and read data from a given input stream.
224 *
225 * @input:
226 * stream ::
227 * A handle to the source stream.
228 *
229 * offset ::
230 * The offset of read in stream (always from start).
231 *
232 * buffer ::
233 * The address of the read buffer.
234 *
235 * count ::
236 * The number of bytes to read from the stream.
237 *
238 * @return:
239 * The number of bytes effectively read by the stream.
240 *
241 * @note:
242 * This function might be called to perform a seek or skip operation
243 * with a `count' of~0. A non-zero return value then indicates an
244 * error.
245 *
246 */
247 typedef unsigned long
248 (*FT_Stream_IoFunc)( FT_Stream stream,
249 unsigned long offset,
250 unsigned char* buffer,
251 unsigned long count );
252
253
254 /*************************************************************************
255 *
256 * @functype:
257 * FT_Stream_CloseFunc
258 *
259 * @description:
260 * A function used to close a given input stream.
261 *
262 * @input:
263 * stream ::
264 * A handle to the target stream.
265 *
266 */
267 typedef void
268 (*FT_Stream_CloseFunc)( FT_Stream stream );
269
270
271 /*************************************************************************
272 *
273 * @struct:
274 * FT_StreamRec
275 *
276 * @description:
277 * A structure used to describe an input stream.
278 *
279 * @input:
280 * base ::
281 * For memory-based streams, this is the address of the first stream
282 * byte in memory. This field should always be set to NULL for
283 * disk-based streams.
284 *
285 * size ::
286 * The stream size in bytes.
287 *
288 * pos ::
289 * The current position within the stream.
290 *
291 * descriptor ::
292 * This field is a union that can hold an integer or a pointer. It is
293 * used by stream implementations to store file descriptors or `FILE*'
294 * pointers.
295 *
296 * pathname ::
297 * This field is completely ignored by FreeType. However, it is often
298 * useful during debugging to use it to store the stream's filename
299 * (where available).
300 *
301 * read ::
302 * The stream's input function.
303 *
304 * close ::
305 * The stream's close function.
306 *
307 * memory ::
308 * The memory manager to use to preload frames. This is set
309 * internally by FreeType and shouldn't be touched by stream
310 * implementations.
311 *
312 * cursor ::
313 * This field is set and used internally by FreeType when parsing
314 * frames.
315 *
316 * limit ::
317 * This field is set and used internally by FreeType when parsing
318 * frames.
319 *
320 */
321 typedef struct FT_StreamRec_
322 {
323 unsigned char* base;
324 unsigned long size;
325 unsigned long pos;
326
327 FT_StreamDesc descriptor;
328 FT_StreamDesc pathname;
329 FT_Stream_IoFunc read;
330 FT_Stream_CloseFunc close;
331
332 FT_Memory memory;
333 unsigned char* cursor;
334 unsigned char* limit;
335
336 } FT_StreamRec;
337
338
339 /* */
340
341
342FT_END_HEADER
343
344#endif /* __FTSYSTEM_H__ */
345
346
347/* END */
348