1 /***************************************************************************/
2 /* */
3 /* ftsystem.h */
4 /* */
5 /* FreeType low-level system interface definition (specification). */
6 /* */
7 /* Copyright 1996-2001 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 /***************************************************************************/
19 #ifndef __FTSYSTEM_H__
20 #define __FTSYSTEM_H__
23 #include <ft2build.h>
26 FT_BEGIN_HEADER
28 /*************************************************************************/
29 /* */
30 /* <Section> */
31 /* system_interface */
32 /* */
33 /* <Title> */
34 /* System Interface */
35 /* */
36 /* <Abstract> */
37 /* How FreeType manages memory and i/o. */
38 /* */
39 /* <Description> */
40 /* This section contains various definitions related to memory */
41 /* management and i/o access. You need to understand this */
42 /* information if you want to use a custom memory manager or you own */
43 /* input i/o streams. */
44 /* */
45 /*************************************************************************/
48 /*************************************************************************/
49 /* */
50 /* M E M O R Y M A N A G E M E N T */
51 /* */
52 /*************************************************************************/
55 /*************************************************************************/
56 /* */
57 /* @type: */
58 /* FT_Memory */
59 /* */
60 /* @description: */
61 /* A handle to a given memory manager object, defined with a */
62 /* @FT_MemoryRec structure. */
63 /* */
64 typedef struct FT_MemoryRec_* FT_Memory;
67 /*************************************************************************/
68 /* */
69 /* @functype: */
70 /* FT_Alloc_Func */
71 /* */
72 /* @description: */
73 /* A function used to allocate `size' bytes from `memory'. */
74 /* */
75 /* @input: */
76 /* memory :: A handle to the source memory manager. */
77 /* */
78 /* size :: The size in bytes to allocate. */
79 /* */
80 /* @return: */
81 /* Address of new memory block. 0 in case of failure. */
82 /* */
83 typedef void*
84 (*FT_Alloc_Func)( FT_Memory memory,
85 long size );
88 /*************************************************************************/
89 /* */
90 /* @functype: */
91 /* FT_Free_Func */
92 /* */
93 /* @description: */
94 /* A function used to release a given block of memory. */
95 /* */
96 /* @input: */
97 /* memory :: A handle to the source memory manager. */
98 /* */
99 /* block :: The address of the target memory block. */
100 /* */
101 typedef void
102 (*FT_Free_Func)( FT_Memory memory,
103 void* block );
106 /*************************************************************************/
107 /* */
108 /* @functype: */
109 /* FT_Realloc_Func */
110 /* */
111 /* @description: */
112 /* a function used to re-allocate a given block of memory. */
113 /* */
114 /* @input: */
115 /* memory :: A handle to the source memory manager. */
116 /* */
117 /* cur_size :: The block's current size in bytes. */
118 /* */
119 /* new_size :: The block's requested new size. */
120 /* */
121 /* block :: The block's current address. */
122 /* */
123 /* @return: */
124 /* New block address. 0 in case of memory shortage. */
125 /* */
126 /* @note: */
127 /* In case of error, the old block must still be available. */
128 /* */
129 typedef void*
130 (*FT_Realloc_Func)( FT_Memory memory,
131 long cur_size,
132 long new_size,
133 void* block );
136 /*************************************************************************/
137 /* */
138 /* @struct: */
139 /* FT_MemoryRec */
140 /* */
141 /* @description: */
142 /* A structure used to describe a given memory manager to FreeType 2. */
143 /* */
144 /* @fields: */
145 /* user :: A generic typeless pointer for user data. */
146 /* */
147 /* alloc :: A pointer type to an allocation function. */
148 /* */
149 /* free :: A pointer type to an memory freeing function. */
150 /* */
151 /* realloc :: A pointer type to a reallocation function. */
152 /* */
153 struct FT_MemoryRec_
154 {
155 void* user;
156 FT_Alloc_Func alloc;
157 FT_Free_Func free;
158 FT_Realloc_Func realloc;
159 };
162 /*************************************************************************/
163 /* */
164 /* I / O M A N A G E M E N T */
165 /* */
166 /*************************************************************************/
169 /*************************************************************************/
170 /* */
171 /* @type: */
172 /* FT_Stream */
173 /* */
174 /* @description: */
175 /* A handle to an input stream. */
176 /* */
177 typedef struct FT_StreamRec_* FT_Stream;
180 /*************************************************************************/
181 /* */
182 /* @struct: */
183 /* FT_StreamDesc */
184 /* */
185 /* @description: */
186 /* A union type used to store either a long or a pointer. This is */
187 /* used to store a file descriptor or a FILE* in an input stream. */
188 /* */
189 typedef union FT_StreamDesc_
190 {
191 long value;
192 void* pointer;
194 } FT_StreamDesc;
197 /*************************************************************************/
198 /* */
199 /* @functype: */
200 /* FT_Stream_IO */
201 /* */
202 /* @description: */
203 /* A function used to seek and read data from a given input stream. */
204 /* */
205 /* @input: */
206 /* stream :: A handle to the source stream. */
207 /* */
208 /* offset :: The offset of read in stream (always from start). */
209 /* */
210 /* buffer :: The address of the read buffer. */
211 /* */
212 /* count :: The number of bytes to read from the stream. */
213 /* */
214 /* @return: */
215 /* The number of bytes effectively read by the stream. */
216 /* */
217 /* @note: */
218 /* This function might be called to perform a seek or skip operation */
219 /* with a `count' of 0. */
220 /* */
221 typedef unsigned long
222 (*FT_Stream_IO)( FT_Stream stream,
223 unsigned long offset,
224 unsigned char* buffer,
225 unsigned long count );
228 /*************************************************************************/
229 /* */
230 /* @functype: */
231 /* FT_Stream_Close */
232 /* */
233 /* @description: */
234 /* A function used to close a given input stream. */
235 /* */
236 /* @input: */
237 /* stream :: A handle to the target stream. */
238 /* */
239 typedef void
240 (*FT_Stream_Close)( FT_Stream stream );
243 /*************************************************************************/
244 /* */
245 /* @struct: */
246 /* FT_StreamRec */
247 /* */
248 /* @description: */
249 /* A structure used to describe an input stream. */
250 /* */
251 /* @input: */
252 /* base :: For memory-based streams, this is the address of the */
253 /* first stream byte in memory. This field should */
254 /* always be set to NULL for disk-based streams. */
255 /* */
256 /* size :: The stream size in bytes. */
257 /* */
258 /* pos :: The current position within the stream. */
259 /* */
260 /* descriptor :: This field is a union that can hold an integer or a */
261 /* pointer. It is used by stream implementations to */
262 /* store file descriptors or FILE* pointers. */
263 /* */
264 /* pathname :: This field is completely ignored by FreeType. */
265 /* However, it is often useful during debugging to use */
266 /* it to store the stream's filename (where available). */
267 /* */
268 /* read :: The stream's input function. */
269 /* */
270 /* close :: The stream;s close function. */
271 /* */
272 /* memory :: The memory manager to use to preload frames. This is */
273 /* set internally by FreeType and shouldn't be touched */
274 /* by stream implementations. */
275 /* */
276 /* cursor :: This field is set and used internally by FreeType */
277 /* when parsing frames. */
278 /* */
279 /* limit :: This field is set and used internally by FreeType */
280 /* when parsing frames. */
281 /* */
282 struct FT_StreamRec_
283 {
284 unsigned char* base;
285 unsigned long size;
286 unsigned long pos;
288 FT_StreamDesc descriptor;
289 FT_StreamDesc pathname;
290 FT_Stream_IO read;
291 FT_Stream_Close close;
293 FT_Memory memory;
294 unsigned char* cursor;
295 unsigned char* limit;
296 };
299 /* */
302 FT_END_HEADER
304 #endif /* __FTSYSTEM_H__ */
307 /* END */