home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: SysTools / SysTools.zip / ft-beta.zip / freetype / lib / freetype.h < prev    next >
C/C++ Source or Header  |  1997-10-06  |  30KB  |  708 lines
  1. /*******************************************************************
  2.  *
  3.  *  freetype.h
  4.  *
  5.  *    High-level interface specification.
  6.  *
  7.  *  Copyright 1996, 1997 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.  *  Notes:
  17.  *
  18.  *    This is the only file that should be included by client            
  19.  *    application sources for the final release. All other types
  20.  *    and functions defined in the "tt*.h" files are library  
  21.  *    internals, and should not be included (except of course
  22.  *    during development, as now).
  23.  *
  24.  *    FreeType is still in alpha!
  25.  *
  26.  ******************************************************************/
  27.  
  28. #ifndef FREETYPE_H
  29. #define FREETYPE_H
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35.   /*******************************************************************/
  36.   /*                                                                 */
  37.   /*  FreeType types definitions.                                    */
  38.   /*                                                                 */
  39.   /*  All these begin with a 'TT_' prefix.                           */
  40.   /*                                                                 */
  41.   /*******************************************************************/
  42.  
  43.   typedef signed long     TT_Fixed;   /* Signed Fixed 16.16 Float */
  44.  
  45.   typedef signed short    TT_FWord;   /* Distance in FUnits */
  46.   typedef unsigned short  TT_UFWord;  /* Unsigned distance */
  47.  
  48.   typedef signed short    TT_Short;
  49.   typedef unsigned short  TT_UShort;
  50.   typedef signed long     TT_Long;
  51.   typedef unsigned long   TT_ULong;
  52.  
  53.   typedef signed short    TT_F2Dot14; /* Signed fixed float 2.14 used for */
  54.                                       /* unary vectors, with layout:      */
  55.                                       /*                                  */
  56.                                       /*  s : 1  -- sign bit              */
  57.                                       /*  m : 1  -- mantissa bit          */
  58.                                       /*  f : 14 -- unsigned fractional   */
  59.                                       /*                                  */
  60.                                       /*  's:m' is the 2-bit signed int   */
  61.                                       /*  value to which the positive     */
  62.                                       /*  fractional part should be       */
  63.                                       /*  added.                          */
  64.                                       /*                                  */
  65.   typedef signed long     TT_F26Dot6; /* 26.6 fixed float, used for       */
  66.                                       /* glyph points pixel coordinates.  */
  67.  
  68.   typedef struct  _TT_UnitVector      /* guess what...  */
  69.   { 
  70.     TT_F2Dot14  x;
  71.     TT_F2Dot14  y;
  72.   } TT_UnitVector;
  73.  
  74.   typedef struct  _TT_Vector          /* Simple vector type */
  75.   {
  76.     TT_F26Dot6  x;
  77.     TT_F26Dot6  y;
  78.   } TT_Vector;
  79.  
  80.  
  81.   typedef struct  _TT_Matrix                       
  82.   {
  83.     TT_Fixed  xx, xy;
  84.     TT_Fixed  yx, yy;
  85.   } TT_Matrix;
  86.  
  87.   /* A simple 2x2 matrix used for transforms */
  88.   /* you should use 16.16 fixed floats       */
  89.   /*                                         */
  90.   /*  x' = xx*x + xy*y                       */
  91.   /*  y' = yx*x + yy*y                       */
  92.   /*                                         */
  93.  
  94.   /* A structure used to describe the source glyph to the renderer. */
  95.   typedef struct  _TT_Glyph_Outline
  96.   {
  97.     unsigned int     contours;   /* number of contours in glyph          */
  98.     unsigned short*  conStarts;  /* points to an array of each contour's */
  99.                                  /* start point index                    */
  100.     unsigned int     points;     /* number of points in the glyph        */
  101.     long*            xCoord;     /* table of x coordinates               */
  102.     long*            yCoord;     /* table of y coordinates               */
  103.     unsigned char*   flag;       /* table of flags                       */
  104.  
  105.     char             dropout_mode;  /* dropout mode */
  106.   } TT_Glyph_Outline;
  107.  
  108.  
  109.   /* A structure used to return glyph metrics. */
  110.   typedef struct  _TT_Glyph_Metrics
  111.   {
  112.     TT_F26Dot6  leftSideBearing;
  113.     TT_F26Dot6  advanceWidth;
  114.  
  115.     TT_F26Dot6  xMin, yMin, xMax, yMax;
  116.   } TT_Glyph_Metrics;
  117.  
  118.  
  119.   /* A structure used to return instance metrics. */
  120.   typedef struct  _TT_Instance_Metrics
  121.   {
  122.     int  pointSize;
  123.     /* pointsize in points ( 1 point = 1/72 inch ) */
  124.  
  125.     int  x_ppem;  /* horizontal pixels per EM square */
  126.     int  y_ppem;  /* vertical pixels per EM square   */
  127.  
  128.     int  x_resolution;  /* device horizontal resolution in dpi */
  129.     int  y_resolution;  /* device vertical resolution in dpi   */
  130.  
  131.   } TT_Instance_Metrics;
  132.  
  133.  
  134.   /* Flow constants:                                            */
  135.   /*                                                            */
  136.   /* The flow of a bitmap refers to the way lines are oriented  */
  137.   /* within the bitmap data, i.e., the orientation of the Y     */
  138.   /* coordinate axis.                                           */
  139.  
  140.   /* for example, if the first bytes of the bitmap pertain to   */
  141.   /* its top-most line, then the flow is 'down'. if these bytes */
  142.   /* pertain to its lowest line, the the flow is 'up'.          */
  143.  
  144. #define TT_Flow_Down  -1  /* bitmap is oriented from top to bottom */
  145. #define TT_Flow_Up     1  /* bitmap is oriented from bottom to top */
  146. #define TT_Flow_Error  0  /* an error occured during rendering     */
  147.  
  148.  
  149.   /* A structure used to describe the target bitmap or pixmap to the   */
  150.   /* renderer. Note that there is nothing in this structure that gives */
  151.   /* the nature of the buffer.                                         */
  152.  
  153.   /* IMPORTANT NOTE :                                                  */
  154.   /*                                                                   */
  155.   /*   A pixmap's width _must_ be a multiple of 4. Clipping            */
  156.   /*   problems will arise otherwise, if not page faults !             */
  157.   /*                                                                   */
  158.   /*   The typical settings are :                                      */
  159.   /*                                                                   */
  160.   /*   - for an WxH bitmap :                                           */
  161.   /*                                                                   */
  162.   /*       rows  = H                                                   */
  163.   /*       cols  = (W+7)/8                                             */
  164.   /*       width = W                                                   */
  165.   /*       flow  = your_choice                                         */
  166.   /*                                                                   */
  167.   /*   - for an WxH pixmap                                             */
  168.   /*                                                                   */
  169.   /*       rows  = H                                                   */
  170.   /*       cols  = (W+3) & ~3                                          */
  171.   /*       width = cols                                                */
  172.   /*       flow  = your_choice                                         */
  173.  
  174.   typedef struct  _TT_Raster_Map
  175.   {
  176.     int     rows;    /* number of rows                    */
  177.     int     cols;    /* number of columns (bytes) per row */
  178.     int     width;   /* number of pixels per line         */
  179.     int     flow;    /* bitmap orientation                */
  180.  
  181.     void*   bitmap;  /* bit/pixmap buffer                 */
  182.     long    size;    /* bit/pixmap size in bytes          */
  183.   } TT_Raster_Map;
  184.  
  185.  
  186.  
  187.  
  188.  
  189.   /* ------- The font header TrueType table structure ----- */
  190.  
  191.   typedef struct  _TT_Header
  192.   {
  193.     TT_Fixed   Table_Version;
  194.     TT_Fixed   Font_Revision;
  195.  
  196.     TT_Long    CheckSum_Adjust;
  197.     TT_Long    Magic_Number;
  198.  
  199.     TT_UShort  Flags;
  200.     TT_UShort  Units_Per_EM;
  201.  
  202.     TT_Long    Created [2];
  203.     TT_Long    Modified[2];
  204.  
  205.     TT_FWord   xMin;
  206.     TT_FWord   yMin;
  207.     TT_FWord   xMax;
  208.     TT_FWord   yMax;
  209.  
  210.     TT_UShort  Mac_Style;
  211.     TT_UShort  Lowest_Rec_PPEM;
  212.  
  213.     TT_Short   Font_Direction;
  214.     TT_Short   Index_To_Loc_Format;
  215.     TT_Short   Glyph_Data_Format;
  216.  
  217.   } TT_Header;
  218.  
  219.   /* ------- The horizontal header TrueType table structure ----- */
  220.  
  221.   typedef struct _TT_Horizontal_Header
  222.   {
  223.     TT_Fixed   Version;
  224.     TT_FWord   Ascender;
  225.     TT_FWord   Descender;
  226.     TT_FWord   Line_Gap;
  227.  
  228.     TT_UFWord  advance_Width_Max;
  229.  
  230.     TT_FWord   min_Left_Side_Bearing;
  231.     TT_FWord   min_Right_Side_Bearing;
  232.     TT_FWord   xMax_Extent;
  233.     TT_FWord   caret_Slope_Rise;
  234.     TT_FWord   caret_Slope_Run;
  235.  
  236.     TT_Short   Reserved[5];
  237.  
  238.     TT_Short   metric_Data_Format;
  239.     TT_UShort  number_Of_HMetrics;
  240.  
  241.   } TT_Horizontal_Header;
  242.  
  243.  
  244.   /* ----------- OS/2 Table ----------------------------- */
  245.  
  246.   typedef struct _TT_OS2
  247.   {
  248.     TT_UShort  version;                /* 0x0001 */
  249.     TT_FWord   xAvgCharWidth;
  250.     TT_UShort  usWeightClass;
  251.     TT_UShort  usWidthClass;
  252.     TT_Short   fsType;
  253.     TT_FWord   ySubscriptXSize;
  254.     TT_FWord   ySubscriptYSize;
  255.     TT_FWord   ySubscriptXOffset;
  256.     TT_FWord   ySubscriptYOffset;
  257.     TT_FWord   ySuperscriptXSize;
  258.     TT_FWord   ySuperscriptYSize;
  259.     TT_FWord   ySuperscriptXOffset;
  260.     TT_FWord   ySuperscriptYOffset;
  261.     TT_FWord   yStrikeoutSize;
  262.     TT_FWord   yStrikeoutPosition;
  263.     TT_Short   sFamilyClass;
  264.  
  265.     char       panose[10];
  266.  
  267.     TT_ULong   ulUnicodeRange1;        /* Bits 0-31   */
  268.     TT_ULong   ulUnicodeRange2;        /* Bits 32-63  */
  269.     TT_ULong   ulUnicodeRange3;        /* Bits 64-95  */
  270.     TT_ULong   ulUnicodeRange4;        /* Bits 96-127 */
  271.  
  272.     char       achVendID[4];
  273.  
  274.     TT_UShort  fsSelection;
  275.     TT_UShort  usFirstCharIndex;
  276.     TT_UShort  usLastCharIndex;
  277.     TT_UShort  sTypoAscender;
  278.     TT_UShort  sTypoDescender;
  279.     TT_UShort  sTypoLineGap;
  280.     TT_UShort  usWinAscent;
  281.     TT_UShort  usWinDescent;
  282.  
  283.     /* only version 1 tables: */
  284.  
  285.     TT_ULong   ulCodePageRange1;       /* Bits 0-31   */
  286.     TT_ULong   ulCodePageRange2;       /* Bits 32-63  */
  287.  
  288.   } TT_OS2;
  289.  
  290.   /* ----------- Postscript table ------------------------ */
  291.  
  292.   typedef struct _TT_Postscript
  293.   {
  294.     TT_Fixed  FormatType;
  295.     TT_Fixed  italicAngle;
  296.     TT_FWord  underlinePosition;
  297.     TT_FWord  underlineThickness;
  298.     TT_ULong  isFixedPitch;
  299.     TT_ULong  minMemType42;
  300.     TT_ULong  maxMemType42;
  301.     TT_ULong  minMemType1;
  302.     TT_ULong  maxMemType1;
  303.  
  304.     /* glyph names follow in the file, but we don't */
  305.     /* load them by default..                       */
  306.  
  307.   } TT_Postscript;
  308.  
  309.  
  310.  
  311.   /* A structure used to describe face properties. */
  312.   typedef struct  _TT_Face_Properties
  313.   {
  314.     int  num_Glyphs;   /* number of glyphs in face              */
  315.     int  max_Points;   /* maximum number of points in a glyph   */
  316.     int  max_Contours; /* maximum number of contours in a glyph */
  317.  
  318.     int  max_Faces;    /* 0 for normal TrueType files, and the  */
  319.                        /* number of embedded faces minus 1 for  */
  320.                        /* TrueType collections                  */
  321.  
  322.     TT_Header*             header;        /* TrueType header table      */
  323.     TT_Horizontal_Header*  horizontal;    /* TrueType horizontal header */
  324.     TT_OS2*                os2;           /* TrueType OS/2 table        */
  325.     TT_Postscript*         postscript;    /* TrueType Postscript table  */
  326.  
  327.   } TT_Face_Properties;
  328.  
  329.  
  330.   /* Here are the definitions of the handle types used for FreeType's */
  331.   /* most common objects accessed by the client application. We use   */
  332.   /* a simple trick there:                                            */
  333.   /*                                                                  */
  334.   /*   Each handle type is a structure that only contains one         */
  335.   /*   pointer. The advantage of structures is that there are         */
  336.   /*   mutually exclusive types. We could have defined the            */
  337.   /*   following types:                                               */
  338.   /*                                                                  */
  339.   /*     typedef void*  TT_Stream;                                    */
  340.   /*     typedef void*  TT_Face;                                      */
  341.   /*     typedef void*  TT_Instance;                                  */
  342.   /*     typedef void*  TT_Glyph;                                     */
  343.   /*     typedef void*  TT_CharMap;                                   */
  344.   /*                                                                  */
  345.   /*   but these would have allowed lines like:                       */
  346.   /*                                                                  */
  347.   /*      stream = instance;                                          */
  348.   /*                                                                  */
  349.   /*   in the client code this would be a severe bug, unnoticed       */
  350.   /*   by the compiler!                                               */
  351.   /*                                                                  */
  352.   /*   Thus, we enforce type checking with a simple language          */
  353.   /*   trick...                                                       */
  354.   /*                                                                  */
  355.   /*   NOTE:  Some macros are defined in tttypes.h to perform         */
  356.   /*          automatic type conversions for library hackers..        */
  357.   /*                                                                  */
  358.  
  359.   struct _TT_Stream   { void*  z; };
  360.   struct _TT_Face     { void*  z; };
  361.   struct _TT_Instance { void*  z; };
  362.   struct _TT_Glyph    { void*  z; };
  363.   struct _TT_CharMap  { void*  z; };
  364.  
  365.   typedef struct _TT_Stream    TT_Stream;    /* stream handle type        */
  366.   typedef struct _TT_Face      TT_Face;      /* face handle type          */
  367.   typedef struct _TT_Instance  TT_Instance;  /* instance handle type      */
  368.   typedef struct _TT_Glyph     TT_Glyph;     /* glyph handle type         */
  369.   typedef struct _TT_CharMap   TT_CharMap;   /* character map handle type */
  370.  
  371.   typedef int  TT_Error;
  372.  
  373.   /*******************************************************************/
  374.   /*                                                                 */
  375.   /*  FreeType API                                                   */
  376.   /*                                                                 */
  377.   /*  All these begin with a 'TT_' prefix.                           */
  378.   /*                                                                 */
  379.   /*  Most of them are implemented in the 'ttapi.c' source file.     */
  380.   /*                                                                 */
  381.   /*******************************************************************/
  382.  
  383.   /* Initialize the engine. */
  384.   TT_Error  TT_Init_FreeType();
  385.  
  386.   /* Finalize the engine, and release all allocated objects. */
  387.   TT_Error  TT_Done_FreeType();
  388.  
  389.   /* Set the gray level palette. This is an array of 5 bytes used */
  390.   /* to produce the font smoothed pixmaps. By convention :        */
  391.   /*                                                              */
  392.   /*  palette[0] = background (white)                             */
  393.   /*  palette[1] = light                                          */
  394.   /*  palette[2] = medium                                         */
  395.   /*  palette[3] = dark                                           */
  396.   /*  palette[4] = foreground (black)                             */
  397.   /*                                                              */
  398.   TT_Error  TT_Set_Raster_Gray_Palette( char*  palette );
  399.   
  400.  
  401.   /* Open a new TrueType font file, and returns a handle for */
  402.   /* it in variable '*face'.                                 */
  403.  
  404.   /* Note : the file can be either a TrueType file (*.ttf) or  */
  405.   /*        a TrueType collection (*.ttc), in this case, only  */
  406.   /*        the first face is opened. The number of faces in   */
  407.   /*        the same collection can be obtained in the face's  */
  408.   /*        properties, through TT_Get_Face_Properties and the */
  409.   /*        'max_Faces' field.                                 */
  410.  
  411.   TT_Error  TT_Open_Face( const char*  fontpathname,
  412.                           TT_Face*     face );
  413.  
  414.   /* Open a TrueType font file located inside a collection */
  415.   /* The font is designed by its index in 'fontIndex'      */
  416.  
  417.   TT_Error  TT_Open_Collection( const char*  collectionpathname,
  418.                                 int          fontIndex,
  419.                                 TT_Face*     face );
  420.  
  421.   /* Return face properties in the 'properties' structure. */
  422.   TT_Error  TT_Get_Face_Properties( TT_Face              face,
  423.                                     TT_Face_Properties*  properties );
  424.  
  425.   /* Close a given font object, destroying all associated     */
  426.   /* instances.                                               */
  427.   TT_Error  TT_Close_Face( TT_Face  face );
  428.  
  429.   /* Open a new font instance and returns an instance handle   */
  430.   /* for it in '*instance'.                                    */
  431.   TT_Error  TT_New_Instance( TT_Face       face,
  432.                              TT_Instance*  instance );
  433.  
  434.   /* Set device resolutions for a given instance. the values are     */
  435.   /* given in dpi (Dots Per Inch). Default is 96 in both directions. */
  436.  
  437.   /* NOTE:  y_resolution is currently ignored, and the lib assumes   */
  438.   /*        square pixels.                                           */
  439.   TT_Error  TT_Set_Instance_Resolution( TT_Instance  instance,
  440.                                         int          x_resolution,
  441.                                         int          y_resolution );
  442.  
  443.   /* Set the pointsize for a given instance. Default is 10. */
  444.   TT_Error  TT_Set_Instance_PointSize( TT_Instance  instance,
  445.                                        int          pointsize );
  446.  
  447.   TT_Error  TT_Set_Instance_Transforms( TT_Instance instance,
  448.                                         int         rotated,
  449.                                         int         stretched );
  450.   /* We do not provide direct support for rotation or stretching, */
  451.   /* which means that you must perform these operations through   */
  452.   /* a call to TT_Apply_Outline_Transform yourself before calling */
  453.   /* TT_Get_Glyph_Bitmap.. However, the engine needs to know what */
  454.   /* kind of text you're displaying. The following boolean flags  */
  455.   /* notice the interpreter that :                                */
  456.   /*                                                              */
  457.   /*   rotated  : the glyphs will be rotated                      */
  458.   /*   stretched: the glyphs will be stretched                    */
  459.   /*                                                              */
  460.   /* These setting only affect the hinting process !              */
  461.   /*                                                              */
  462.  
  463.   /* Return instance metrics in 'metrics'. */
  464.   TT_Error  TT_Get_Instance_Metrics( TT_Instance           instance,
  465.                                      TT_Instance_Metrics*  metrics );
  466.  
  467.   /* Close a given instance object, destroying all associated */
  468.   /* data.                                                    */
  469.   TT_Error  TT_Done_Instance( TT_Instance  instance );
  470.  
  471.   /* Create a new glyph object related to the given 'face'.   */
  472.   TT_Error  TT_New_Glyph( TT_Face    face,
  473.                           TT_Glyph*  glyph );
  474.  
  475.   /* Discard (and destroy) a given glyph object. */
  476.   TT_Error  TT_Done_Glyph( TT_Glyph  glyph );
  477.  
  478.  
  479. #define TTLOAD_SCALE_GLYPH  1
  480. #define TTLOAD_HINT_GLYPH   2
  481.  
  482. #define TTLOAD_DEFAULT  (TTLOAD_SCALE_GLYPH | TTLOAD_HINT_GLYPH)
  483.  
  484.  
  485.   /* load and process (scale/transform and hint) a glyph from the */
  486.   /* given 'instance'. The glyph and instance handles must be     */
  487.   /* related to the same face object. The glyph index can be      */
  488.   /* computed with a call to TT_Char_Index                        */
  489.  
  490.   /* the 'load_flags' argument is a combination of the macros     */
  491.   /* TTLOAD_SCALE_GLYPH and TTLOAD_HINT_GLYPH. Hinting will be    */
  492.   /* applied only if the scaling is selected..                    */
  493.  
  494.   /* When scaling is off (i.e. load_flags = 0), the returned      */
  495.   /* outlines are in EM square coordinates (also called FUnits),  */
  496.   /* extracted directly from the font with no hinting.            */
  497.   /* Other glyph metrics are also in FUnits..                     */
  498.  
  499.   /* When scaling is on, the returned outlines are in fractional  */
  500.   /* pixel units (i.e. TT_F26Dot6 = 26.6 fixed floats).           */
  501.  
  502.   /* NOTE : the glyph index must be in the range 0..num_glyphs-1  */
  503.   /*        where 'num_glyphs' is the total number of glyphs in   */
  504.   /*        the font file (given in the face properties)..        */
  505.   TT_Error  TT_Load_Glyph( TT_Instance  instance,
  506.                            TT_Glyph     glyph,
  507.                            int          glyph_index,
  508.                            int          load_flags );
  509.  
  510.   /* Return glyph outline pointers in 'outline'. Note that the returned */
  511.   /* pointers are owned by the glyph object, and will be destroyed with */
  512.   /* it. The client application should _not_ change the pointers.       */
  513.   TT_Error  TT_Get_Glyph_Outline( TT_Glyph           glyph,
  514.                                   TT_Glyph_Outline*  outline );
  515.  
  516.   /* Copy the glyph metrics into 'metrics'. */
  517.   TT_Error  TT_Get_Glyph_Metrics( TT_Glyph           glyph,
  518.                                   TT_Glyph_Metrics*  metrics );
  519.  
  520.   /* Render the glyph into a bitmap, with given position offsets. */
  521.   TT_Error  TT_Get_Glyph_Bitmap( TT_Glyph        glyph,
  522.                                  TT_Raster_Map*  map,
  523.                                  TT_F26Dot6      x_offset,
  524.                                  TT_F26Dot6      y_offset );
  525.  
  526.   /* Render the glyph into a pixmap, with given position offsets. */
  527.   TT_Error  TT_Get_Glyph_Pixmap( TT_Glyph        glyph,
  528.                                  TT_Raster_Map*  map,
  529.                                  TT_F26Dot6      x_offset,
  530.                                  TT_F26Dot6      y_offset );
  531.  
  532.   TT_Error  TT_Apply_Outline_Matrix( TT_Glyph_Outline*  outline,
  533.                                      TT_Matrix*         matrix );
  534.   /* Apply a transform to a glyph outline */
  535.  
  536.   TT_Error  TT_Apply_Outline_Translation( TT_Glyph_Outline*  outline,
  537.                                           TT_F26Dot6         x_offset,
  538.                                           TT_F26Dot6         y_offset );
  539.   /* Apply a translation to a glyph outline */
  540.  
  541.   /* ----------------- character mappings support ------------- */
  542.  
  543.   /* Return the number of character mappings found in this file */
  544.   /* Returns -1 in case of failure (invalid face handle)        */
  545.   int  TT_Get_CharMap_Count( TT_Face  face );
  546.  
  547.   /* Return the ID of charmap number 'charmapIndex' of a given face */
  548.   /* used to enumerate the charmaps present in a TrueType file      */
  549.   TT_Error   TT_Get_CharMap_ID( TT_Face  face,
  550.                                 int      charmapIndex,
  551.                                 short*   platformID,
  552.                                 short*   encodingID );
  553.  
  554.   /* Look up the character maps found in 'face' and return a handle */
  555.   /* for the one matching 'platformID' and 'platformEncodingID'     */
  556.   /* (see the TrueType specs relating to the 'cmap' table for       */
  557.   /* information on these ID numbers). Returns an error code.       */
  558.   /* In case of failure, the handle is set to NULL and is invalid.  */
  559.   TT_Error  TT_Get_CharMap( TT_Face      face,
  560.                             int          charmapIndex,
  561.                             TT_CharMap*  charMap );
  562.  
  563.   /* Translate a character code through a given character map   */
  564.   /* and return the corresponding glyph index to be used in     */
  565.   /* a TT_Load_Glyph call. This function returns -1 in case of  */
  566.   /* failure.                                                   */
  567.   int  TT_Char_Index( TT_CharMap      charMap,
  568.                       unsigned short  charCode );
  569.  
  570.   /* --------------------- names table support ------------------- */
  571.  
  572.   /* Return the number of name strings found in the name table */
  573.   /* Returns -1 in case of failure (invalid face handle)       */
  574.   int  TT_Get_Name_Count( TT_Face  face );
  575.  
  576.   /* Return the ID of the name number 'nameIndex' of a given face */
  577.   /* used to enumerate the charmaps present in a TrueType file    */
  578.   TT_Error  TT_Get_Name_ID( TT_Face  face,
  579.                             int      nameIndex,
  580.                             short*   platformID,
  581.                             short*   encodingID,
  582.                             short*   languageID,
  583.                             short*   nameID );
  584.  
  585.   /* Return the address and length of the name number 'nameIndex' */
  586.   /* of a given face. The string is part of the face object and   */
  587.   /* shouldn't be written to or released.                         */
  588.  
  589.   /* Note that if the string platformID is not in the range 0..3  */
  590.   /* A null pointer will be returned !                            */
  591.   TT_Error  TT_Get_Name_String( TT_Face  face,
  592.                                 int      nameIndex,
  593.                                 char**   stringPtr, /* address of pointer     */
  594.                                 int*     length );  /* address of str. length */
  595.  
  596.   /************************ error codes declaration **************/
  597.   
  598.   /* The error codes are grouped in 'classes' used to indicate the */
  599.   /* 'level' at which the error happened.                          */
  600.   /* The class is given by an error code's high byte..             */
  601.  
  602.   /* ------------- Success is always 0 -------- */
  603.  
  604.   #define TT_Err_Ok                      0
  605.   
  606.   /* -------- High-level API error codes ------ */
  607.   
  608.   #define TT_Err_Invalid_Face_Handle      0x001
  609.   #define TT_Err_Invalid_Instance_Handle  0x002
  610.   #define TT_Err_Invalid_Glyph_Handle     0x003
  611.   #define TT_Err_Invalid_CharMap_Handle   0x004
  612.   #define TT_Err_Invalid_Result_Address   0x005
  613.   #define TT_Err_Invalid_Glyph_Index      0x006
  614.   #define TT_Err_Invalid_Argument         0x007
  615.   #define TT_Err_Could_Not_Open_File      0x008
  616.   #define TT_Err_File_Is_Not_Collection   0x009
  617.   
  618.   #define TT_Err_Table_Missing            0x00A
  619.   #define TT_Err_Invalid_Horiz_Metrics    0x00B
  620.   #define TT_Err_Invalid_CharMap_Format   0x00C
  621.  
  622.   #define TT_Err_Invalid_File_Format      0x010
  623.   
  624.   /* -------- Memory component error codes ---- */
  625.  
  626.   /* this error indicates that an operation cannot */
  627.   /* be performed due to memory exhaustion         */
  628.  
  629.   #define TT_Err_Out_Of_Memory            0x100
  630.   
  631.   /* -------- File component error codes ------ */
  632.   
  633.   /* these error codes indicate that the file could */
  634.   /* not be accessed properly. Usually, this means  */
  635.   /* a broken font file !                           */
  636.  
  637.   #define TT_Err_Invalid_File_Offset      0x200
  638.   #define TT_Err_Invalid_File_Read        0x201
  639.   #define TT_Err_Invalid_Frame_Access     0x202
  640.   
  641.   /* -------- Glyph loader error codes -------- */
  642.   
  643.   /* Produced only by the glyph loader, these error */
  644.   /* codes indicate a broken glyph in a font file   */
  645.  
  646.   #define TT_Err_Too_Many_Points          0x300
  647.   #define TT_Err_Too_Many_Contours        0x301
  648.   #define TT_Err_Invalid_Composite        0x302
  649.   #define TT_Err_Too_Many_Ins             0x303
  650.   
  651.   /* --- bytecode interpreter error codes ----- */
  652.   
  653.   /* These error codes are produced by the TrueType */
  654.   /* bytecode interpreter. They usually indicate a  */
  655.   /* broken font file, a broken glyph within a font */
  656.   /* file, or a bug in the interpreter !            */
  657.  
  658.   #define TT_Err_Invalid_Opcode           0x400
  659.   #define TT_Err_Too_Few_Arguments        0x401
  660.   #define TT_Err_Stack_Overflow           0x402
  661.   #define TT_Err_Code_Overflow            0x403
  662.   #define TT_Err_Bad_Argument             0x404
  663.   #define TT_Err_Divide_By_Zero           0x405
  664.   #define TT_Err_Storage_Overflow         0x406
  665.   #define TT_Err_Cvt_Overflow             0x407
  666.   #define TT_Err_Invalid_Reference        0x408
  667.   #define TT_Err_Invalid_Distance         0x409
  668.   #define TT_Err_Interpolate_Twilight     0x40A
  669.   #define TT_Err_Debug_OpCode             0x40B
  670.   #define TT_Err_ENDF_In_Exec_Stream      0x40C
  671.   #define TT_Err_Out_Of_CodeRanges        0x40D
  672.   #define TT_Err_Nested_DEFS              0x40E 
  673.   #define TT_Err_Invalid_Coderange        0x40F
  674.   
  675.   /* ------ internal failures error codes ----- */
  676.  
  677.   /* These error codes are produced when an incoherent */
  678.   /* library state has been detected. These reflect a  */
  679.   /* severe bug in the engine ! (or a major overwrite  */
  680.   /* of your application into the library's data)      */
  681.   
  682.   #define TT_Err_Nested_Frame_Access      0x500
  683.   #define TT_Err_Invalid_Cache_List       0x501
  684.   #define TT_Err_Could_Not_Find_Context   0x502
  685.   #define TT_Err_Unlisted_Object          0x503
  686.   
  687.   /* ---- scan-line converter error codes ----- */
  688.   
  689.   /* These error codes are produced by the raster component   */
  690.   /* They indicate that an outline structure was incoherently */
  691.   /* setup, or that you're trying to render an horribly       */
  692.   /* complex glyph !                                          */
  693.  
  694.   #define TT_Err_Raster_Pool_Overflow     0x600
  695.   #define TT_Err_Raster_Negative_Height   0x601
  696.   #define TT_Err_Raster_Invalid_Value     0x602
  697.   #define TT_Err_Raster_Not_Initialized   0x603
  698.   
  699.  
  700. #ifdef __cplusplus
  701. }
  702. #endif
  703.  
  704. #endif /* FREETYPE_H */
  705.  
  706.  
  707. /* End */
  708.