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 342 FT_END_HEADER 343 344 #endif /* __FTSYSTEM_H__ */ 345 346 347 /* END */ 348