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