Subversion Repositories Kolibri OS

Rev

Blame | Last modification | View Log | Download | RSS feed

  1. /*******************************************************************
  2.  *
  3.  *  freetype.h
  4.  *
  5.  *    High-level interface specification.
  6.  *
  7.  *  Copyright 1996-1999 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.  *  Note:
  17.  *
  18.  *    This is the only file that should be included by client
  19.  *    application sources.  All other types and functions defined
  20.  *    in the `tt*.h' files are library internals and should not be
  21.  *    included.
  22.  *
  23.  ******************************************************************/
  24.  
  25. #ifndef FREETYPE_H
  26. #define FREETYPE_H
  27.  
  28.  
  29. #define TT_FREETYPE_MAJOR  1
  30. #define TT_FREETYPE_MINOR  3
  31.  
  32.  
  33. #include "fterrid.h"
  34. #include "ftnameid.h"
  35.  
  36. /* To make freetype.h independent from configuration files we check */
  37. /* whether EXPORT_DEF has been defined already.                     */
  38.  
  39. #ifndef EXPORT_DEF
  40. #define EXPORT_DEF  extern
  41. #endif
  42.  
  43. /* The same for TT_Text.  If you define the HAVE_TT_TEXT macro, you */
  44. /* have to provide a typedef declaration for TT_Text before         */
  45. /* including this file.                                             */
  46.  
  47. #ifndef HAVE_TT_TEXT
  48. #define HAVE_TT_TEXT
  49.   typedef char  TT_Text;              /* The data type to represent */
  50.                                       /* file name string elements. */
  51. #endif
  52.  
  53. #ifdef __cplusplus
  54.   extern "C" {
  55. #endif
  56.  
  57.  
  58.   /*******************************************************************/
  59.   /*                                                                 */
  60.   /*  FreeType types definitions.                                    */
  61.   /*                                                                 */
  62.   /*  All these begin with a 'TT_' prefix.                           */
  63.   /*                                                                 */
  64.   /*******************************************************************/
  65.  
  66.   typedef int             TT_Bool;
  67.  
  68.   typedef signed long     TT_Fixed;   /* signed fixed 16.16 float */
  69.  
  70.   typedef signed short    TT_FWord;   /* distance in FUnits */
  71.   typedef unsigned short  TT_UFWord;  /* unsigned distance  */
  72.  
  73.   typedef char            TT_String;
  74.   typedef signed char     TT_Char;
  75.   typedef unsigned char   TT_Byte;
  76.   typedef signed short    TT_Short;
  77.   typedef unsigned short  TT_UShort;
  78.   typedef int             TT_Int;
  79.   typedef unsigned int    TT_UInt;
  80.   typedef signed long     TT_Long;
  81.   typedef unsigned long   TT_ULong;
  82.  
  83.   typedef signed short    TT_F2Dot14; /* Signed fixed float 2.14 used for */
  84.                                       /* unit vectors, with layout        */
  85.                                       /*                                  */
  86.                                       /*   s : 1  -- sign bit             */
  87.                                       /*   m : 1  -- integer bit          */
  88.                                       /*   f : 14 -- unsigned fractional  */
  89.                                       /*                                  */
  90.                                       /* `s:m' is the 2-bit signed int    */
  91.                                       /* value to which the positive      */
  92.                                       /* fractional part should be added. */
  93.  
  94.   typedef signed long     TT_F26Dot6; /* 26.6 fixed float, used for       */
  95.                                       /* glyph points pixel coordinates.  */
  96.  
  97.   typedef signed long     TT_Pos;     /* Point position, expressed either */
  98.                                       /* in fractional pixels or notional */
  99.                                       /* units, depending on context.     */
  100.                                       /* For example, glyph coordinates   */
  101.                                       /* returned by TT_Load_Glyph() are  */
  102.                                       /* expressed in font units if       */
  103.                                       /* scaling wasn't requested, and    */
  104.                                       /* in 26.6 fractional pixels if it  */
  105.                                       /* was.                             */
  106.  
  107.  
  108.   struct  TT_UnitVector_      /* guess what...  */
  109.   {
  110.     TT_F2Dot14  x;
  111.     TT_F2Dot14  y;
  112.   };
  113.  
  114.   typedef struct TT_UnitVector_  TT_UnitVector;
  115.  
  116.  
  117.   struct  TT_Vector_          /* simple vector type */
  118.   {
  119.     TT_F26Dot6  x;
  120.     TT_F26Dot6  y;
  121.   };
  122.  
  123.   typedef struct TT_Vector_  TT_Vector;
  124.  
  125.  
  126.   /* A simple 2x2 matrix used for transformations. */
  127.   /* You should use 16.16 fixed floats.            */
  128.   /*                                               */
  129.   /*   x' = xx*x + xy*y                            */
  130.   /*   y' = yx*x + yy*y                            */
  131.   /*                                               */
  132.  
  133.   struct  TT_Matrix_
  134.   {
  135.     TT_Fixed  xx, xy;
  136.     TT_Fixed  yx, yy;
  137.   };
  138.  
  139.   typedef struct TT_Matrix_  TT_Matrix;
  140.  
  141.  
  142.   /* A structure used to describe the source glyph to the renderer. */
  143.  
  144.   struct  TT_Outline_
  145.   {
  146.     TT_Short         n_contours;   /* number of contours in glyph   */
  147.     TT_UShort        n_points;     /* number of points in the glyph */
  148.  
  149.     TT_Vector*       points;       /* the outline's points   */
  150.     TT_Byte*         flags;        /* the points flags       */
  151.     TT_UShort*       contours;     /* the contour end points */
  152.  
  153.     /* The following flag indicates that the outline owns the arrays it  */
  154.     /* refers to.  Typically, this is true of outlines created from the  */
  155.     /* TT_New_Outline() API, while it isn't for those returned by        */
  156.     /* TT_Get_Glyph_Outline().                                           */
  157.  
  158.     TT_Bool          owner;      /* The outline owns the coordinates, */
  159.                                  /* flags and contours array it uses. */
  160.  
  161.     /* The following flags are set automatically by                      */
  162.     /* TT_Get_Glyph_Outline().  Their meaning is the following:          */
  163.     /*                                                                   */
  164.     /*  high_precision   If true, the scan-line converter will use a     */
  165.     /*                   higher precision to render bitmaps (i.e., a     */
  166.     /*                   1/1024 pixel precision).  This is important for */
  167.     /*                   small ppem sizes.                               */
  168.     /*                                                                   */
  169.     /*  second_pass      If true, the scan-line converter performs a     */
  170.     /*                   second sweep phase dedicated to find vertical   */
  171.     /*                   drop-outs.  If false, only horizontal drop-outs */
  172.     /*                   will be checked during the first vertical       */
  173.     /*                   sweep (yes, this is a bit confusing but it is   */
  174.     /*                   really the way it should work).  This is        */
  175.     /*                   important for small ppems too.                  */
  176.     /*                                                                   */
  177.     /*  dropout_mode     Specifies the TrueType drop-out mode to use for */
  178.     /*                   continuity checking.  Valid values are 0 (no    */
  179.     /*                   check), 1, 2, 4, and 5.                         */
  180.     /*                                                                   */
  181.     /*  Most of the engine's users will safely ignore these fields...    */
  182.  
  183.     TT_Bool          high_precision;  /* high precision rendering */
  184.     TT_Bool          second_pass;     /* two sweeps rendering     */
  185.     TT_Char          dropout_mode;    /* dropout mode             */
  186.   };
  187.  
  188.   typedef struct TT_Outline_  TT_Outline;
  189.  
  190.  
  191.   /* A structure used to describe a simple bounding box. */
  192.  
  193.   struct TT_BBox_
  194.   {
  195.     TT_Pos  xMin;
  196.     TT_Pos  yMin;
  197.     TT_Pos  xMax;
  198.     TT_Pos  yMax;
  199.   };
  200.  
  201.   typedef struct TT_BBox_  TT_BBox;
  202.  
  203.  
  204.   /* A structure used to return glyph metrics.                          */
  205.   /*                                                                    */
  206.   /* The `bearingX' isn't called `left-side bearing' anymore because    */
  207.   /* it has different meanings depending on the glyph's orientation.    */
  208.   /*                                                                    */
  209.   /* The same is true for `bearingY', which is the top-side bearing     */
  210.   /* defined by the TT_Spec, i.e., the distance from the baseline to    */
  211.   /* the top of the glyph's bbox.  According to our current convention, */
  212.   /* this is always the same as `bbox.yMax' but we make it appear for   */
  213.   /* consistency in its proper field.                                   */
  214.   /*                                                                    */
  215.   /* The `advance' field is the advance width for horizontal layout,    */
  216.   /* and advance height for vertical layouts.                           */
  217.  
  218.   struct  TT_Glyph_Metrics_
  219.   {
  220.     TT_BBox  bbox;      /* glyph bounding box */
  221.  
  222.     TT_Pos   bearingX;  /* left-side bearing                    */
  223.     TT_Pos   bearingY;  /* top-side bearing, per se the TT spec */
  224.  
  225.     TT_Pos   advance;   /* advance width (or height) */
  226.   };
  227.  
  228.   typedef struct TT_Glyph_Metrics_  TT_Glyph_Metrics;
  229.  
  230.  
  231.   /* A structure used to return horizontal _and_ vertical glyph         */
  232.   /* metrics.                                                           */
  233.   /*                                                                    */
  234.   /* A glyph can be used either in a horizontal or vertical layout.     */
  235.   /* Its glyph metrics vary with orientation.  The TT_Big_Glyph_Metrics */
  236.   /* structure is used to return _all_ metrics in one call.             */
  237.  
  238.   struct TT_Big_Glyph_Metrics_
  239.   {
  240.     TT_BBox  bbox;          /* glyph bounding box */
  241.  
  242.     TT_Pos   horiBearingX;  /* left side bearing in horizontal layouts */
  243.     TT_Pos   horiBearingY;  /* top side bearing in horizontal layouts  */
  244.  
  245.     TT_Pos   vertBearingX;  /* left side bearing in vertical layouts */
  246.     TT_Pos   vertBearingY;  /* top side bearing in vertical layouts  */
  247.  
  248.     TT_Pos   horiAdvance;   /* advance width for horizontal layout */
  249.     TT_Pos   vertAdvance;   /* advance height for vertical layout  */
  250.  
  251.     /* The following fields represent unhinted scaled metrics values. */
  252.     /* They can be useful for applications needing to do some device  */
  253.     /* independent placement of glyphs.                               */
  254.     /*                                                                */
  255.     /* Applying these metrics to hinted glyphs will most surely ruin  */
  256.     /* the grid fitting performed by the bytecode interpreter.  These */
  257.     /* values are better used to compute accumulated positioning      */
  258.     /* distances.                                                     */
  259.  
  260.     TT_Pos   linearHoriBearingX;  /* linearly scaled horizontal lsb     */
  261.     TT_Pos   linearHoriAdvance;   /* linearly scaled horizontal advance */
  262.  
  263.     TT_Pos   linearVertBearingY;  /* linearly scaled vertical tsb     */
  264.     TT_Pos   linearVertAdvance;   /* linearly scaled vertical advance */
  265.   };
  266.  
  267.   typedef struct TT_Big_Glyph_Metrics_  TT_Big_Glyph_Metrics;
  268.  
  269.  
  270.   /* A structure used to return instance metrics. */
  271.  
  272.   struct  TT_Instance_Metrics_
  273.   {
  274.     TT_F26Dot6  pointSize;     /* char. size in points (1pt = 1/72 inch) */
  275.  
  276.     TT_UShort   x_ppem;        /* horizontal pixels per EM square */
  277.     TT_UShort   y_ppem;        /* vertical pixels per EM square   */
  278.  
  279.     TT_Fixed    x_scale;     /* 16.16 to convert from EM units to 26.6 pix */
  280.     TT_Fixed    y_scale;     /* 16.16 to convert from EM units to 26.6 pix */
  281.  
  282.     TT_UShort   x_resolution;  /* device horizontal resolution in dpi */
  283.     TT_UShort   y_resolution;  /* device vertical resolution in dpi   */
  284.   };
  285.  
  286.   typedef struct TT_Instance_Metrics_  TT_Instance_Metrics;
  287.  
  288.  
  289.   /* Flow constants:                                             */
  290.   /*                                                             */
  291.   /* The flow of a bitmap refers to the way lines are oriented   */
  292.   /* within the bitmap data, i.e., the orientation of the Y      */
  293.   /* coordinate axis.                                            */
  294.   /*                                                             */
  295.   /* For example, if the first bytes of the bitmap pertain to    */
  296.   /* its top-most line, then the flow is `down'.  If these bytes */
  297.   /* pertain to its lowest line, the the flow is `up'.           */
  298.  
  299. #define TT_Flow_Down  -1  /* bitmap is oriented from top to bottom */
  300. #define TT_Flow_Up     1  /* bitmap is oriented from bottom to top */
  301. #define TT_Flow_Error  0  /* an error occurred during rendering    */
  302.  
  303.  
  304.   /* A structure used to describe the target bitmap or pixmap to the   */
  305.   /* renderer.  Note that there is nothing in this structure that      */
  306.   /* gives the nature of the buffer.                                   */
  307.   /*                                                                   */
  308.   /* IMPORTANT NOTE:                                                   */
  309.   /*                                                                   */
  310.   /*   In the case of a pixmap, the `width' and `cols' fields must     */
  311.   /*   have the _same_ values, and _must_ be padded to 32-bits, i.e.,  */
  312.   /*   be a multiple of 4.  Clipping problems will arise otherwise,    */
  313.   /*   if not even page faults!                                        */
  314.   /*                                                                   */
  315.   /*   The typical settings are:                                       */
  316.   /*                                                                   */
  317.   /*   - for a WxH bitmap:                                             */
  318.   /*                                                                   */
  319.   /*       rows  = H                                                   */
  320.   /*       cols  = (W+7) / 8                                           */
  321.   /*       width = W                                                   */
  322.   /*       flow  = your_choice                                         */
  323.   /*                                                                   */
  324.   /*   - for a WxH pixmap:                                             */
  325.   /*                                                                   */
  326.   /*       rows  = H                                                   */
  327.   /*       cols  = (W+3) & ~3                                          */
  328.   /*       width = cols                                                */
  329.   /*       flow  = your_choice                                         */
  330.  
  331.   struct  TT_Raster_Map_
  332.   {
  333.     int    rows;    /* number of rows                    */
  334.     int    cols;    /* number of columns (bytes) per row */
  335.     int    width;   /* number of pixels per line         */
  336.     int    flow;    /* bitmap orientation                */
  337.  
  338.     void*  bitmap;  /* bit/pixmap buffer                 */
  339.     long   size;    /* bit/pixmap size in bytes          */
  340.   };
  341.  
  342.   typedef struct TT_Raster_Map_  TT_Raster_Map;
  343.  
  344.  
  345.   /* ------ The font header TrueType table structure ------ */
  346.  
  347.   struct  TT_Header_
  348.   {
  349.     TT_Fixed   Table_Version;
  350.     TT_Fixed   Font_Revision;
  351.  
  352.     TT_Long    CheckSum_Adjust;
  353.     TT_Long    Magic_Number;
  354.  
  355.     TT_UShort  Flags;
  356.     TT_UShort  Units_Per_EM;
  357.  
  358.     TT_Long    Created [2];
  359.     TT_Long    Modified[2];
  360.  
  361.     TT_FWord   xMin;
  362.     TT_FWord   yMin;
  363.     TT_FWord   xMax;
  364.     TT_FWord   yMax;
  365.  
  366.     TT_UShort  Mac_Style;
  367.     TT_UShort  Lowest_Rec_PPEM;
  368.  
  369.     TT_Short   Font_Direction;
  370.     TT_Short   Index_To_Loc_Format;
  371.     TT_Short   Glyph_Data_Format;
  372.   };
  373.  
  374.   typedef struct TT_Header_  TT_Header;
  375.  
  376.  
  377.   /* ------ The horizontal header TrueType table structure ------ */
  378.  
  379.   /*******************************************************/
  380.   /*  This structure is the one defined by the TrueType  */
  381.   /*  specification, plus two fields used to link the    */
  382.   /*  font-units metrics to the header.                  */
  383.  
  384.   struct  TT_Horizontal_Header_
  385.   {
  386.     TT_Fixed   Version;
  387.     TT_FWord   Ascender;
  388.     TT_FWord   Descender;
  389.     TT_FWord   Line_Gap;
  390.  
  391.     TT_UFWord  advance_Width_Max;      /* advance width maximum */
  392.  
  393.     TT_FWord   min_Left_Side_Bearing;  /* minimum left-sb       */
  394.     TT_FWord   min_Right_Side_Bearing; /* minimum right-sb      */
  395.     TT_FWord   xMax_Extent;            /* xmax extents          */
  396.     TT_FWord   caret_Slope_Rise;
  397.     TT_FWord   caret_Slope_Run;
  398.  
  399.     TT_Short   Reserved0,
  400.                Reserved1,
  401.                Reserved2,
  402.                Reserved3,
  403.                Reserved4;
  404.  
  405.     TT_Short   metric_Data_Format;
  406.     TT_UShort  number_Of_HMetrics;
  407.  
  408.     /* The following fields are not defined by the TrueType specification */
  409.     /* but they're used to connect the metrics header to the relevant     */
  410.     /* `HMTX' or `VMTX' table.                                            */
  411.  
  412.     void*      long_metrics;
  413.     void*      short_metrics;
  414.   };
  415.  
  416.   typedef struct TT_Horizontal_Header_  TT_Horizontal_Header;
  417.  
  418.  
  419.   /*******************************************************/
  420.   /*  This structure is the one defined by the TrueType  */
  421.   /*  specification.  Note that it has exactly the same  */
  422.   /*  layout as the horizontal header (both are loaded   */
  423.   /*  by the same function).                             */
  424.  
  425.   struct  TT_Vertical_Header_
  426.   {
  427.     TT_Fixed   Version;
  428.     TT_FWord   Ascender;
  429.     TT_FWord   Descender;
  430.     TT_FWord   Line_Gap;
  431.  
  432.     TT_UFWord  advance_Height_Max;      /* advance height maximum */
  433.  
  434.     TT_FWord   min_Top_Side_Bearing;    /* minimum left-sb or top-sb       */
  435.     TT_FWord   min_Bottom_Side_Bearing; /* minimum right-sb or bottom-sb   */
  436.     TT_FWord   yMax_Extent;             /* xmax or ymax extents            */
  437.     TT_FWord   caret_Slope_Rise;
  438.     TT_FWord   caret_Slope_Run;
  439.     TT_FWord   caret_Offset;
  440.  
  441.     TT_Short   Reserved1,
  442.                Reserved2,
  443.                Reserved3,
  444.                Reserved4;
  445.  
  446.     TT_Short   metric_Data_Format;
  447.     TT_UShort  number_Of_VMetrics;
  448.  
  449.     /* The following fields are not defined by the TrueType specification */
  450.     /* but they're used to connect the metrics header to the relevant     */
  451.     /* `HMTX' or `VMTX' table.                                            */
  452.  
  453.     void*      long_metrics;
  454.     void*      short_metrics;
  455.   };
  456.  
  457.   typedef struct TT_Vertical_Header_  TT_Vertical_Header;
  458.  
  459.  
  460.   /* ------ The OS/2 table ------ */
  461.  
  462.   /************************************************************************/
  463.   /* Note that since FreeType 1.3, we support Mac fonts which do not have */
  464.   /* an OS/2 table.  In this case the `version' field will be set to      */
  465.   /* 0xFFFF by the table loader; all other fields should be 0.            */
  466.  
  467.   struct  TT_OS2_
  468.   {
  469.     TT_UShort  version;                /* 0x0001 */
  470.     TT_FWord   xAvgCharWidth;
  471.     TT_UShort  usWeightClass;
  472.     TT_UShort  usWidthClass;
  473.     TT_Short   fsType;
  474.     TT_FWord   ySubscriptXSize;
  475.     TT_FWord   ySubscriptYSize;
  476.     TT_FWord   ySubscriptXOffset;
  477.     TT_FWord   ySubscriptYOffset;
  478.     TT_FWord   ySuperscriptXSize;
  479.     TT_FWord   ySuperscriptYSize;
  480.     TT_FWord   ySuperscriptXOffset;
  481.     TT_FWord   ySuperscriptYOffset;
  482.     TT_FWord   yStrikeoutSize;
  483.     TT_FWord   yStrikeoutPosition;
  484.     TT_Short   sFamilyClass;
  485.  
  486.     TT_Byte    panose[10];
  487.  
  488.     TT_ULong   ulUnicodeRange1;        /* Bits 0-31   */
  489.     TT_ULong   ulUnicodeRange2;        /* Bits 32-63  */
  490.     TT_ULong   ulUnicodeRange3;        /* Bits 64-95  */
  491.     TT_ULong   ulUnicodeRange4;        /* Bits 96-127 */
  492.  
  493.     TT_Char    achVendID[4];
  494.  
  495.     TT_UShort  fsSelection;
  496.     TT_UShort  usFirstCharIndex;
  497.     TT_UShort  usLastCharIndex;
  498.     TT_Short   sTypoAscender;
  499.     TT_Short   sTypoDescender;
  500.     TT_Short   sTypoLineGap;
  501.     TT_UShort  usWinAscent;
  502.     TT_UShort  usWinDescent;
  503.  
  504.     /* only version 1 tables: */
  505.  
  506.     TT_ULong   ulCodePageRange1;       /* Bits 0-31   */
  507.     TT_ULong   ulCodePageRange2;       /* Bits 32-63  */
  508.   };
  509.  
  510.   typedef struct TT_OS2_  TT_OS2;
  511.  
  512.  
  513.   /* ------ The PostScript table ------ */
  514.  
  515.   struct  TT_Postscript_
  516.   {
  517.     TT_Fixed  FormatType;
  518.     TT_Fixed  italicAngle;
  519.     TT_FWord  underlinePosition;
  520.     TT_FWord  underlineThickness;
  521.     TT_ULong  isFixedPitch;
  522.     TT_ULong  minMemType42;
  523.     TT_ULong  maxMemType42;
  524.     TT_ULong  minMemType1;
  525.     TT_ULong  maxMemType1;
  526.  
  527.     /* Glyph names follow in the file, but we don't         */
  528.     /* load them by default.  See the ftxpost.c extension.  */
  529.   };
  530.  
  531.   typedef struct TT_Postscript_  TT_Postscript;
  532.  
  533.  
  534.   /* ------ The horizontal device metrics table (`hdmx') ------ */
  535.  
  536.   struct  TT_Hdmx_Record_
  537.   {
  538.     TT_Byte   ppem;
  539.     TT_Byte   max_width;
  540.     TT_Byte*  widths;
  541.   };
  542.  
  543.   typedef struct TT_Hdmx_Record_  TT_Hdmx_Record;
  544.  
  545.  
  546.   struct  TT_Hdmx_
  547.   {
  548.     TT_UShort        version;
  549.     TT_Short         num_records;
  550.     TT_Hdmx_Record*  records;
  551.   };
  552.  
  553.   typedef struct TT_Hdmx_  TT_Hdmx;
  554.  
  555.  
  556.   /* A structure used to describe face properties. */
  557.  
  558.   struct  TT_Face_Properties_
  559.   {
  560.     TT_UShort  num_Glyphs;      /* number of glyphs in face              */
  561.     TT_UShort  max_Points;      /* maximum number of points in a glyph   */
  562.     TT_UShort  max_Contours;    /* maximum number of contours in a glyph */
  563.  
  564.     TT_UShort  num_CharMaps;    /* number of charmaps in the face     */
  565.     TT_UShort  num_Names;       /* number of name records in the face */
  566.  
  567.     TT_ULong   num_Faces;  /* 1 for normal TrueType files, and the  */
  568.                            /* number of embedded faces for TrueType */
  569.                            /* collections                           */
  570.  
  571.     TT_Header*             header;        /* TrueType header table          */
  572.     TT_Horizontal_Header*  horizontal;    /* TrueType horizontal header     */
  573.     TT_OS2*                os2;           /* TrueType OS/2 table            */
  574.     TT_Postscript*         postscript;    /* TrueType Postscript table      */
  575.     TT_Hdmx*               hdmx;          /* TrueType hor. dev. metr. table */
  576.     TT_Vertical_Header*    vertical;      /* TT Vertical header, if present */
  577.   };
  578.  
  579.   typedef struct TT_Face_Properties_  TT_Face_Properties;
  580.  
  581.  
  582.   /* Here are the definitions of the handle types used for FreeType's */
  583.   /* most common objects accessed by the client application.  We use  */
  584.   /* a simple trick:                                                  */
  585.   /*                                                                  */
  586.   /*   Each handle type is a structure that only contains one         */
  587.   /*   pointer.  The advantage of structures is that they are         */
  588.   /*   mutually exclusive types.  We could have defined the           */
  589.   /*   following types:                                               */
  590.   /*                                                                  */
  591.   /*     typedef void*  TT_Stream;                                    */
  592.   /*     typedef void*  TT_Face;                                      */
  593.   /*     typedef void*  TT_Instance;                                  */
  594.   /*     typedef void*  TT_Glyph;                                     */
  595.   /*     typedef void*  TT_CharMap;                                   */
  596.   /*                                                                  */
  597.   /*   but these would have allowed lines like:                       */
  598.   /*                                                                  */
  599.   /*      stream = instance;                                          */
  600.   /*                                                                  */
  601.   /*   in the client code this would be a severe bug, unnoticed       */
  602.   /*   by the compiler!                                               */
  603.   /*                                                                  */
  604.   /*   Thus, we enforce type checking with a simple language          */
  605.   /*   trick...                                                       */
  606.   /*                                                                  */
  607.   /*   NOTE:  Some macros are defined in tttypes.h to perform         */
  608.   /*          automatic type conversions for library hackers...       */
  609.  
  610.   struct TT_Engine_   { void*  z; };
  611.   struct TT_Stream_   { void*  z; };
  612.   struct TT_Face_     { void*  z; };
  613.   struct TT_Instance_ { void*  z; };
  614.   struct TT_Glyph_    { void*  z; };
  615.   struct TT_CharMap_  { void*  z; };
  616.  
  617.   typedef struct TT_Engine_    TT_Engine;    /* engine instance           */
  618.   typedef struct TT_Stream_    TT_Stream;    /* stream handle type        */
  619.   typedef struct TT_Face_      TT_Face;      /* face handle type          */
  620.   typedef struct TT_Instance_  TT_Instance;  /* instance handle type      */
  621.   typedef struct TT_Glyph_     TT_Glyph;     /* glyph handle type         */
  622.   typedef struct TT_CharMap_   TT_CharMap;   /* character map handle type */
  623.  
  624.  
  625.   /* Almost all functions return an error code of this type. */
  626.  
  627.   typedef long  TT_Error;
  628.  
  629.  
  630.   /*******************************************************************/
  631.   /*                                                                 */
  632.   /*  FreeType API                                                   */
  633.   /*                                                                 */
  634.   /*  All these begin with a `TT_' prefix.                           */
  635.   /*                                                                 */
  636.   /*  Most of them are implemented in the `ttapi.c' source file.     */
  637.   /*                                                                 */
  638.   /*******************************************************************/
  639.  
  640.   /* Get version information. */
  641.  
  642.   EXPORT_DEF
  643.   TT_Error  TT_FreeType_Version( int  *major,
  644.                                  int  *minor );
  645.  
  646.  
  647.   /* Initialize the engine. */
  648.  
  649.   EXPORT_DEF
  650.   TT_Error  TT_Init_FreeType( TT_Engine*  engine );
  651.  
  652.  
  653.   /* Finalize the engine, and release all allocated objects. */
  654.  
  655.   EXPORT_DEF
  656.   TT_Error  TT_Done_FreeType( TT_Engine  engine );
  657.  
  658.  
  659.   /* Set the gray level palette.  This is an array of 5 bytes used */
  660.   /* to produce the font smoothed pixmaps.  By convention:         */
  661.   /*                                                               */
  662.   /*  palette[0] = background (white)                              */
  663.   /*  palette[1] = light                                           */
  664.   /*  palette[2] = medium                                          */
  665.   /*  palette[3] = dark                                            */
  666.   /*  palette[4] = foreground (black)                              */
  667.   /*                                                               */
  668.  
  669.   EXPORT_DEF
  670.   TT_Error  TT_Set_Raster_Gray_Palette( TT_Engine  engine,
  671.                                         TT_Byte*   palette );
  672.  
  673.  
  674.   /* ----------------------- face management ----------------------- */
  675.  
  676.   /* Open a new TrueType font file, and returns a handle for  */
  677.   /* it in variable '*face'.                                  */
  678.   /*                                                          */
  679.   /* Note: The file can be either a TrueType file (*.ttf) or  */
  680.   /*       a TrueType collection (*.ttc, in this case, only   */
  681.   /*       the first face is opened).  The number of faces in */
  682.   /*       the same collection can be obtained in the face's  */
  683.   /*       properties, using TT_Get_Face_Properties() and the */
  684.   /*       `max_Faces' field.                                 */
  685.  
  686.   EXPORT_DEF
  687.   TT_Error  TT_Open_Face( TT_Engine       engine,
  688.                           const TT_Text*  fontPathName,
  689.                           TT_Face*        face );
  690.  
  691.  
  692.   /* Open a TrueType font file located inside a collection. */
  693.   /* The font is assigned by its index in `fontIndex'.      */
  694.  
  695.   EXPORT_DEF
  696.   TT_Error  TT_Open_Collection( TT_Engine       engine,
  697.                                 const TT_Text*  collectionPathName,
  698.                                 TT_ULong        fontIndex,
  699.                                 TT_Face*        face );
  700.  
  701.  
  702.   /* Return face properties in the `properties' structure.          */
  703.   /*                                                                */
  704.   /* Note that since version 1.3, we support font files with no     */
  705.   /* OS/2 table (mainly old Mac fonts).  In this case, the OS/2     */
  706.   /* `version' field will be set to 0xFFFF, and all other fields    */
  707.   /* will be zeroed.                                                */
  708.  
  709.   EXPORT_DEF
  710.   TT_Error  TT_Get_Face_Properties( TT_Face              face,
  711.                                     TT_Face_Properties*  properties );
  712.  
  713.  
  714.   /* Set a face object's generic pointer */
  715.  
  716.   EXPORT_DEF
  717.   TT_Error  TT_Set_Face_Pointer( TT_Face  face,
  718.                                  void*    data );
  719.  
  720.  
  721.   /* Get a face object's generic pointer */
  722.  
  723.   EXPORT_DEF
  724.   void*  TT_Get_Face_Pointer( TT_Face  face );
  725.  
  726.  
  727.   /* Close a face's file handle to save system resources.  The file */
  728.   /* will be re-opened automatically on the next disk access.       */
  729.  
  730.   EXPORT_DEF
  731.   TT_Error  TT_Flush_Face( TT_Face  face );
  732.  
  733.   /* Get a face's glyph metrics expressed in font units.  Returns any    */
  734.   /* number of arrays.  Set the fields to NULL if you are not interested */
  735.   /* by a given array.                                                   */
  736.  
  737.   EXPORT_DEF
  738.   TT_Error  TT_Get_Face_Metrics( TT_Face     face,
  739.                                  TT_UShort   firstGlyph,
  740.                                  TT_UShort   lastGlyph,
  741.                                  TT_Short*   leftBearings,
  742.                                  TT_UShort*  widths,
  743.                                  TT_Short*   topBearings,
  744.                                  TT_UShort*  heights );
  745.  
  746.  
  747.   /* Close a given font object, destroying all associated */
  748.   /* instances.                                           */
  749.  
  750.   EXPORT_DEF
  751.   TT_Error  TT_Close_Face( TT_Face  face );
  752.  
  753.  
  754.   /* Get font or table data. */
  755.  
  756.   EXPORT_DEF
  757.   TT_Error  TT_Get_Font_Data( TT_Face   face,
  758.                               TT_ULong  tag,
  759.                               TT_Long   offset,
  760.                               void*     buffer,
  761.                               TT_Long*  length );
  762.  
  763.  
  764. /* A simple macro to build table tags from ASCII chars */
  765.  
  766. #define MAKE_TT_TAG( _x1, _x2, _x3, _x4 ) \
  767.           (((TT_ULong)_x1 << 24) |        \
  768.            ((TT_ULong)_x2 << 16) |        \
  769.            ((TT_ULong)_x3 << 8)  |        \
  770.             (TT_ULong)_x4)
  771.  
  772.  
  773.  
  774.   /* ----------------------- instance management -------------------- */
  775.  
  776.   /* Open a new font instance and returns an instance handle */
  777.   /* for it in `*instance'.                                  */
  778.  
  779.   EXPORT_DEF
  780.   TT_Error  TT_New_Instance( TT_Face       face,
  781.                              TT_Instance*  instance );
  782.  
  783.  
  784.   /* Set device resolution for a given instance.  The values are      */
  785.   /* given in dpi (Dots Per Inch).  Default is 96 in both directions. */
  786.  
  787.   EXPORT_DEF
  788.   TT_Error  TT_Set_Instance_Resolutions( TT_Instance  instance,
  789.                                          TT_UShort    xResolution,
  790.                                          TT_UShort    yResolution );
  791.  
  792.  
  793.   /* Set the pointsize for a given instance.  Default is 10pt. */
  794.  
  795.   EXPORT_DEF
  796.   TT_Error  TT_Set_Instance_CharSize( TT_Instance  instance,
  797.                                       TT_F26Dot6   charSize );
  798.  
  799.   EXPORT_DEF
  800.   TT_Error  TT_Set_Instance_CharSizes( TT_Instance  instance,
  801.                                        TT_F26Dot6   charWidth,
  802.                                        TT_F26Dot6   charHeight );
  803.  
  804. #define TT_Set_Instance_PointSize( ins, ptsize )   \
  805.             TT_Set_Instance_CharSize( ins, ptsize*64L )
  806.  
  807.   EXPORT_DEF
  808.   TT_Error  TT_Set_Instance_PixelSizes( TT_Instance  instance,
  809.                                         TT_UShort    pixelWidth,
  810.                                         TT_UShort    pixelHeight,
  811.                                         TT_F26Dot6   pointSize );
  812.  
  813.  
  814.   /* This function has been deprecated!  Do not use it, as it      */
  815.   /* doesn't work reliably.  You can perfectly control hinting     */
  816.   /* yourself when loading glyphs, then apply transforms as usual. */
  817.  
  818.   EXPORT_DEF
  819.   TT_Error  TT_Set_Instance_Transform_Flags( TT_Instance  instance,
  820.                                              TT_Bool      rotated,
  821.                                              TT_Bool      stretched );
  822.  
  823.  
  824.   /* Return instance metrics in `metrics'. */
  825.  
  826.   EXPORT_DEF
  827.   TT_Error  TT_Get_Instance_Metrics( TT_Instance           instance,
  828.                                      TT_Instance_Metrics*  metrics );
  829.  
  830.  
  831.   /* Set an instance's generic pointer. */
  832.  
  833.   EXPORT_DEF
  834.   TT_Error  TT_Set_Instance_Pointer( TT_Instance  instance,
  835.                                      void*        data );
  836.  
  837.  
  838.   /* Get an instance's generic pointer. */
  839.  
  840.   EXPORT_DEF
  841.   void*     TT_Get_Instance_Pointer( TT_Instance  instance );
  842.  
  843.  
  844.   /* Close a given instance object, destroying all associated data. */
  845.  
  846.   EXPORT_DEF
  847.   TT_Error  TT_Done_Instance( TT_Instance  instance );
  848.  
  849.  
  850.  
  851.   /* ----------------------- glyph management ----------------------- */
  852.  
  853.   /* Create a new glyph object related to the given `face'. */
  854.  
  855.   EXPORT_DEF
  856.   TT_Error  TT_New_Glyph( TT_Face    face,
  857.                           TT_Glyph*  glyph );
  858.  
  859.  
  860.   /* Discard (and destroy) a given glyph object. */
  861.  
  862.   EXPORT_DEF
  863.   TT_Error  TT_Done_Glyph( TT_Glyph  glyph );
  864.  
  865.  
  866. #define TTLOAD_SCALE_GLYPH                    1
  867. #define TTLOAD_HINT_GLYPH                     2
  868. #define TTLOAD_PEDANTIC                     128
  869. #define TTLOAD_IGNORE_GLOBAL_ADVANCE_WIDTH  256
  870.  
  871. #define TTLOAD_DEFAULT  (TTLOAD_SCALE_GLYPH | TTLOAD_HINT_GLYPH)
  872.  
  873.  
  874.   /* Load and process (scale/transform and hint) a glyph from the */
  875.   /* given `instance'.  The glyph and instance handles must be    */
  876.   /* related to the same face object.  The glyph index can be     */
  877.   /* computed with a call to TT_Char_Index().                     */
  878.   /*                                                              */
  879.   /* The 'load_flags' argument is a combination of the macros     */
  880.   /* TTLOAD_SCALE_GLYPH and TTLOAD_HINT_GLYPH.  Hinting will be   */
  881.   /* applied only if the scaling is selected.                     */
  882.   /*                                                              */
  883.   /* If scaling is off (i.e., load_flags = 0), the returned       */
  884.   /* outlines are in EM square coordinates (also called FUnits),  */
  885.   /* extracted directly from the font with no hinting.  Other     */
  886.   /* glyph metrics are also in FUnits.                            */
  887.   /*                                                              */
  888.   /* If scaling is on, the returned outlines are in fractional    */
  889.   /* pixel units (i.e. TT_F26Dot6 = 26.6 fixed floats).           */
  890.   /*                                                              */
  891.   /* NOTE: The glyph index must be in the range 0..num_glyphs-1,  */
  892.   /*       where `num_glyphs' is the total number of glyphs in    */
  893.   /*       the font file (given in the face properties).          */
  894.  
  895.   EXPORT_DEF
  896.   TT_Error  TT_Load_Glyph( TT_Instance  instance,
  897.                            TT_Glyph     glyph,
  898.                            TT_UShort    glyphIndex,
  899.                            TT_UShort    loadFlags );
  900.  
  901.  
  902.   /* Return glyph outline pointers in `outline'.  Note that the returned */
  903.   /* pointers are owned by the glyph object, and will be destroyed with  */
  904.   /* it.  The client application should _not_ change the pointers.       */
  905.  
  906.   EXPORT_DEF
  907.   TT_Error  TT_Get_Glyph_Outline( TT_Glyph     glyph,
  908.                                   TT_Outline*  outline );
  909.  
  910.  
  911.   /* Copy the glyph metrics into `metrics'. */
  912.  
  913.   EXPORT_DEF
  914.   TT_Error  TT_Get_Glyph_Metrics( TT_Glyph           glyph,
  915.                                   TT_Glyph_Metrics*  metrics );
  916.  
  917.  
  918.   /* Copy the glyph's big metrics into `metrics'. */
  919.   /* Necessary to obtain vertical metrics.        */
  920.  
  921.   EXPORT_DEF
  922.   TT_Error  TT_Get_Glyph_Big_Metrics( TT_Glyph               glyph,
  923.                                       TT_Big_Glyph_Metrics*  metrics );
  924.  
  925.  
  926.   /* Render the glyph into a bitmap, with given position offsets.     */
  927.   /*                                                                  */
  928.   /* Note: Only use integer pixel offsets to preserve the fine        */
  929.   /*       hinting of the glyph and the `correct' anti-aliasing       */
  930.   /*       (where vertical and horizontal stems aren't grayed).  This */
  931.   /*       means that `xOffset' and `yOffset' must be multiples       */
  932.   /*       of 64!                                                     */
  933.  
  934.   EXPORT_DEF
  935.   TT_Error  TT_Get_Glyph_Bitmap( TT_Glyph        glyph,
  936.                                  TT_Raster_Map*  map,
  937.                                  TT_F26Dot6      xOffset,
  938.                                  TT_F26Dot6      yOffset );
  939.  
  940.  
  941.   /* Render the glyph into a pixmap, with given position offsets.     */
  942.   /*                                                                  */
  943.   /* Note: Only use integer pixel offsets to preserve the fine        */
  944.   /*       hinting of the glyph and the `correct' anti-aliasing       */
  945.   /*       (where vertical and horizontal stems aren't grayed).  This */
  946.   /*       means that `xOffset' and `yOffset' must be multiples       */
  947.   /*       of 64!                                                     */
  948.  
  949.   EXPORT_DEF
  950.   TT_Error  TT_Get_Glyph_Pixmap( TT_Glyph        glyph,
  951.                                  TT_Raster_Map*  map,
  952.                                  TT_F26Dot6      xOffset,
  953.                                  TT_F26Dot6      yOffset );
  954.  
  955.  
  956.  
  957.   /* ----------------------- outline support ------------------------ */
  958.  
  959.   /* Allocate a new outline.  Reserve space for `numPoints' and */
  960.   /* `numContours'.                                             */
  961.  
  962.   EXPORT_DEF
  963.   TT_Error  TT_New_Outline( TT_UShort    numPoints,
  964.                             TT_Short     numContours,
  965.                             TT_Outline*  outline );
  966.  
  967.  
  968.   /* Release an outline. */
  969.  
  970.   EXPORT_DEF
  971.   TT_Error  TT_Done_Outline( TT_Outline*  outline );
  972.  
  973.  
  974.   /* Copy an outline into another one. */
  975.  
  976.   EXPORT_DEF
  977.   TT_Error  TT_Copy_Outline( TT_Outline*  source,
  978.                              TT_Outline*  target );
  979.  
  980.  
  981.   /* Render an outline into a bitmap. */
  982.  
  983.   EXPORT_DEF
  984.   TT_Error  TT_Get_Outline_Bitmap( TT_Engine       engine,
  985.                                    TT_Outline*     outline,
  986.                                    TT_Raster_Map*  map );
  987.  
  988.  
  989.   /* Render an outline into a pixmap. */
  990.  
  991.   EXPORT_DEF
  992.   TT_Error  TT_Get_Outline_Pixmap( TT_Engine       engine,
  993.                                    TT_Outline*     outline,
  994.                                    TT_Raster_Map*  map );
  995.  
  996.  
  997.   /* Return an outline's bounding box -- this function is slow as it */
  998.   /* performs a complete scan-line process, without drawing, to get  */
  999.   /* the most accurate values.                                       */
  1000.  
  1001.   EXPORT_DEF
  1002.   TT_Error  TT_Get_Outline_BBox( TT_Outline*  outline,
  1003.                                  TT_BBox*     bbox );
  1004.  
  1005.  
  1006.   /* Apply a transformation to a glyph outline. */
  1007.  
  1008.   EXPORT_DEF
  1009.   void  TT_Transform_Outline( TT_Outline*  outline,
  1010.                               TT_Matrix*   matrix );
  1011.  
  1012.  
  1013.   /* Apply a translation to a glyph outline. */
  1014.  
  1015.   EXPORT_DEF
  1016.   void  TT_Translate_Outline( TT_Outline*  outline,
  1017.                               TT_F26Dot6   xOffset,
  1018.                               TT_F26Dot6   yOffset );
  1019.  
  1020.  
  1021.   /* Apply a transformation to a vector. */
  1022.  
  1023.   EXPORT_DEF
  1024.   void  TT_Transform_Vector( TT_F26Dot6*  x,
  1025.                              TT_F26Dot6*  y,
  1026.                              TT_Matrix*   matrix );
  1027.  
  1028.  
  1029.   /* Compute A*B/C with 64 bits intermediate precision. */
  1030.  
  1031.   EXPORT_DEF
  1032.   TT_Long  TT_MulDiv( TT_Long  A,
  1033.                       TT_Long  B,
  1034.                       TT_Long  C );
  1035.  
  1036.  
  1037.   /* Compute A*B/0x10000 with 64 bits intermediate precision. */
  1038.   /* Useful to multiply by a 16.16 fixed float value.         */
  1039.  
  1040.   EXPORT_DEF
  1041.   TT_Long  TT_MulFix( TT_Long  A,
  1042.                       TT_Long  B );
  1043.  
  1044.  
  1045.   /* ----------------- character mapping support --------------- */
  1046.  
  1047.   /* Return the number of character mappings found in this file. */
  1048.   /* Returns -1 in case of failure (invalid face handle).        */
  1049.   /*                                                             */
  1050.   /* DON'T USE THIS FUNCTION!  IT HAS BEEN DEPRECATED!           */
  1051.   /*                                                             */
  1052.   /* It is retained for backwards compatibility only and will    */
  1053.   /* fail on 16bit systems.                                      */
  1054.   /*                                                             */
  1055.   /* You can now get the charmap count in the `num_CharMaps'     */
  1056.   /* field of a face's properties.                               */
  1057.   /*                                                             */
  1058.  
  1059.   EXPORT_DEF
  1060.   int  TT_Get_CharMap_Count( TT_Face  face );
  1061.  
  1062.  
  1063.   /* Return the ID of charmap number `charmapIndex' of a given face */
  1064.   /* used to enumerate the charmaps present in a TrueType file.     */
  1065.  
  1066.   EXPORT_DEF
  1067.   TT_Error  TT_Get_CharMap_ID( TT_Face     face,
  1068.                                TT_UShort   charmapIndex,
  1069.                                TT_UShort*  platformID,
  1070.                                TT_UShort*  encodingID );
  1071.  
  1072.  
  1073.   /* Look up the character maps found in `face' and return a handle */
  1074.   /* for the one matching `platformID' and `platformEncodingID'     */
  1075.   /* (see the TrueType specs relating to the `cmap' table for       */
  1076.   /* information on these ID numbers).  Returns an error code.      */
  1077.   /* In case of failure, the handle is set to NULL and is invalid.  */
  1078.  
  1079.   EXPORT_DEF
  1080.   TT_Error  TT_Get_CharMap( TT_Face      face,
  1081.                             TT_UShort    charmapIndex,
  1082.                             TT_CharMap*  charMap );
  1083.  
  1084.  
  1085.   /* Translate a character code through a given character map   */
  1086.   /* and return the corresponding glyph index to be used in     */
  1087.   /* a TT_Load_Glyph() call.  This function returns 0 in case   */
  1088.   /* of failure.                                                */
  1089.  
  1090.   EXPORT_DEF
  1091.   TT_UShort  TT_Char_Index( TT_CharMap  charMap,
  1092.                             TT_UShort   charCode );
  1093.  
  1094.  
  1095.  
  1096.   /* --------------------- names table support ------------------- */
  1097.  
  1098.   /* Return the number of name strings found in the name table.  */
  1099.   /* Returns -1 in case of failure (invalid face handle).        */
  1100.   /*                                                             */
  1101.   /* DON'T USE THIS FUNCTION!  IT HAS BEEN DEPRECATED!           */
  1102.   /*                                                             */
  1103.   /* It is retained for backwards compatibility only and will    */
  1104.   /* fail on 16bit systems.                                      */
  1105.   /*                                                             */
  1106.   /* You can now get the number of name strings in a face with   */
  1107.   /* the `num_Names' field of its properties.                    */
  1108.  
  1109.   EXPORT_DEF
  1110.   int  TT_Get_Name_Count( TT_Face  face );
  1111.  
  1112.  
  1113.   /* Return the ID of the name number `nameIndex' of a given face */
  1114.   /* used to enumerate the charmaps present in a TrueType file.   */
  1115.  
  1116.   EXPORT_DEF
  1117.   TT_Error  TT_Get_Name_ID( TT_Face     face,
  1118.                             TT_UShort   nameIndex,
  1119.                             TT_UShort*  platformID,
  1120.                             TT_UShort*  encodingID,
  1121.                             TT_UShort*  languageID,
  1122.                             TT_UShort*  nameID );
  1123.  
  1124.  
  1125.   /* Return the address and length of the name number `nameIndex' */
  1126.   /* of a given face in the variables `stringPtr' resp. `length'. */
  1127.   /* The string is part of the face object and shouldn't be       */
  1128.   /* written to or released.                                      */
  1129.   /*                                                              */
  1130.   /* Note that for an invalid platform ID a null pointer will be  */
  1131.   /* returned.                                                    */
  1132.  
  1133.   EXPORT_DEF
  1134.   TT_Error  TT_Get_Name_String( TT_Face      face,
  1135.                                 TT_UShort    nameIndex,
  1136.                                 TT_String**  stringPtr,
  1137.                                 TT_UShort*   length );
  1138.  
  1139.  
  1140. #ifdef __cplusplus
  1141.   }
  1142. #endif
  1143.  
  1144. #endif /* FREETYPE_H */
  1145.  
  1146.  
  1147. /* END */
  1148.