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