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