include/freetype/fttypes.h

   1 /****************************************************************************
   2  *
   3  * fttypes.h
   4  *
   5  *   FreeType simple types definitions (specification only).
   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 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 */