1 /**************************************************************************** 2 * 3 * ftsystem.h 4 * 5 * FreeType low-level system interface definition (specification). 6 * 7 * Copyright 1996-2018 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. In particular, the `FT_GET_XXX' macros use this instead 324 * of the `pos' field. 325 * 326 * limit :: 327 * This field is set and used internally by FreeType when parsing 328 * frames. 329 * 330 */ 331 typedef struct FT_StreamRec_ 332 { 333 unsigned char* base; 334 unsigned long size; 335 unsigned long pos; 336 337 FT_StreamDesc descriptor; 338 FT_StreamDesc pathname; 339 FT_Stream_IoFunc read; 340 FT_Stream_CloseFunc close; 341 342 FT_Memory memory; 343 unsigned char* cursor; 344 unsigned char* limit; 345 346 } FT_StreamRec; 347 348 /* */ 349 350 351 FT_END_HEADER 352 353 #endif /* FTSYSTEM_H_ */ 354 355 356 /* END */ 357