1 /**************************************************************************** 2 * 3 * ftsystem.h 4 * 5 * FreeType low-level system interface definition (specification). 6 * 7 * Copyright (C) 1996-2020 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 24 25 FT_BEGIN_HEADER 26 27 28 /************************************************************************** 29 * 30 * @section: 31 * system_interface 32 * 33 * @title: 34 * System Interface 35 * 36 * @abstract: 37 * How FreeType manages memory and i/o. 38 * 39 * @description: 40 * This section contains various definitions related to memory management 41 * and i/o access. You need to understand this information if you want to 42 * use a custom memory manager or you own i/o streams. 43 * 44 */ 45 46 47 /************************************************************************** 48 * 49 * M E M O R Y M A N A G E M E N T 50 * 51 */ 52 53 54 /************************************************************************** 55 * 56 * @type: 57 * FT_Memory 58 * 59 * @description: 60 * A handle to a given memory manager object, defined with an 61 * @FT_MemoryRec structure. 62 * 63 */ 64 typedef struct FT_MemoryRec_* FT_Memory; 65 66 67 /************************************************************************** 68 * 69 * @functype: 70 * FT_Alloc_Func 71 * 72 * @description: 73 * A function used to allocate `size` bytes from `memory`. 74 * 75 * @input: 76 * memory :: 77 * A handle to the source memory manager. 78 * 79 * size :: 80 * The size in bytes to allocate. 81 * 82 * @return: 83 * Address of new memory block. 0~in case of failure. 84 * 85 */ 86 typedef void* 87 (*FT_Alloc_Func)( FT_Memory memory, 88 long size ); 89 90 91 /************************************************************************** 92 * 93 * @functype: 94 * FT_Free_Func 95 * 96 * @description: 97 * A function used to release a given block of memory. 98 * 99 * @input: 100 * memory :: 101 * A handle to the source memory manager. 102 * 103 * block :: 104 * The address of the target memory block. 105 * 106 */ 107 typedef void 108 (*FT_Free_Func)( FT_Memory memory, 109 void* block ); 110 111 112 /************************************************************************** 113 * 114 * @functype: 115 * FT_Realloc_Func 116 * 117 * @description: 118 * A function used to re-allocate a given block of memory. 119 * 120 * @input: 121 * memory :: 122 * A handle to the source memory manager. 123 * 124 * cur_size :: 125 * The block's current size in bytes. 126 * 127 * new_size :: 128 * The block's requested new size. 129 * 130 * block :: 131 * The block's current address. 132 * 133 * @return: 134 * New block address. 0~in case of memory shortage. 135 * 136 * @note: 137 * In case of error, the old block must still be available. 138 * 139 */ 140 typedef void* 141 (*FT_Realloc_Func)( FT_Memory memory, 142 long cur_size, 143 long new_size, 144 void* block ); 145 146 147 /************************************************************************** 148 * 149 * @struct: 150 * FT_MemoryRec 151 * 152 * @description: 153 * A structure used to describe a given memory manager to FreeType~2. 154 * 155 * @fields: 156 * user :: 157 * A generic typeless pointer for user data. 158 * 159 * alloc :: 160 * A pointer type to an allocation function. 161 * 162 * free :: 163 * A pointer type to an memory freeing function. 164 * 165 * realloc :: 166 * A pointer type to a reallocation function. 167 * 168 */ 169 struct FT_MemoryRec_ 170 { 171 void* user; 172 FT_Alloc_Func alloc; 173 FT_Free_Func free; 174 FT_Realloc_Func realloc; 175 }; 176 177 178 /************************************************************************** 179 * 180 * I / O M A N A G E M E N T 181 * 182 */ 183 184 185 /************************************************************************** 186 * 187 * @type: 188 * FT_Stream 189 * 190 * @description: 191 * A handle to an input stream. 192 * 193 * @also: 194 * See @FT_StreamRec for the publicly accessible fields of a given stream 195 * object. 196 * 197 */ 198 typedef struct FT_StreamRec_* FT_Stream; 199 200 201 /************************************************************************** 202 * 203 * @struct: 204 * FT_StreamDesc 205 * 206 * @description: 207 * A union type used to store either a long or a pointer. This is used 208 * to store a file descriptor or a `FILE*` in an input stream. 209 * 210 */ 211 typedef union FT_StreamDesc_ 212 { 213 long value; 214 void* pointer; 215 216 } FT_StreamDesc; 217 218 219 /************************************************************************** 220 * 221 * @functype: 222 * FT_Stream_IoFunc 223 * 224 * @description: 225 * A function used to seek and read data from a given input stream. 226 * 227 * @input: 228 * stream :: 229 * A handle to the source stream. 230 * 231 * offset :: 232 * The offset of read in stream (always from start). 233 * 234 * buffer :: 235 * The address of the read buffer. 236 * 237 * count :: 238 * The number of bytes to read from the stream. 239 * 240 * @return: 241 * The number of bytes effectively read by the stream. 242 * 243 * @note: 244 * This function might be called to perform a seek or skip operation with 245 * a `count` of~0. A non-zero return value then indicates an error. 246 * 247 */ 248 typedef unsigned long 249 (*FT_Stream_IoFunc)( FT_Stream stream, 250 unsigned long offset, 251 unsigned char* buffer, 252 unsigned long count ); 253 254 255 /************************************************************************** 256 * 257 * @functype: 258 * FT_Stream_CloseFunc 259 * 260 * @description: 261 * A function used to close a given input stream. 262 * 263 * @input: 264 * stream :: 265 * A handle to the target stream. 266 * 267 */ 268 typedef void 269 (*FT_Stream_CloseFunc)( FT_Stream stream ); 270 271 272 /************************************************************************** 273 * 274 * @struct: 275 * FT_StreamRec 276 * 277 * @description: 278 * A structure used to describe an input stream. 279 * 280 * @input: 281 * base :: 282 * For memory-based streams, this is the address of the first stream 283 * byte in memory. This field should always be set to `NULL` for 284 * disk-based streams. 285 * 286 * size :: 287 * The stream size in bytes. 288 * 289 * In case of compressed streams where the size is unknown before 290 * actually doing the decompression, the value is set to 0x7FFFFFFF. 291 * (Note that this size value can occur for normal streams also; it is 292 * thus just a hint.) 293 * 294 * pos :: 295 * The current position within the stream. 296 * 297 * descriptor :: 298 * This field is a union that can hold an integer or a pointer. It is 299 * used by stream implementations to store file descriptors or `FILE*` 300 * pointers. 301 * 302 * pathname :: 303 * This field is completely ignored by FreeType. However, it is often 304 * useful during debugging to use it to store the stream's filename 305 * (where available). 306 * 307 * read :: 308 * The stream's input function. 309 * 310 * close :: 311 * The stream's close function. 312 * 313 * memory :: 314 * The memory manager to use to preload frames. This is set internally 315 * by FreeType and shouldn't be touched by stream implementations. 316 * 317 * cursor :: 318 * This field is set and used internally by FreeType when parsing 319 * frames. In particular, the `FT_GET_XXX` macros use this instead of 320 * the `pos` field. 321 * 322 * limit :: 323 * This field is set and used internally by FreeType when parsing 324 * frames. 325 * 326 */ 327 typedef struct FT_StreamRec_ 328 { 329 unsigned char* base; 330 unsigned long size; 331 unsigned long pos; 332 333 FT_StreamDesc descriptor; 334 FT_StreamDesc pathname; 335 FT_Stream_IoFunc read; 336 FT_Stream_CloseFunc close; 337 338 FT_Memory memory; 339 unsigned char* cursor; 340 unsigned char* limit; 341 342 } FT_StreamRec; 343 344 /* */ 345 346 347 FT_END_HEADER 348 349 #endif /* FTSYSTEM_H_ */ 350 351 352 /* END */ 353