libraries/freetype-2.0.5/include/freetype/internal/sfnt.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  sfnt.h                                                                 */
   4 /*                                                                         */
   5 /*    High-level `sfnt' driver interface (specification).                  */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001 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 __SFNT_H__
  20 #define __SFNT_H__
  21
  22
  23 #include <ft2build.h>
  24 #include FT_INTERNAL_DRIVER_H
  25 #include FT_INTERNAL_TRUETYPE_TYPES_H
  26
  27
  28 FT_BEGIN_HEADER
  29
  30
  31   /*************************************************************************/
  32   /*                                                                       */
  33   /* <FuncType>                                                            */
  34   /*    TT_Init_Face_Func                                                  */
  35   /*                                                                       */
  36   /* <Description>                                                         */
  37   /*    First part of the SFNT face object initialization.  This will find */
  38   /*    the face in a SFNT file or collection, and load its format tag in  */
  39   /*    face->format_tag.                                                  */
  40   /*                                                                       */
  41   /* <Input>                                                               */
  42   /*    stream     :: The input stream.                                    */
  43   /*                                                                       */
  44   /*    face       :: A handle to the target face object.                  */
  45   /*                                                                       */
  46   /*    face_index :: The index of the TrueType font, if we are opening a  */
  47   /*                  collection.                                          */
  48   /*                                                                       */
  49   /*    num_params :: The number of additional parameters.                 */
  50   /*                                                                       */
  51   /*    params     :: Optional additional parameters.                      */
  52   /*                                                                       */
  53   /* <Return>                                                              */
  54   /*    FreeType error code.  0 means success.                             */
  55   /*                                                                       */
  56   /* <Note>                                                                */
  57   /*    The stream cursor must be at the font file's origin.               */
  58   /*                                                                       */
  59   /*    This function recognizes fonts embedded in a `TrueType             */
  60   /*    collection'.                                                       */
  61   /*                                                                       */
  62   /*    Once the format tag has been validated by the font driver, it      */
  63   /*    should then call the TT_Load_Face_Func() callback to read the rest */
  64   /*    of the SFNT tables in the object.                                  */
  65   /*                                                                       */
  66   typedef FT_Error
  67   (*TT_Init_Face_Func)( FT_Stream      stream,
  68                         TT_Face        face,
  69                         FT_Int         face_index,
  70                         FT_Int         num_params,
  71                         FT_Parameter*  params );
  72
  73
  74   /*************************************************************************/
  75   /*                                                                       */
  76   /* <FuncType>                                                            */
  77   /*    TT_Load_Face_Func                                                  */
  78   /*                                                                       */
  79   /* <Description>                                                         */
  80   /*    Second part of the SFNT face object initialization.  This will     */
  81   /*    load the common SFNT tables (head, OS/2, maxp, metrics, etc.) in   */
  82   /*    the face object.                                                   */
  83   /*                                                                       */
  84   /* <Input>                                                               */
  85   /*    stream     :: The input stream.                                    */
  86   /*                                                                       */
  87   /*    face       :: A handle to the target face object.                  */
  88   /*                                                                       */
  89   /*    face_index :: The index of the TrueType font, if we are opening a  */
  90   /*                  collection.                                          */
  91   /*                                                                       */
  92   /*    num_params :: The number of additional parameters.                 */
  93   /*                                                                       */
  94   /*    params     :: Optional additional parameters.                      */
  95   /*                                                                       */
  96   /* <Return>                                                              */
  97   /*    FreeType error code.  0 means success.                             */
  98   /*                                                                       */
  99   /* <Note>                                                                */
 100   /*    This function must be called after TT_Init_Face_Func().            */
 101   /*                                                                       */
 102   typedef FT_Error
 103   (*TT_Load_Face_Func)( FT_Stream      stream,
 104                         TT_Face        face,
 105                         FT_Int         face_index,
 106                         FT_Int         num_params,
 107                         FT_Parameter*  params );
 108
 109
 110   /*************************************************************************/
 111   /*                                                                       */
 112   /* <FuncType>                                                            */
 113   /*    TT_Done_Face_Func                                                  */
 114   /*                                                                       */
 115   /* <Description>                                                         */
 116   /*    A callback used to delete the common SFNT data from a face.        */
 117   /*                                                                       */
 118   /* <Input>                                                               */
 119   /*    face :: A handle to the target face object.                        */
 120   /*                                                                       */
 121   /* <Note>                                                                */
 122   /*    This function does NOT destroy the face object.                    */
 123   /*                                                                       */
 124   typedef void
 125   (*TT_Done_Face_Func)( TT_Face  face );
 126
 127
 128   typedef FT_Module_Interface
 129   (*SFNT_Get_Interface_Func)( FT_Module    module,
 130                               const char*  interface );
 131
 132
 133   /*************************************************************************/
 134   /*                                                                       */
 135   /* <FuncType>                                                            */
 136   /*    TT_Load_SFNT_Header_Func                                           */
 137   /*                                                                       */
 138   /* <Description>                                                         */
 139   /*    Loads the header of a SFNT font file.  Supports collections.       */
 140   /*                                                                       */
 141   /* <Input>                                                               */
 142   /*    face       :: A handle to the target face object.                  */
 143   /*                                                                       */
 144   /*    stream     :: The input stream.                                    */
 145   /*                                                                       */
 146   /*    face_index :: The index of the TrueType font, if we are opening a  */
 147   /*                  collection.                                          */
 148   /*                                                                       */
 149   /* <Output>                                                              */
 150   /*    sfnt       :: The SFNT header.                                     */
 151   /*                                                                       */
 152   /* <Return>                                                              */
 153   /*    FreeType error code.  0 means success.                             */
 154   /*                                                                       */
 155   /* <Note>                                                                */
 156   /*    The stream cursor must be at the font file's origin.               */
 157   /*                                                                       */
 158   /*    This function recognizes fonts embedded in a `TrueType             */
 159   /*    collection'.                                                       */
 160   /*                                                                       */
 161   /*    This function checks that the header is valid by looking at the    */
 162   /*    values of `search_range', `entry_selector', and `range_shift'.     */
 163   /*                                                                       */
 164   typedef FT_Error
 165   (*TT_Load_SFNT_Header_Func)( TT_Face       face,
 166                                FT_Stream     stream,
 167                                FT_Long       face_index,
 168                                SFNT_Header*  sfnt );
 169
 170
 171   /*************************************************************************/
 172   /*                                                                       */
 173   /* <FuncType>                                                            */
 174   /*    TT_Load_Directory_Func                                             */
 175   /*                                                                       */
 176   /* <Description>                                                         */
 177   /*    Loads the table directory into a face object.                      */
 178   /*                                                                       */
 179   /* <Input>                                                               */
 180   /*    face      :: A handle to the target face object.                   */
 181   /*                                                                       */
 182   /*    stream    :: The input stream.                                     */
 183   /*                                                                       */
 184   /*    sfnt      :: The SFNT header.                                      */
 185   /*                                                                       */
 186   /* <Return>                                                              */
 187   /*    FreeType error code.  0 means success.                             */
 188   /*                                                                       */
 189   /* <Note>                                                                */
 190   /*    The stream cursor must be on the first byte after the 4-byte font  */
 191   /*    format tag.  This is the case just after a call to                 */
 192   /*    TT_Load_Format_Tag().                                              */
 193   /*                                                                       */
 194   typedef FT_Error
 195   (*TT_Load_Directory_Func)( TT_Face       face,
 196                              FT_Stream     stream,
 197                              SFNT_Header*  sfnt );
 198
 199
 200   /*************************************************************************/
 201   /*                                                                       */
 202   /* <FuncType>                                                            */
 203   /*    TT_Load_Any_Func                                                   */
 204   /*                                                                       */
 205   /* <Description>                                                         */
 206   /*    Loads any font table into client memory.                           */
 207   /*                                                                       */
 208   /* <Input>                                                               */
 209   /*    face   :: The face object to look for.                             */
 210   /*                                                                       */
 211   /*    tag    :: The tag of table to load.  Use the value 0 if you want   */
 212   /*              to access the whole font file, else set this parameter   */
 213   /*              to a valid TrueType table tag that you can forge with    */
 214   /*              the MAKE_TT_TAG macro.                                   */
 215   /*                                                                       */
 216   /*    offset :: The starting offset in the table (or the file if         */
 217   /*              tag == 0).                                               */
 218   /*                                                                       */
 219   /*    length :: The address of the decision variable:                    */
 220   /*                                                                       */
 221   /*                If length == NULL:                                     */
 222   /*                  Loads the whole table.  Returns an error if          */
 223   /*                  `offset' == 0!                                       */
 224   /*                                                                       */
 225   /*                If *length == 0:                                       */
 226   /*                  Exits immediately; returning the length of the given */
 227   /*                  table or of the font file, depending on the value of */
 228   /*                  `tag'.                                               */
 229   /*                                                                       */
 230   /*                If *length != 0:                                       */
 231   /*                  Loads the next `length' bytes of table or font,      */
 232   /*                  starting at offset `offset' (in table or font too).  */
 233   /*                                                                       */
 234   /* <Output>                                                              */
 235   /*    buffer :: The address of target buffer.                            */
 236   /*                                                                       */
 237   /* <Return>                                                              */
 238   /*    TrueType error code.  0 means success.                             */
 239   /*                                                                       */
 240   typedef FT_Error
 241   (*TT_Load_Any_Func)( TT_Face    face,
 242                        FT_ULong   tag,
 243                        FT_Long    offset,
 244                        FT_Byte   *buffer,
 245                        FT_ULong*  length );
 246
 247
 248   /*************************************************************************/
 249   /*                                                                       */
 250   /* <FuncType>                                                            */
 251   /*    TT_Load_SBit_Image_Func                                            */
 252   /*                                                                       */
 253   /* <Description>                                                         */
 254   /*    Loads a given glyph sbit image from the font resource.  This also  */
 255   /*    returns its metrics.                                               */
 256   /*                                                                       */
 257   /* <Input>                                                               */
 258   /*    face        :: The target face object.                             */
 259   /*                                                                       */
 260   /*    x_ppem      :: The horizontal resolution in points per EM.         */
 261   /*                                                                       */
 262   /*    y_ppem      :: The vertical resolution in points per EM.           */
 263   /*                                                                       */
 264   /*    glyph_index :: The current glyph index.                            */
 265   /*                                                                       */
 266   /*    stream      :: The input stream.                                   */
 267   /*                                                                       */
 268   /* <Output>                                                              */
 269   /*    amap        :: The target pixmap.                                  */
 270   /*                                                                       */
 271   /*    ametrics    :: A big sbit metrics structure for the glyph image.   */
 272   /*                                                                       */
 273   /* <Return>                                                              */
 274   /*    FreeType error code.  0 means success.  Returns an error if no     */
 275   /*    glyph sbit exists for the index.                                   */
 276   /*                                                                       */
 277   /*  <Note>                                                               */
 278   /*    The `map.buffer' field is always freed before the glyph is loaded. */
 279   /*                                                                       */
 280   typedef FT_Error
 281   (*TT_Load_SBit_Image_Func)( TT_Face           face,
 282                               FT_ULong          strike_index,
 283                               FT_UInt           glyph_index,
 284                               FT_UInt           load_flags,
 285                               FT_Stream         stream,
 286                               FT_Bitmap        *amap,
 287                               TT_SBit_Metrics  *ametrics );
 288
 289
 290   /*************************************************************************/
 291   /*                                                                       */
 292   /* <FuncType>                                                            */
 293   /*    TT_Set_SBit_Strike_Func                                            */
 294   /*                                                                       */
 295   /* <Description>                                                         */
 296   /*    Selects an sbit strike for given horizontal and vertical ppem      */
 297   /*    values.                                                            */
 298   /*                                                                       */
 299   /* <Input>                                                               */
 300   /*    face          :: The target face object.                           */
 301   /*                                                                       */
 302   /*    x_ppem        :: The horizontal resolution in points per EM.       */
 303   /*                                                                       */
 304   /*    y_ppem        :: The vertical resolution in points per EM.         */
 305   /*                                                                       */
 306   /* <Output>                                                              */
 307   /*    astrike_index :: The index of the sbit strike.                     */
 308   /*                                                                       */
 309   /* <Return>                                                              */
 310   /*    FreeType error code.  0 means success.  Returns an error if no     */
 311   /*    sbit strike exists for the selected ppem values.                   */
 312   /*                                                                       */
 313   typedef FT_Error
 314   (*TT_Set_SBit_Strike_Func)( TT_Face    face,
 315                               FT_Int     x_ppem,
 316                               FT_Int     y_ppem,
 317                               FT_ULong  *astrike_index );
 318
 319
 320   /*************************************************************************/
 321   /*                                                                       */
 322   /* <FuncType>                                                            */
 323   /*    TT_Get_PS_Name_Func                                                */
 324   /*                                                                       */
 325   /* <Description>                                                         */
 326   /*    Gets the PostScript glyph name of a glyph.                         */
 327   /*                                                                       */
 328   /* <Input>                                                               */
 329   /*    index  :: The glyph index.                                         */
 330   /*                                                                       */
 331   /*    PSname :: The address of a string pointer.  Will be NULL in case   */
 332   /*              of error, otherwise it is a pointer to the glyph name.   */
 333   /*                                                                       */
 334   /*              You must not modify the returned string!                 */
 335   /*                                                                       */
 336   /* <Output>                                                              */
 337   /*    FreeType error code.  0 means success.                             */
 338   /*                                                                       */
 339   typedef FT_Error
 340   (*TT_Get_PS_Name_Func)( TT_Face      face,
 341                           FT_UInt      index,
 342                           FT_String**  PSname );
 343
 344
 345   /*************************************************************************/
 346   /*                                                                       */
 347   /* <FuncType>                                                            */
 348   /*    TT_Load_Metrics_Func                                               */
 349   /*                                                                       */
 350   /* <Description>                                                         */
 351   /*    Loads the horizontal or vertical header in a face object.          */
 352   /*                                                                       */
 353   /* <Input>                                                               */
 354   /*    face     :: A handle to the target face object.                    */
 355   /*                                                                       */
 356   /*    stream   :: The input stream.                                      */
 357   /*                                                                       */
 358   /*    vertical :: A boolean flag.  If set, load vertical metrics.        */
 359   /*                                                                       */
 360   /* <Return>                                                              */
 361   /*    FreeType error code.  0 means success.                             */
 362   /*                                                                       */
 363   typedef FT_Error
 364   (*TT_Load_Metrics_Func)( TT_Face    face,
 365                            FT_Stream  stream,
 366                            FT_Bool    vertical );
 367
 368
 369   /*************************************************************************/
 370   /*                                                                       */
 371   /* <FuncType>                                                            */
 372   /*    TT_CharMap_Load_Func                                               */
 373   /*                                                                       */
 374   /* <Description>                                                         */
 375   /*    Loads a given TrueType character map into memory.                  */
 376   /*                                                                       */
 377   /* <Input>                                                               */
 378   /*    face   :: A handle to the parent face object.                      */
 379   /*                                                                       */
 380   /*    stream :: A handle to the current stream object.                   */
 381   /*                                                                       */
 382   /* <InOut>                                                               */
 383   /*    cmap   :: A pointer to a cmap object.                              */
 384   /*                                                                       */
 385   /* <Return>                                                              */
 386   /*    FreeType error code.  0 means success.                             */
 387   /*                                                                       */
 388   /* <Note>                                                                */
 389   /*    The function assumes that the stream is already in use (i.e.,      */
 390   /*    opened).  In case of error, all partially allocated tables are     */
 391   /*    released.                                                          */
 392   /*                                                                       */
 393   typedef FT_Error
 394   (*TT_CharMap_Load_Func)( TT_Face        face,
 395                            TT_CMapTable*  cmap,
 396                            FT_Stream      input );
 397
 398
 399   /*************************************************************************/
 400   /*                                                                       */
 401   /* <FuncType>                                                            */
 402   /*    TT_CharMap_Free_Func                                               */
 403   /*                                                                       */
 404   /* <Description>                                                         */
 405   /*    Destroys a character mapping table.                                */
 406   /*                                                                       */
 407   /* <Input>                                                               */
 408   /*    face :: A handle to the parent face object.                        */
 409   /*                                                                       */
 410   /*    cmap :: A handle to a cmap object.                                 */
 411   /*                                                                       */
 412   /* <Return>                                                              */
 413   /*    FreeType error code.  0 means success.                             */
 414   /*                                                                       */
 415   typedef FT_Error
 416   (*TT_CharMap_Free_Func)( TT_Face        face,
 417                            TT_CMapTable*  cmap );
 418
 419
 420   /*************************************************************************/
 421   /*                                                                       */
 422   /* <FuncType>                                                            */
 423   /*    TT_Load_Table_Func                                                 */
 424   /*                                                                       */
 425   /* <Description>                                                         */
 426   /*    Loads a given TrueType table.                                      */
 427   /*                                                                       */
 428   /* <Input>                                                               */
 429   /*    face   :: A handle to the target face object.                      */
 430   /*                                                                       */
 431   /*    stream :: The input stream.                                        */
 432   /*                                                                       */
 433   /* <Return>                                                              */
 434   /*    FreeType error code.  0 means success.                             */
 435   /*                                                                       */
 436   /* <Note>                                                                */
 437   /*    The function will use `face->goto_table' to seek the stream to     */
 438   /*    the start of the table.                                            */
 439   /*                                                                       */
 440   typedef FT_Error
 441   (*TT_Load_Table_Func)( TT_Face    face,
 442                          FT_Stream  stream );
 443
 444
 445   /*************************************************************************/
 446   /*                                                                       */
 447   /* <FuncType>                                                            */
 448   /*    TT_Free_Table_Func                                                 */
 449   /*                                                                       */
 450   /* <Description>                                                         */
 451   /*    Frees a given TrueType table.                                      */
 452   /*                                                                       */
 453   /* <Input>                                                               */
 454   /*    face :: A handle to the target face object.                        */
 455   /*                                                                       */
 456   typedef void
 457   (*TT_Free_Table_Func)( TT_Face  face );
 458
 459
 460   /*************************************************************************/
 461   /*                                                                       */
 462   /* <Struct>                                                              */
 463   /*    SFNT_Interface                                                     */
 464   /*                                                                       */
 465   /* <Description>                                                         */
 466   /*    This structure holds pointers to the functions used to load and    */
 467   /*    free the basic tables that are required in a `sfnt' font file.     */
 468   /*                                                                       */
 469   /* <Fields>                                                              */
 470   /*    Check the various xxx_Func() descriptions for details.             */
 471   /*                                                                       */
 472   typedef struct  SFNT_Interface_
 473   {
 474     TT_Goto_Table_Func        goto_table;
 475
 476     TT_Init_Face_Func         init_face;
 477     TT_Load_Face_Func         load_face;
 478     TT_Done_Face_Func         done_face;
 479     SFNT_Get_Interface_Func   get_interface;
 480
 481     TT_Load_Any_Func          load_any;
 482     TT_Load_SFNT_Header_Func  load_sfnt_header;
 483     TT_Load_Directory_Func    load_directory;
 484
 485     /* these functions are called by `load_face' but they can also  */
 486     /* be called from external modules, if there is a need to do so */
 487     TT_Load_Table_Func        load_header;
 488     TT_Load_Metrics_Func      load_metrics;
 489     TT_Load_Table_Func        load_charmaps;
 490     TT_Load_Table_Func        load_max_profile;
 491     TT_Load_Table_Func        load_os2;
 492     TT_Load_Table_Func        load_psnames;
 493
 494     TT_Load_Table_Func        load_names;
 495     TT_Free_Table_Func        free_names;
 496
 497     /* optional tables */
 498     TT_Load_Table_Func        load_hdmx;
 499     TT_Free_Table_Func        free_hdmx;
 500
 501     TT_Load_Table_Func        load_kerning;
 502     TT_Load_Table_Func        load_gasp;
 503     TT_Load_Table_Func        load_pclt;
 504
 505     /* see `ttload.h' */
 506     TT_Load_Table_Func        load_bitmap_header;
 507
 508     /* see `ttsbit.h' */
 509     TT_Set_SBit_Strike_Func   set_sbit_strike;
 510     TT_Load_Table_Func        load_sbits;
 511     TT_Load_SBit_Image_Func   load_sbit_image;
 512     TT_Free_Table_Func        free_sbits;
 513
 514     /* see `ttpost.h' */
 515     TT_Get_PS_Name_Func       get_psname;
 516     TT_Free_Table_Func        free_psnames;
 517
 518     /* see `ttcmap.h' */
 519     TT_CharMap_Load_Func      load_charmap;
 520     TT_CharMap_Free_Func      free_charmap;
 521
 522   } SFNT_Interface;
 523
 524
 525 FT_END_HEADER
 526
 527 #endif /* __SFNT_H__ */
 528
 529
 530 /* END */