1/****************************************************************************
2 *
3 * ftsystem.h
4 *
5 * FreeType low-level system interface definition (specification).
6 *
7 * Copyright (C) 1996-2023 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 from the start of the stream to seek to.
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 * If count >~0, return the number of bytes effectively read by the
242 * stream (after seeking to `offset`). If count ==~0, return the status
243 * of the seek operation (non-zero indicates an error).
244 *
245 */
246 typedef unsigned long
247 (*FT_Stream_IoFunc)( FT_Stream stream,
248 unsigned long offset,
249 unsigned char* buffer,
250 unsigned long count );
251
252
253 /**************************************************************************
254 *
255 * @functype:
256 * FT_Stream_CloseFunc
257 *
258 * @description:
259 * A function used to close a given input stream.
260 *
261 * @input:
262 * stream ::
263 * A handle to the target stream.
264 *
265 */
266 typedef void
267 (*FT_Stream_CloseFunc)( FT_Stream stream );
268
269
270 /**************************************************************************
271 *
272 * @struct:
273 * FT_StreamRec
274 *
275 * @description:
276 * A structure used to describe an input stream.
277 *
278 * @input:
279 * base ::
280 * For memory-based streams, this is the address of the first stream
281 * byte in memory. This field should always be set to `NULL` for
282 * disk-based streams.
283 *
284 * size ::
285 * The stream size in bytes.
286 *
287 * In case of compressed streams where the size is unknown before
288 * actually doing the decompression, the value is set to 0x7FFFFFFF.
289 * (Note that this size value can occur for normal streams also; it is
290 * thus just a hint.)
291 *
292 * pos ::
293 * The current position within the stream.
294 *
295 * descriptor ::
296 * This field is a union that can hold an integer or a pointer. It is
297 * used by stream implementations to store file descriptors or `FILE*`
298 * pointers.
299 *
300 * pathname ::
301 * This field is completely ignored by FreeType. However, it is often
302 * useful during debugging to use it to store the stream's filename
303 * (where available).
304 *
305 * read ::
306 * The stream's input function.
307 *
308 * close ::
309 * The stream's close function.
310 *
311 * memory ::
312 * The memory manager to use to preload frames. This is set internally
313 * by FreeType and shouldn't be touched by stream implementations.
314 *
315 * cursor ::
316 * This field is set and used internally by FreeType when parsing
317 * frames. In particular, the `FT_GET_XXX` macros use this instead of
318 * the `pos` field.
319 *
320 * limit ::
321 * This field is set and used internally by FreeType when parsing
322 * frames.
323 *
324 */
325 typedef struct FT_StreamRec_
326 {
327 unsigned char* base;
328 unsigned long size;
329 unsigned long pos;
330
331 FT_StreamDesc descriptor;
332 FT_StreamDesc pathname;
333 FT_Stream_IoFunc read;
334 FT_Stream_CloseFunc close;
335
336 FT_Memory memory;
337 unsigned char* cursor;
338 unsigned char* limit;
339
340 } FT_StreamRec;
341
342 /* */
343
344
345FT_END_HEADER
346
347#endif /* FTSYSTEM_H_ */
348
349
350/* END */
351