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  /* Sunliang.Liu 20100915 sync 221's revison. */
93  typedef void*
94	  (*FT_AllocDebug_Func)( FT_Memory  memory,
95	  long       size, const char* filename,  int line);
96
97
98
99  /*************************************************************************
100   *
101   * @functype:
102   *   FT_Free_Func
103   *
104   * @description:
105   *   A function used to release a given block of memory.
106   *
107   * @input:
108   *   memory ::
109   *     A handle to the source memory manager.
110   *
111   *   block ::
112   *     The address of the target memory block.
113   *
114   */
115  typedef void
116  (*FT_Free_Func)( FT_Memory  memory,
117                   void*      block );
118
119
120  /*************************************************************************
121   *
122   * @functype:
123   *   FT_Realloc_Func
124   *
125   * @description:
126   *   A function used to re-allocate a given block of memory.
127   *
128   * @input:
129   *   memory ::
130   *     A handle to the source memory manager.
131   *
132   *   cur_size ::
133   *     The block's current size in bytes.
134   *
135   *   new_size ::
136   *     The block's requested new size.
137   *
138   *   block ::
139   *     The block's current address.
140   *
141   * @return:
142   *   New block address.  0~in case of memory shortage.
143   *
144   * @note:
145   *   In case of error, the old block must still be available.
146   *
147   */
148  typedef void*
149  (*FT_Realloc_Func)( FT_Memory  memory,
150                      long       cur_size,
151                      long       new_size,
152                      void*      block );
153
154
155  /*************************************************************************
156   *
157   * @struct:
158   *   FT_MemoryRec
159   *
160   * @description:
161   *   A structure used to describe a given memory manager to FreeType~2.
162   *
163   * @fields:
164   *   user ::
165   *     A generic typeless pointer for user data.
166   *
167   *   alloc ::
168   *     A pointer type to an allocation function.
169   *
170   *   free ::
171   *     A pointer type to an memory freeing function.
172   *
173   *   realloc ::
174   *     A pointer type to a reallocation function.
175   *
176   */
177  struct  FT_MemoryRec_
178  {
179    void*            user;
180    FT_Alloc_Func    alloc;
181	FT_AllocDebug_Func allocdebug;	/* Sunliang.Liu 20100915 sync 221's revison. */
182    FT_Free_Func     free;
183    FT_Realloc_Func  realloc;
184  };
185
186
187  /*************************************************************************/
188  /*                                                                       */
189  /*                       I / O   M A N A G E M E N T                     */
190  /*                                                                       */
191  /*************************************************************************/
192
193
194  /*************************************************************************
195   *
196   * @type:
197   *   FT_Stream
198   *
199   * @description:
200   *   A handle to an input stream.
201   *
202   */
203  typedef struct FT_StreamRec_*  FT_Stream;
204
205
206  /*************************************************************************
207   *
208   * @struct:
209   *   FT_StreamDesc
210   *
211   * @description:
212   *   A union type used to store either a long or a pointer.  This is used
213   *   to store a file descriptor or a `FILE*' in an input stream.
214   *
215   */
216  typedef union  FT_StreamDesc_
217  {
218    long   value;
219    void*  pointer;
220
221  } FT_StreamDesc;
222
223
224  /*************************************************************************
225   *
226   * @functype:
227   *   FT_Stream_IoFunc
228   *
229   * @description:
230   *   A function used to seek and read data from a given input stream.
231   *
232   * @input:
233   *   stream ::
234   *     A handle to the source stream.
235   *
236   *   offset ::
237   *     The offset of read in stream (always from start).
238   *
239   *   buffer ::
240   *     The address of the read buffer.
241   *
242   *   count ::
243   *     The number of bytes to read from the stream.
244   *
245   * @return:
246   *   The number of bytes effectively read by the stream.
247   *
248   * @note:
249   *   This function might be called to perform a seek or skip operation
250   *   with a `count' of~0.  A non-zero return value then indicates an
251   *   error.
252   *
253   */
254  typedef unsigned long
255  (*FT_Stream_IoFunc)( FT_Stream       stream,
256                       unsigned long   offset,
257                       unsigned char*  buffer,
258                       unsigned long   count );
259
260
261  /*************************************************************************
262   *
263   * @functype:
264   *   FT_Stream_CloseFunc
265   *
266   * @description:
267   *   A function used to close a given input stream.
268   *
269   * @input:
270   *  stream ::
271   *     A handle to the target stream.
272   *
273   */
274  typedef void
275  (*FT_Stream_CloseFunc)( FT_Stream  stream );
276
277
278  /*************************************************************************
279   *
280   * @struct:
281   *   FT_StreamRec
282   *
283   * @description:
284   *   A structure used to describe an input stream.
285   *
286   * @input:
287   *   base ::
288   *     For memory-based streams, this is the address of the first stream
289   *     byte in memory.  This field should always be set to NULL for
290   *     disk-based streams.
291   *
292   *   size ::
293   *     The stream size in bytes.
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
316   *     internally by FreeType and shouldn't be touched by stream
317   *     implementations.
318   *
319   *   cursor ::
320   *     This field is set and used internally by FreeType when parsing
321   *     frames.
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
349FT_END_HEADER
350
351#endif /* __FTSYSTEM_H__ */
352
353
354/* END */
355