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