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