XFA: merge patch from CL 817753002
[pdfium.git] / core / include / thirdparties / freetype / freetype / ftsystem.h
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
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         */
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
349 FT_END_HEADER
350
351 #endif /* __FTSYSTEM_H__ */
352
353
354 /* END */