XFA: merge patch from CL 815103002
[pdfium.git] / third_party / freetype / include / 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
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 FT_END_HEADER
342
343 #endif /* __FTSYSTEM_H__ */
344
345
346 /* END */