include/freetype/fttypes.h

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