ftsystem.h (8502B)
1 /**************************************************************************** 2 * 3 * ftsystem.h 4 * 5 * FreeType low-level system interface definition (specification). 6 * 7 * Copyright (C) 1996-2025 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 from the start of the stream to seek to. 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 * If count >~0, return the number of bytes effectively read by the 242 * stream (after seeking to `offset`). If count ==~0, return the status 243 * of the seek operation (non-zero indicates an error). 244 * 245 */ 246 typedef unsigned long 247 (*FT_Stream_IoFunc)( FT_Stream stream, 248 unsigned long offset, 249 unsigned char* buffer, 250 unsigned long count ); 251 252 253 /************************************************************************** 254 * 255 * @functype: 256 * FT_Stream_CloseFunc 257 * 258 * @description: 259 * A function used to close a given input stream. 260 * 261 * @input: 262 * stream :: 263 * A handle to the target stream. 264 * 265 */ 266 typedef void 267 (*FT_Stream_CloseFunc)( FT_Stream stream ); 268 269 270 /************************************************************************** 271 * 272 * @struct: 273 * FT_StreamRec 274 * 275 * @description: 276 * A structure used to describe an input stream. 277 * 278 * @input: 279 * base :: 280 * For memory-based streams, this is the address of the first stream 281 * byte in memory. This field should always be set to `NULL` for 282 * disk-based streams. 283 * 284 * size :: 285 * The stream size in bytes. 286 * 287 * In case of compressed streams where the size is unknown before 288 * actually doing the decompression, the value is set to 0x7FFFFFFF. 289 * (Note that this size value can occur for normal streams also; it is 290 * thus just a hint.) 291 * 292 * pos :: 293 * The current position within the stream. 294 * 295 * descriptor :: 296 * This field is a union that can hold an integer or a pointer. It is 297 * used by stream implementations to store file descriptors or `FILE*` 298 * pointers. 299 * 300 * pathname :: 301 * This field is completely ignored by FreeType. However, it is often 302 * useful during debugging to use it to store the stream's filename 303 * (where available). 304 * 305 * read :: 306 * The stream's input function. 307 * 308 * close :: 309 * The stream's close function. 310 * 311 * memory :: 312 * The memory manager to use to preload frames. This is set internally 313 * by FreeType and shouldn't be touched by stream implementations. 314 * 315 * cursor :: 316 * This field is set and used internally by FreeType when parsing 317 * frames. In particular, the `FT_GET_XXX` macros use this instead of 318 * the `pos` field. 319 * 320 * limit :: 321 * This field is set and used internally by FreeType when parsing 322 * frames. 323 * 324 */ 325 typedef struct FT_StreamRec_ 326 { 327 unsigned char* base; 328 unsigned long size; 329 unsigned long pos; 330 331 FT_StreamDesc descriptor; 332 FT_StreamDesc pathname; 333 FT_Stream_IoFunc read; 334 FT_Stream_CloseFunc close; 335 336 FT_Memory memory; 337 unsigned char* cursor; 338 unsigned char* limit; 339 340 } FT_StreamRec; 341 342 /* */ 343 344 345 FT_END_HEADER 346 347 #endif /* FTSYSTEM_H_ */ 348 349 350 /* END */