path: root/include/freetype/internal/sfnt.h

/***************************************************************************/
/*                                                                         */
/*  sfnt.h                                                                 */
/*                                                                         */
/*    High-level `sfnt' driver interface (specification).                  */
/*                                                                         */
/*  Copyright 1996-2000 by                                                 */
/*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
/*                                                                         */
/*  This file is part of the FreeType project, and may only be used,       */
/*  modified, and distributed under the terms of the FreeType project      */
/*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
/*  this file you indicate that you have read the license and              */
/*  understand and accept it fully.                                        */
/*                                                                         */
/***************************************************************************/


#ifndef SFNT_H
#define SFNT_H

#include <freetype/freetype.h>
#include <freetype/internal/ftdriver.h>
#include <freetype/internal/tttypes.h>


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Init_Face_Func                                                  */
  /*                                                                       */
  /* <Description>                                                         */
  /*    First part of the SFNT face object initialisation. This will       */
  /*    find the face in a SFNT file or collection, and load its           */
  /*    format tag in face->format_tag.                                    */
  /*                                                                       */
  /* <Input>                                                               */
  /*    stream     :: The input stream.                                    */
  /*    face       :: A handle to the target face object.                  */
  /*    faceIndex  :: The index of the TrueType font, if we're opening a   */
  /*                  collection.                                          */
  /*    num_params :: number of additional parameters                      */
  /*    params     :: optional additional parameters                       */
  /*                                                                       */
  /* <Return>                                                              */
  /*    FreeType error code.  0 means success.                             */
  /*                                                                       */
  /* <Note>                                                                */
  /*    The stream cursor must be at the font file's origin                */
  /*    This function recognizes fonts embedded in a "TrueType collection" */
  /*                                                                       */
  /*    Once the format tag has been validated by the font driver, it      */
  /*    should then call the TT_Load_Face_Func callback to read the rest   */
  /*    of the SFNT tables in the object..                                 */
  /*                                                                       */
  typedef
  FT_Error  (*TT_Init_Face_Func)( FT_Stream      stream,
                                  TT_Face        face,
                                  FT_Int         face_index,
                                  FT_Int         num_params,
                                  FT_Parameter*  params );

  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_Face_Func                                                  */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Second part of the SFNT face object initialisation. This will      */
  /*    load the common SFNT tables (head, OS/2, maxp, metrics, etc..)     */
  /*    in the face object..                                               */
  /*                                                                       */
  /* <Input>                                                               */
  /*    stream     :: The input stream.                                    */
  /*    face       :: A handle to the target face object.                  */
  /*    faceIndex  :: The index of the TrueType font, if we're opening a   */
  /*                  collection.                                          */
  /*    num_params :: number of additional parameters                      */
  /*    params     :: optional additional parameters                       */
  /*                                                                       */
  /* <Return>                                                              */
  /*    FreeType error code.  0 means success.                             */
  /*                                                                       */
  /* <Note>                                                                */
  /*    This function must be called after TT_Init_Face_Func               */
  /*                                                                       */
  typedef
  FT_Error  (*TT_Load_Face_Func)( FT_Stream      stream,
                                  TT_Face        face,
                                  FT_Int         face_index,
                                  FT_Int         num_params,
                                  FT_Parameter*  params );

  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Done_Face_Func                                                  */
  /*                                                                       */
  /* <Description>                                                         */
  /*    A callback used to delete the common SFNT data from a face.        */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face       :: A handle to the target face object.                  */
  /*                                                                       */
  /* <Note>                                                                */
  /*    This function does NOT destroy the face object..                   */
  /*                                                                       */
  typedef
  void    (*TT_Done_Face_Func)( TT_Face   face );


  typedef
  FTDriver_Interface  (*SFNT_Get_Interface_Func)( FT_Driver    driver,
                                                  const char*  interface );


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_SFNT_Header                                                */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads the header of a SFNT font file. Supports collections..       */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face      :: A handle to the target face object.                   */
  /*    stream    :: The input stream.                                     */
  /*                                                                       */
  /* <Output>                                                              */
  /*    sfnt      :: the sfnt header                                       */
  /*                                                                       */
  /* <Return>                                                              */
  /*    TrueType error code.  0 means success.                             */
  /*                                                                       */
  /* <Note>                                                                */
  /*    The stream cursor must be at the font file's origin                */
  /*    This function recognizes fonts embedded in a "TrueType collection" */
  /*                                                                       */
  /*    This function checks that the header is valid by looking at the    */
  /*    values of "search_range", "entry_selector" and "range_shift"..     */
  /*                                                                       */
  typedef
  TT_Error  (*TT_Load_SFNT_Header_Func)( TT_Face      face,
                                         FT_Stream    stream,
                                         TT_Long      faceIndex,
                                         SFNT_Header* sfnt );

  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_Directory_Func                                             */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads the table directory into a face object.                      */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face      :: A handle to the target face object.                   */
  /*    stream    :: The input stream.                                     */
  /*    sfnt      :: sfnt header                                           */
  /*                                                                       */
  /* <Return>                                                              */
  /*    TrueType error code.  0 means success.                             */
  /*                                                                       */
  /* <Note>                                                                */
  /*    The stream cursor must be on the first byte after the 4-byte       */
  /*    font format tag. This is the case just after a call to             */
  /*    TT_Load_Format_Tag                                                 */
  /*                                                                       */
  typedef
  TT_Error  (*TT_Load_Directory_Func)( TT_Face       face,
                                       FT_Stream     stream,
                                       SFNT_Header*  sfnt );


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_Any_Func                                                   */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads any font table into client memory.  Used by the              */
  /*    TT_Get_Font_Data() API function.                                   */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face   :: The face object to look for.                             */
  /*                                                                       */
  /*    tag    :: The tag of table to load.  Use the value 0 if you  want  */
  /*              to access the whole font file, else set this parameter   */
  /*              to a valid TrueType table tag that you can forge with    */
  /*              the MAKE_TT_TAG macro.                                   */
  /*                                                                       */
  /*    offset :: The starting offset in the table (or the file if         */
  /*              tag == 0).                                               */
  /*                                                                       */
  /*    length :: The address of the decision variable:                    */
  /*                                                                       */
  /*                If length == NULL:                                     */
  /*                  Loads the whole table.  Returns an error if          */
  /*                  `offset' == 0!                                       */
  /*                                                                       */
  /*                If *length == 0:                                       */
  /*                  Exits immediately; returning the length of the given */
  /*                  table or of the font file, depending on the value of */
  /*                  `tag'.                                               */
  /*                                                                       */
  /*                If *length != 0:                                       */
  /*                  Loads the next `length' bytes of table or font,      */
  /*                  starting at offset `offset' (in table or font too).  */
  /*                                                                       */
  /* <Output>                                                              */
  /*    buffer :: The address of target buffer.                            */
  /*                                                                       */
  /* <Return>                                                              */
  /*    TrueType error code.  0 means success.                             */
  /*                                                                       */
  typedef
  TT_Error  (*TT_Load_Any_Func)( TT_Face   face,
                                 TT_ULong  tag,
                                 TT_Long   offset,
                                 void*     buffer,
                                 TT_Long*  length );


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_SBit_Image_Func                                            */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads a given glyph sbit image from the font resource.  This also  */
  /*    returns its metrics.                                               */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face        :: The target face object.                             */
  /*                                                                       */
  /*    x_ppem      :: The horizontal resolution in points per EM.         */
  /*                                                                       */
  /*    y_ppem      :: The vertical resolution in points per EM.           */
  /*                                                                       */
  /*    glyph_index :: The current glyph index.                            */
  /*                                                                       */
  /*    stream      :: The input stream.                                   */
  /*                                                                       */
  /* <Output>                                                              */
  /*    map         :: The target pixmap.                                  */
  /*    metrics     :: A big sbit metrics structure for the glyph image.   */
  /*                                                                       */
  /* <Return>                                                              */
  /*    TrueType error code.  0 means success.  Returns an error if no     */
  /*    glyph sbit exists for the index.                                   */
  /*                                                                       */
  /*  <Note>                                                               */
  /*    The `map.buffer' field is always freed before the glyph is loaded. */
  /*                                                                       */
  typedef
  TT_Error  (*TT_Load_SBit_Image_Func)( TT_Face           face,
                                        TT_Int            x_ppem,
                                        TT_Int            y_ppem,
                                        TT_UInt           glyph_index,
                                        TT_UInt           load_flags,
                                        FT_Stream         stream,
                                        FT_Bitmap*        map,
                                        TT_SBit_Metrics*  metrics );

  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Get_PS_Name_Func                                                */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Gets the PostScript glyph name of a glyph.                         */
  /*                                                                       */
  /* <Input>                                                               */
  /*    index  :: The glyph index.                                         */
  /*                                                                       */
  /*    PSname :: The address of a string pointer.  Will be NULL in case   */
  /*              of error, otherwise it is a pointer to the glyph name.   */
  /*                                                                       */
  /*              You must not modify the returned string!                 */
  /*                                                                       */
  /* <Output>                                                              */
  /*    TrueType error code.  0 means success.                             */
  /*                                                                       */
  typedef
  TT_Error (*TT_Get_PS_Name_Func)( TT_Face      face,
                                   TT_UInt      index,
                                   TT_String**  PSname );


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_Metrics                                                    */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads the horizontal or vertical header in a face object.          */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face     :: A handle to the target face object.                    */
  /*    stream   :: The input stream.                                      */
  /*    vertical :: A boolean flag.  If set, load vertical metrics.        */
  /*                                                                       */
  /* <Return>                                                              */
  /*    TrueType error code.  0 means success.                             */
  /*                                                                       */
  typedef
  TT_Error  (*TT_Load_Metrics_Func)( TT_Face    face,
                                     FT_Stream  stream,
                                     TT_Bool    vertical );



  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_CharMap_Load_Func                                               */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads a given TrueType character map into memory.                  */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face   :: A handle to the parent face object.                      */
  /*    stream :: A handle to the current stream object.                   */
  /*                                                                       */
  /* <InOut>                                                               */
  /*    cmap   :: A pointer to a cmap object.                              */
  /*                                                                       */
  /* <Return>                                                              */
  /*    Error code.  0 means success.                                      */
  /*                                                                       */
  /* <Note>                                                                */
  /*    The function assumes that the stream is already in use (i.e.,      */
  /*    opened).  In case of error, all partially allocated tables are     */
  /*    released.                                                          */
  /*                                                                       */
  typedef
  TT_Error  (*TT_CharMap_Load_Func)( TT_Face        face,
                                     TT_CMapTable*  cmap,
                                     FT_Stream      input );


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_CharMap_Free_Func                                               */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Destroys a character mapping table.                                */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face :: A handle to the parent face object.                        */
  /*    cmap :: A handle to a cmap object.                                 */
  /*                                                                       */
  /* <Return>                                                              */
  /*    Error code.  0 means success.                                      */
  /*                                                                       */
  typedef
  TT_Error  (*TT_CharMap_Free_Func)( TT_Face        face,
                                     TT_CMapTable*  cmap );


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_Table                                                      */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads a given TrueType table.                                      */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face   :: A handle to the target face object.                      */
  /*    stream :: The input stream.                                        */
  /*                                                                       */
  /* <Return>                                                              */
  /*    TrueType error code.  0 means success.                             */
  /*                                                                       */
  /* <Note>                                                                */
  /*    The function will use `face->goto_table' to seek the stream to     */
  /*    the start of the table                                             */
  /*                                                                       */
  typedef
  TT_Error  (*TT_Load_Table_Func)( TT_Face    face,
                                   FT_Stream  stream );


  /*************************************************************************/
  /*                                                                       */
  /* <FuncType>                                                            */
  /*    TT_Load_Table                                                      */
  /*                                                                       */
  /* <Description>                                                         */
  /*    Loads a given TrueType table.                                      */
  /*                                                                       */
  /* <Input>                                                               */
  /*    face   :: A handle to the target face object.                      */
  /*    stream :: The input stream.                                        */
  /*                                                                       */
  /* <Return>                                                              */
  /*    TrueType error code.  0 means success.                             */
  /*                                                                       */
  /* <Note>                                                                */
  /*    The function will use `face->goto_table' to seek the stream to     */
  /*    the start of the table                                             */
  /*                                                                       */
  typedef
  void  (*TT_Free_Table_Func)( TT_Face  face );



  /*************************************************************************/
  /*                                                                       */
  /* <Struct>                                                              */
  /*    SFNT_Interface                                                     */
  /*                                                                       */
  /* <Description>                                                         */
  /*    this structure holds pointers to the functions used to load and    */
  /*    free the basic tables that are required in a `sfnt' font file.     */
  /*                                                                       */
  /* <Fields>                                                              */
  /*                                                                       */
  /*                                                                       */
  /*                                                                       */
  /*                                                                       */
  /*                                                                       */
  /*                                                                       */
  /*                                                                       */
  /*                                                                       */
  typedef struct  SFNT_Interface_
  {
    TT_Goto_Table_Func       goto_table;

    TT_Init_Face_Func        init_face;
    TT_Load_Face_Func        load_face;
    TT_Done_Face_Func        done_face;
    SFNT_Get_Interface_Func  get_interface;
    
    TT_Load_Any_Func         load_any;
    TT_Load_SFNT_Header_Func load_sfnt_header;
    TT_Load_Directory_Func   load_directory;

    /* these functions are called by "load_face" but they can also */
    /* be called from external modules, if there is a need to      */
    TT_Load_Table_Func       load_header;
    TT_Load_Metrics_Func     load_metrics;
    TT_Load_Table_Func       load_charmaps;
    TT_Load_Table_Func       load_max_profile;
    TT_Load_Table_Func       load_os2;
    TT_Load_Table_Func       load_psnames;

    TT_Load_Table_Func       load_names;
    TT_Free_Table_Func       free_names;

    /* optional tables */
    TT_Load_Table_Func       load_hdmx;
    TT_Free_Table_Func       free_hdmx;

    TT_Load_Table_Func       load_kerning;
    TT_Load_Table_Func       load_gasp;
	TT_Load_Table_Func       load_pclt;

    /* see `ttsbit.h' */
    TT_Load_Table_Func       load_sbits;
    TT_Load_SBit_Image_Func  load_sbit_image;
    TT_Free_Table_Func       free_sbits;

    /* see `ttpost.h' */
    TT_Get_PS_Name_Func      get_psname;
    TT_Free_Table_Func       free_psnames;

    /* see `ttcmap.h' */
    TT_CharMap_Load_Func     load_charmap;
    TT_CharMap_Free_Func     free_charmap;

  } SFNT_Interface;

#endif /* SFNT_H */


/* END */