1/***************************************************************************/
2/*                                                                         */
3/*  ftsystem.h                                                             */
4/*                                                                         */
5/*    FreeType low-level system interface definition (specification).      */
6/*                                                                         */
7/*  Copyright 1996-2001, 2002, 2005, 2010 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
26FT_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   */
196  typedef struct FT_StreamRec_*  FT_Stream;
197
198
199  /*************************************************************************
200   *
201   * @struct:
202   *   FT_StreamDesc
203   *
204   * @description:
205   *   A union type used to store either a long or a pointer.  This is used
206   *   to store a file descriptor or a `FILE*' in an input stream.
207   *
208   */
209  typedef union  FT_StreamDesc_
210  {
211    long   value;
212    void*  pointer;
213
214  } FT_StreamDesc;
215
216
217  /*************************************************************************
218   *
219   * @functype:
220   *   FT_Stream_IoFunc
221   *
222   * @description:
223   *   A function used to seek and read data from a given input stream.
224   *
225   * @input:
226   *   stream ::
227   *     A handle to the source stream.
228   *
229   *   offset ::
230   *     The offset of read in stream (always from start).
231   *
232   *   buffer ::
233   *     The address of the read buffer.
234   *
235   *   count ::
236   *     The number of bytes to read from the stream.
237   *
238   * @return:
239   *   The number of bytes effectively read by the stream.
240   *
241   * @note:
242   *   This function might be called to perform a seek or skip operation
243   *   with a `count' of~0.  A non-zero return value then indicates an
244   *   error.
245   *
246   */
247  typedef unsigned long
248  (*FT_Stream_IoFunc)( FT_Stream       stream,
249                       unsigned long   offset,
250                       unsigned char*  buffer,
251                       unsigned long   count );
252
253
254  /*************************************************************************
255   *
256   * @functype:
257   *   FT_Stream_CloseFunc
258   *
259   * @description:
260   *   A function used to close a given input stream.
261   *
262   * @input:
263   *  stream ::
264   *     A handle to the target stream.
265   *
266   */
267  typedef void
268  (*FT_Stream_CloseFunc)( FT_Stream  stream );
269
270
271  /*************************************************************************
272   *
273   * @struct:
274   *   FT_StreamRec
275   *
276   * @description:
277   *   A structure used to describe an input stream.
278   *
279   * @input:
280   *   base ::
281   *     For memory-based streams, this is the address of the first stream
282   *     byte in memory.  This field should always be set to NULL for
283   *     disk-based streams.
284   *
285   *   size ::
286   *     The stream size in bytes.
287   *
288   *   pos ::
289   *     The current position within the stream.
290   *
291   *   descriptor ::
292   *     This field is a union that can hold an integer or a pointer.  It is
293   *     used by stream implementations to store file descriptors or `FILE*'
294   *     pointers.
295   *
296   *   pathname ::
297   *     This field is completely ignored by FreeType.  However, it is often
298   *     useful during debugging to use it to store the stream's filename
299   *     (where available).
300   *
301   *   read ::
302   *     The stream's input function.
303   *
304   *   close ::
305   *     The stream's close function.
306   *
307   *   memory ::
308   *     The memory manager to use to preload frames.  This is set
309   *     internally by FreeType and shouldn't be touched by stream
310   *     implementations.
311   *
312   *   cursor ::
313   *     This field is set and used internally by FreeType when parsing
314   *     frames.
315   *
316   *   limit ::
317   *     This field is set and used internally by FreeType when parsing
318   *     frames.
319   *
320   */
321  typedef struct  FT_StreamRec_
322  {
323    unsigned char*       base;
324    unsigned long        size;
325    unsigned long        pos;
326
327    FT_StreamDesc        descriptor;
328    FT_StreamDesc        pathname;
329    FT_Stream_IoFunc     read;
330    FT_Stream_CloseFunc  close;
331
332    FT_Memory            memory;
333    unsigned char*       cursor;
334    unsigned char*       limit;
335
336  } FT_StreamRec;
337
338
339  /* */
340
341
342FT_END_HEADER
343
344#endif /* __FTSYSTEM_H__ */
345
346
347/* END */
348