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