fttypes.h (14735B)
1 /**************************************************************************** 2 * 3 * fttypes.h 4 * 5 * FreeType simple types definitions (specification only). 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 FTTYPES_H_ 20 #define FTTYPES_H_ 21 22 23 #include <ft2build.h> 24 #include FT_CONFIG_CONFIG_H 25 #include <freetype/ftsystem.h> 26 #include <freetype/ftimage.h> 27 28 #include <stddef.h> 29 30 31 FT_BEGIN_HEADER 32 33 34 /************************************************************************** 35 * 36 * @section: 37 * basic_types 38 * 39 * @title: 40 * Basic Data Types 41 * 42 * @abstract: 43 * The basic data types defined by the library. 44 * 45 * @description: 46 * This section contains the basic data types defined by FreeType~2, 47 * ranging from simple scalar types to bitmap descriptors. More 48 * font-specific structures are defined in a different section. Note 49 * that FreeType does not use floating-point data types. Fractional 50 * values are represented by fixed-point integers, with lower bits 51 * storing the fractional part. 52 * 53 * @order: 54 * FT_Byte 55 * FT_Bytes 56 * FT_Char 57 * FT_Int 58 * FT_UInt 59 * FT_Int16 60 * FT_UInt16 61 * FT_Int32 62 * FT_UInt32 63 * FT_Int64 64 * FT_UInt64 65 * FT_Short 66 * FT_UShort 67 * FT_Long 68 * FT_ULong 69 * FT_Bool 70 * FT_Offset 71 * FT_PtrDist 72 * FT_String 73 * FT_Tag 74 * FT_Error 75 * FT_Fixed 76 * FT_Pointer 77 * FT_Pos 78 * FT_Vector 79 * FT_BBox 80 * FT_Matrix 81 * FT_FWord 82 * FT_UFWord 83 * FT_F2Dot14 84 * FT_UnitVector 85 * FT_F26Dot6 86 * FT_Data 87 * 88 * FT_MAKE_TAG 89 * 90 * FT_Generic 91 * FT_Generic_Finalizer 92 * 93 * FT_Bitmap 94 * FT_Pixel_Mode 95 * FT_Palette_Mode 96 * FT_Glyph_Format 97 * FT_IMAGE_TAG 98 * 99 */ 100 101 102 /************************************************************************** 103 * 104 * @type: 105 * FT_Bool 106 * 107 * @description: 108 * A typedef of unsigned char, used for simple booleans. As usual, 109 * values 1 and~0 represent true and false, respectively. 110 */ 111 typedef unsigned char FT_Bool; 112 113 114 /************************************************************************** 115 * 116 * @type: 117 * FT_FWord 118 * 119 * @description: 120 * A signed 16-bit integer used to store a distance in original font 121 * units. 122 */ 123 typedef signed short FT_FWord; /* distance in FUnits */ 124 125 126 /************************************************************************** 127 * 128 * @type: 129 * FT_UFWord 130 * 131 * @description: 132 * An unsigned 16-bit integer used to store a distance in original font 133 * units. 134 */ 135 typedef unsigned short FT_UFWord; /* unsigned distance */ 136 137 138 /************************************************************************** 139 * 140 * @type: 141 * FT_Char 142 * 143 * @description: 144 * A simple typedef for the _signed_ char type. 145 */ 146 typedef signed char FT_Char; 147 148 149 /************************************************************************** 150 * 151 * @type: 152 * FT_Byte 153 * 154 * @description: 155 * A simple typedef for the _unsigned_ char type. 156 */ 157 typedef unsigned char FT_Byte; 158 159 160 /************************************************************************** 161 * 162 * @type: 163 * FT_Bytes 164 * 165 * @description: 166 * A typedef for constant memory areas. 167 */ 168 typedef const FT_Byte* FT_Bytes; 169 170 171 /************************************************************************** 172 * 173 * @type: 174 * FT_Tag 175 * 176 * @description: 177 * A typedef for 32-bit tags (as used in the SFNT format). 178 */ 179 typedef FT_UInt32 FT_Tag; 180 181 182 /************************************************************************** 183 * 184 * @type: 185 * FT_String 186 * 187 * @description: 188 * A simple typedef for the char type, usually used for strings. 189 */ 190 typedef char FT_String; 191 192 193 /************************************************************************** 194 * 195 * @type: 196 * FT_Short 197 * 198 * @description: 199 * A typedef for signed short. 200 */ 201 typedef signed short FT_Short; 202 203 204 /************************************************************************** 205 * 206 * @type: 207 * FT_UShort 208 * 209 * @description: 210 * A typedef for unsigned short. 211 */ 212 typedef unsigned short FT_UShort; 213 214 215 /************************************************************************** 216 * 217 * @type: 218 * FT_Int 219 * 220 * @description: 221 * A typedef for the int type. 222 */ 223 typedef signed int FT_Int; 224 225 226 /************************************************************************** 227 * 228 * @type: 229 * FT_UInt 230 * 231 * @description: 232 * A typedef for the unsigned int type. 233 */ 234 typedef unsigned int FT_UInt; 235 236 237 /************************************************************************** 238 * 239 * @type: 240 * FT_Long 241 * 242 * @description: 243 * A typedef for signed long. 244 */ 245 typedef signed long FT_Long; 246 247 248 /************************************************************************** 249 * 250 * @type: 251 * FT_ULong 252 * 253 * @description: 254 * A typedef for unsigned long. 255 */ 256 typedef unsigned long FT_ULong; 257 258 259 /************************************************************************** 260 * 261 * @type: 262 * FT_F2Dot14 263 * 264 * @description: 265 * A signed 2.14 fixed-point type used for unit vectors. 266 */ 267 typedef signed short FT_F2Dot14; 268 269 270 /************************************************************************** 271 * 272 * @type: 273 * FT_F26Dot6 274 * 275 * @description: 276 * A signed 26.6 fixed-point type used for vectorial pixel coordinates. 277 */ 278 typedef signed long FT_F26Dot6; 279 280 281 /************************************************************************** 282 * 283 * @type: 284 * FT_Fixed 285 * 286 * @description: 287 * This type is used to store 16.16 fixed-point values, like scaling 288 * values or matrix coefficients. 289 */ 290 typedef signed long FT_Fixed; 291 292 293 /************************************************************************** 294 * 295 * @type: 296 * FT_Error 297 * 298 * @description: 299 * The FreeType error code type. A value of~0 is always interpreted as a 300 * successful operation. 301 */ 302 typedef int FT_Error; 303 304 305 /************************************************************************** 306 * 307 * @type: 308 * FT_Pointer 309 * 310 * @description: 311 * A simple typedef for a typeless pointer. 312 */ 313 typedef void* FT_Pointer; 314 315 316 /************************************************************************** 317 * 318 * @type: 319 * FT_Offset 320 * 321 * @description: 322 * This is equivalent to the ANSI~C `size_t` type, i.e., the largest 323 * _unsigned_ integer type used to express a file size or position, or a 324 * memory block size. 325 */ 326 typedef size_t FT_Offset; 327 328 329 /************************************************************************** 330 * 331 * @type: 332 * FT_PtrDist 333 * 334 * @description: 335 * This is equivalent to the ANSI~C `ptrdiff_t` type, i.e., the largest 336 * _signed_ integer type used to express the distance between two 337 * pointers. 338 */ 339 typedef ft_ptrdiff_t FT_PtrDist; 340 341 342 /************************************************************************** 343 * 344 * @struct: 345 * FT_UnitVector 346 * 347 * @description: 348 * A simple structure used to store a 2D vector unit vector. Uses 349 * FT_F2Dot14 types. 350 * 351 * @fields: 352 * x :: 353 * Horizontal coordinate. 354 * 355 * y :: 356 * Vertical coordinate. 357 */ 358 typedef struct FT_UnitVector_ 359 { 360 FT_F2Dot14 x; 361 FT_F2Dot14 y; 362 363 } FT_UnitVector; 364 365 366 /************************************************************************** 367 * 368 * @struct: 369 * FT_Matrix 370 * 371 * @description: 372 * A simple structure used to store a 2x2 matrix. Coefficients are in 373 * 16.16 fixed-point format. The computation performed is: 374 * 375 * ``` 376 * x' = x*xx + y*xy 377 * y' = x*yx + y*yy 378 * ``` 379 * 380 * @fields: 381 * xx :: 382 * Matrix coefficient. 383 * 384 * xy :: 385 * Matrix coefficient. 386 * 387 * yx :: 388 * Matrix coefficient. 389 * 390 * yy :: 391 * Matrix coefficient. 392 */ 393 typedef struct FT_Matrix_ 394 { 395 FT_Fixed xx, xy; 396 FT_Fixed yx, yy; 397 398 } FT_Matrix; 399 400 401 /************************************************************************** 402 * 403 * @struct: 404 * FT_Data 405 * 406 * @description: 407 * Read-only binary data represented as a pointer and a length. 408 * 409 * @fields: 410 * pointer :: 411 * The data. 412 * 413 * length :: 414 * The length of the data in bytes. 415 */ 416 typedef struct FT_Data_ 417 { 418 const FT_Byte* pointer; 419 FT_UInt length; 420 421 } FT_Data; 422 423 424 /************************************************************************** 425 * 426 * @functype: 427 * FT_Generic_Finalizer 428 * 429 * @description: 430 * Describe a function used to destroy the 'client' data of any FreeType 431 * object. See the description of the @FT_Generic type for details of 432 * usage. 433 * 434 * @input: 435 * The address of the FreeType object that is under finalization. Its 436 * client data is accessed through its `generic` field. 437 */ 438 typedef void (*FT_Generic_Finalizer)( void* object ); 439 440 441 /************************************************************************** 442 * 443 * @struct: 444 * FT_Generic 445 * 446 * @description: 447 * Client applications often need to associate their own data to a 448 * variety of FreeType core objects. For example, a text layout API 449 * might want to associate a glyph cache to a given size object. 450 * 451 * Some FreeType object contains a `generic` field, of type `FT_Generic`, 452 * which usage is left to client applications and font servers. 453 * 454 * It can be used to store a pointer to client-specific data, as well as 455 * the address of a 'finalizer' function, which will be called by 456 * FreeType when the object is destroyed (for example, the previous 457 * client example would put the address of the glyph cache destructor in 458 * the `finalizer` field). 459 * 460 * @fields: 461 * data :: 462 * A typeless pointer to any client-specified data. This field is 463 * completely ignored by the FreeType library. 464 * 465 * finalizer :: 466 * A pointer to a 'generic finalizer' function, which will be called 467 * when the object is destroyed. If this field is set to `NULL`, no 468 * code will be called. 469 */ 470 typedef struct FT_Generic_ 471 { 472 void* data; 473 FT_Generic_Finalizer finalizer; 474 475 } FT_Generic; 476 477 478 /************************************************************************** 479 * 480 * @macro: 481 * FT_MAKE_TAG 482 * 483 * @description: 484 * This macro converts four-letter tags that are used to label TrueType 485 * tables into an `FT_Tag` type, to be used within FreeType. 486 * 487 * @note: 488 * The produced values **must** be 32-bit integers. Don't redefine this 489 * macro. 490 */ 491 #define FT_MAKE_TAG( _x1, _x2, _x3, _x4 ) \ 492 ( ( FT_STATIC_BYTE_CAST( FT_Tag, _x1 ) << 24 ) | \ 493 ( FT_STATIC_BYTE_CAST( FT_Tag, _x2 ) << 16 ) | \ 494 ( FT_STATIC_BYTE_CAST( FT_Tag, _x3 ) << 8 ) | \ 495 FT_STATIC_BYTE_CAST( FT_Tag, _x4 ) ) 496 497 498 /*************************************************************************/ 499 /*************************************************************************/ 500 /* */ 501 /* L I S T M A N A G E M E N T */ 502 /* */ 503 /*************************************************************************/ 504 /*************************************************************************/ 505 506 507 /************************************************************************** 508 * 509 * @section: 510 * list_processing 511 * 512 */ 513 514 515 /************************************************************************** 516 * 517 * @type: 518 * FT_ListNode 519 * 520 * @description: 521 * Many elements and objects in FreeType are listed through an @FT_List 522 * record (see @FT_ListRec). As its name suggests, an FT_ListNode is a 523 * handle to a single list element. 524 */ 525 typedef struct FT_ListNodeRec_* FT_ListNode; 526 527 528 /************************************************************************** 529 * 530 * @type: 531 * FT_List 532 * 533 * @description: 534 * A handle to a list record (see @FT_ListRec). 535 */ 536 typedef struct FT_ListRec_* FT_List; 537 538 539 /************************************************************************** 540 * 541 * @struct: 542 * FT_ListNodeRec 543 * 544 * @description: 545 * A structure used to hold a single list element. 546 * 547 * @fields: 548 * prev :: 549 * The previous element in the list. `NULL` if first. 550 * 551 * next :: 552 * The next element in the list. `NULL` if last. 553 * 554 * data :: 555 * A typeless pointer to the listed object. 556 */ 557 typedef struct FT_ListNodeRec_ 558 { 559 FT_ListNode prev; 560 FT_ListNode next; 561 void* data; 562 563 } FT_ListNodeRec; 564 565 566 /************************************************************************** 567 * 568 * @struct: 569 * FT_ListRec 570 * 571 * @description: 572 * A structure used to hold a simple doubly-linked list. These are used 573 * in many parts of FreeType. 574 * 575 * @fields: 576 * head :: 577 * The head (first element) of doubly-linked list. 578 * 579 * tail :: 580 * The tail (last element) of doubly-linked list. 581 */ 582 typedef struct FT_ListRec_ 583 { 584 FT_ListNode head; 585 FT_ListNode tail; 586 587 } FT_ListRec; 588 589 /* */ 590 591 592 #define FT_IS_EMPTY( list ) ( (list).head == 0 ) 593 #define FT_BOOL( x ) FT_STATIC_CAST( FT_Bool, (x) != 0 ) 594 595 /* concatenate C tokens */ 596 #define FT_ERR_XCAT( x, y ) x ## y 597 #define FT_ERR_CAT( x, y ) FT_ERR_XCAT( x, y ) 598 599 /* see `ftmoderr.h` for descriptions of the following macros */ 600 601 #define FT_ERR( e ) FT_ERR_CAT( FT_ERR_PREFIX, e ) 602 603 #define FT_ERROR_BASE( x ) ( (x) & 0xFF ) 604 #define FT_ERROR_MODULE( x ) ( (x) & 0xFF00U ) 605 606 #define FT_ERR_EQ( x, e ) \ 607 ( FT_ERROR_BASE( x ) == FT_ERROR_BASE( FT_ERR( e ) ) ) 608 #define FT_ERR_NEQ( x, e ) \ 609 ( FT_ERROR_BASE( x ) != FT_ERROR_BASE( FT_ERR( e ) ) ) 610 611 612 FT_END_HEADER 613 614 #endif /* FTTYPES_H_ */ 615 616 617 /* END */