Home | History | Annotate | Download | only in internal
      1 /***************************************************************************/
      2 /*                                                                         */
      3 /*  pshints.h                                                              */
      4 /*                                                                         */
      5 /*    Interface to Postscript-specific (Type 1 and Type 2) hints           */
      6 /*    recorders (specification only).  These are used to support native    */
      7 /*    T1/T2 hints in the `type1', `cid', and `cff' font drivers.           */
      8 /*                                                                         */
      9 /*  Copyright 2001, 2002, 2003, 2005, 2006, 2007, 2009 by                  */
     10 /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
     11 /*                                                                         */
     12 /*  This file is part of the FreeType project, and may only be used,       */
     13 /*  modified, and distributed under the terms of the FreeType project      */
     14 /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
     15 /*  this file you indicate that you have read the license and              */
     16 /*  understand and accept it fully.                                        */
     17 /*                                                                         */
     18 /***************************************************************************/
     19 
     20 
     21 #ifndef __PSHINTS_H__
     22 #define __PSHINTS_H__
     23 
     24 
     25 #include <ft2build.h>
     26 #include FT_FREETYPE_H
     27 #include FT_TYPE1_TABLES_H
     28 
     29 
     30 FT_BEGIN_HEADER
     31 
     32 
     33   /*************************************************************************/
     34   /*************************************************************************/
     35   /*****                                                               *****/
     36   /*****               INTERNAL REPRESENTATION OF GLOBALS              *****/
     37   /*****                                                               *****/
     38   /*************************************************************************/
     39   /*************************************************************************/
     40 
     41   typedef struct PSH_GlobalsRec_*  PSH_Globals;
     42 
     43   typedef FT_Error
     44   (*PSH_Globals_NewFunc)( FT_Memory     memory,
     45                           T1_Private*   private_dict,
     46                           PSH_Globals*  aglobals );
     47 
     48   typedef FT_Error
     49   (*PSH_Globals_SetScaleFunc)( PSH_Globals  globals,
     50                                FT_Fixed     x_scale,
     51                                FT_Fixed     y_scale,
     52                                FT_Fixed     x_delta,
     53                                FT_Fixed     y_delta );
     54 
     55   typedef void
     56   (*PSH_Globals_DestroyFunc)( PSH_Globals  globals );
     57 
     58 
     59   typedef struct  PSH_Globals_FuncsRec_
     60   {
     61     PSH_Globals_NewFunc       create;
     62     PSH_Globals_SetScaleFunc  set_scale;
     63     PSH_Globals_DestroyFunc   destroy;
     64 
     65   } PSH_Globals_FuncsRec, *PSH_Globals_Funcs;
     66 
     67 
     68   /*************************************************************************/
     69   /*************************************************************************/
     70   /*****                                                               *****/
     71   /*****                  PUBLIC TYPE 1 HINTS RECORDER                 *****/
     72   /*****                                                               *****/
     73   /*************************************************************************/
     74   /*************************************************************************/
     75 
     76   /*************************************************************************
     77    *
     78    * @type:
     79    *   T1_Hints
     80    *
     81    * @description:
     82    *   This is a handle to an opaque structure used to record glyph hints
     83    *   from a Type 1 character glyph character string.
     84    *
     85    *   The methods used to operate on this object are defined by the
     86    *   @T1_Hints_FuncsRec structure.  Recording glyph hints is normally
     87    *   achieved through the following scheme:
     88    *
     89    *   - Open a new hint recording session by calling the `open' method.
     90    *     This rewinds the recorder and prepare it for new input.
     91    *
     92    *   - For each hint found in the glyph charstring, call the corresponding
     93    *     method (`stem', `stem3', or `reset').  Note that these functions do
     94    *     not return an error code.
     95    *
     96    *   - Close the recording session by calling the `close' method.  It
     97    *     returns an error code if the hints were invalid or something
     98    *     strange happened (e.g., memory shortage).
     99    *
    100    *   The hints accumulated in the object can later be used by the
    101    *   PostScript hinter.
    102    *
    103    */
    104   typedef struct T1_HintsRec_*  T1_Hints;
    105 
    106 
    107   /*************************************************************************
    108    *
    109    * @type:
    110    *   T1_Hints_Funcs
    111    *
    112    * @description:
    113    *   A pointer to the @T1_Hints_FuncsRec structure that defines the API of
    114    *   a given @T1_Hints object.
    115    *
    116    */
    117   typedef const struct T1_Hints_FuncsRec_*  T1_Hints_Funcs;
    118 
    119 
    120   /*************************************************************************
    121    *
    122    * @functype:
    123    *   T1_Hints_OpenFunc
    124    *
    125    * @description:
    126    *   A method of the @T1_Hints class used to prepare it for a new Type 1
    127    *   hints recording session.
    128    *
    129    * @input:
    130    *   hints ::
    131    *     A handle to the Type 1 hints recorder.
    132    *
    133    * @note:
    134    *   You should always call the @T1_Hints_CloseFunc method in order to
    135    *   close an opened recording session.
    136    *
    137    */
    138   typedef void
    139   (*T1_Hints_OpenFunc)( T1_Hints  hints );
    140 
    141 
    142   /*************************************************************************
    143    *
    144    * @functype:
    145    *   T1_Hints_SetStemFunc
    146    *
    147    * @description:
    148    *   A method of the @T1_Hints class used to record a new horizontal or
    149    *   vertical stem.  This corresponds to the Type 1 `hstem' and `vstem'
    150    *   operators.
    151    *
    152    * @input:
    153    *   hints ::
    154    *     A handle to the Type 1 hints recorder.
    155    *
    156    *   dimension ::
    157    *     0 for horizontal stems (hstem), 1 for vertical ones (vstem).
    158    *
    159    *   coords ::
    160    *     Array of 2 coordinates in 16.16 format, used as (position,length)
    161    *     stem descriptor.
    162    *
    163    * @note:
    164    *   Use vertical coordinates (y) for horizontal stems (dim=0).  Use
    165    *   horizontal coordinates (x) for vertical stems (dim=1).
    166    *
    167    *   `coords[0]' is the absolute stem position (lowest coordinate);
    168    *   `coords[1]' is the length.
    169    *
    170    *   The length can be negative, in which case it must be either -20 or
    171    *   -21.  It is interpreted as a `ghost' stem, according to the Type 1
    172    *   specification.
    173    *
    174    *   If the length is -21 (corresponding to a bottom ghost stem), then
    175    *   the real stem position is `coords[0]+coords[1]'.
    176    *
    177    */
    178   typedef void
    179   (*T1_Hints_SetStemFunc)( T1_Hints   hints,
    180                            FT_UInt    dimension,
    181                            FT_Fixed*  coords );
    182 
    183 
    184   /*************************************************************************
    185    *
    186    * @functype:
    187    *   T1_Hints_SetStem3Func
    188    *
    189    * @description:
    190    *   A method of the @T1_Hints class used to record three
    191    *   counter-controlled horizontal or vertical stems at once.
    192    *
    193    * @input:
    194    *   hints ::
    195    *     A handle to the Type 1 hints recorder.
    196    *
    197    *   dimension ::
    198    *     0 for horizontal stems, 1 for vertical ones.
    199    *
    200    *   coords ::
    201    *     An array of 6 values in 16.16 format, holding 3 (position,length)
    202    *     pairs for the counter-controlled stems.
    203    *
    204    * @note:
    205    *   Use vertical coordinates (y) for horizontal stems (dim=0).  Use
    206    *   horizontal coordinates (x) for vertical stems (dim=1).
    207    *
    208    *   The lengths cannot be negative (ghost stems are never
    209    *   counter-controlled).
    210    *
    211    */
    212   typedef void
    213   (*T1_Hints_SetStem3Func)( T1_Hints   hints,
    214                             FT_UInt    dimension,
    215                             FT_Fixed*  coords );
    216 
    217 
    218   /*************************************************************************
    219    *
    220    * @functype:
    221    *   T1_Hints_ResetFunc
    222    *
    223    * @description:
    224    *   A method of the @T1_Hints class used to reset the stems hints in a
    225    *   recording session.
    226    *
    227    * @input:
    228    *   hints ::
    229    *     A handle to the Type 1 hints recorder.
    230    *
    231    *   end_point ::
    232    *     The index of the last point in the input glyph in which the
    233    *     previously defined hints apply.
    234    *
    235    */
    236   typedef void
    237   (*T1_Hints_ResetFunc)( T1_Hints  hints,
    238                          FT_UInt   end_point );
    239 
    240 
    241   /*************************************************************************
    242    *
    243    * @functype:
    244    *   T1_Hints_CloseFunc
    245    *
    246    * @description:
    247    *   A method of the @T1_Hints class used to close a hint recording
    248    *   session.
    249    *
    250    * @input:
    251    *   hints ::
    252    *     A handle to the Type 1 hints recorder.
    253    *
    254    *   end_point ::
    255    *     The index of the last point in the input glyph.
    256    *
    257    * @return:
    258    *   FreeType error code.  0 means success.
    259    *
    260    * @note:
    261    *   The error code is set to indicate that an error occurred during the
    262    *   recording session.
    263    *
    264    */
    265   typedef FT_Error
    266   (*T1_Hints_CloseFunc)( T1_Hints  hints,
    267                          FT_UInt   end_point );
    268 
    269 
    270   /*************************************************************************
    271    *
    272    * @functype:
    273    *   T1_Hints_ApplyFunc
    274    *
    275    * @description:
    276    *   A method of the @T1_Hints class used to apply hints to the
    277    *   corresponding glyph outline.  Must be called once all hints have been
    278    *   recorded.
    279    *
    280    * @input:
    281    *   hints ::
    282    *     A handle to the Type 1 hints recorder.
    283    *
    284    *   outline ::
    285    *     A pointer to the target outline descriptor.
    286    *
    287    *   globals ::
    288    *     The hinter globals for this font.
    289    *
    290    *   hint_mode ::
    291    *     Hinting information.
    292    *
    293    * @return:
    294    *   FreeType error code.  0 means success.
    295    *
    296    * @note:
    297    *   On input, all points within the outline are in font coordinates. On
    298    *   output, they are in 1/64th of pixels.
    299    *
    300    *   The scaling transformation is taken from the `globals' object which
    301    *   must correspond to the same font as the glyph.
    302    *
    303    */
    304   typedef FT_Error
    305   (*T1_Hints_ApplyFunc)( T1_Hints        hints,
    306                          FT_Outline*     outline,
    307                          PSH_Globals     globals,
    308                          FT_Render_Mode  hint_mode );
    309 
    310 
    311   /*************************************************************************
    312    *
    313    * @struct:
    314    *   T1_Hints_FuncsRec
    315    *
    316    * @description:
    317    *   The structure used to provide the API to @T1_Hints objects.
    318    *
    319    * @fields:
    320    *   hints ::
    321    *     A handle to the T1 Hints recorder.
    322    *
    323    *   open ::
    324    *     The function to open a recording session.
    325    *
    326    *   close ::
    327    *     The function to close a recording session.
    328    *
    329    *   stem ::
    330    *     The function to set a simple stem.
    331    *
    332    *   stem3 ::
    333    *     The function to set counter-controlled stems.
    334    *
    335    *   reset ::
    336    *     The function to reset stem hints.
    337    *
    338    *   apply ::
    339    *     The function to apply the hints to the corresponding glyph outline.
    340    *
    341    */
    342   typedef struct  T1_Hints_FuncsRec_
    343   {
    344     T1_Hints               hints;
    345     T1_Hints_OpenFunc      open;
    346     T1_Hints_CloseFunc     close;
    347     T1_Hints_SetStemFunc   stem;
    348     T1_Hints_SetStem3Func  stem3;
    349     T1_Hints_ResetFunc     reset;
    350     T1_Hints_ApplyFunc     apply;
    351 
    352   } T1_Hints_FuncsRec;
    353 
    354 
    355   /*************************************************************************/
    356   /*************************************************************************/
    357   /*****                                                               *****/
    358   /*****                  PUBLIC TYPE 2 HINTS RECORDER                 *****/
    359   /*****                                                               *****/
    360   /*************************************************************************/
    361   /*************************************************************************/
    362 
    363   /*************************************************************************
    364    *
    365    * @type:
    366    *   T2_Hints
    367    *
    368    * @description:
    369    *   This is a handle to an opaque structure used to record glyph hints
    370    *   from a Type 2 character glyph character string.
    371    *
    372    *   The methods used to operate on this object are defined by the
    373    *   @T2_Hints_FuncsRec structure.  Recording glyph hints is normally
    374    *   achieved through the following scheme:
    375    *
    376    *   - Open a new hint recording session by calling the `open' method.
    377    *     This rewinds the recorder and prepare it for new input.
    378    *
    379    *   - For each hint found in the glyph charstring, call the corresponding
    380    *     method (`stems', `hintmask', `counters').  Note that these
    381    *     functions do not return an error code.
    382    *
    383    *   - Close the recording session by calling the `close' method.  It
    384    *     returns an error code if the hints were invalid or something
    385    *     strange happened (e.g., memory shortage).
    386    *
    387    *   The hints accumulated in the object can later be used by the
    388    *   Postscript hinter.
    389    *
    390    */
    391   typedef struct T2_HintsRec_*  T2_Hints;
    392 
    393 
    394   /*************************************************************************
    395    *
    396    * @type:
    397    *   T2_Hints_Funcs
    398    *
    399    * @description:
    400    *   A pointer to the @T2_Hints_FuncsRec structure that defines the API of
    401    *   a given @T2_Hints object.
    402    *
    403    */
    404   typedef const struct T2_Hints_FuncsRec_*  T2_Hints_Funcs;
    405 
    406 
    407   /*************************************************************************
    408    *
    409    * @functype:
    410    *   T2_Hints_OpenFunc
    411    *
    412    * @description:
    413    *   A method of the @T2_Hints class used to prepare it for a new Type 2
    414    *   hints recording session.
    415    *
    416    * @input:
    417    *   hints ::
    418    *     A handle to the Type 2 hints recorder.
    419    *
    420    * @note:
    421    *   You should always call the @T2_Hints_CloseFunc method in order to
    422    *   close an opened recording session.
    423    *
    424    */
    425   typedef void
    426   (*T2_Hints_OpenFunc)( T2_Hints  hints );
    427 
    428 
    429   /*************************************************************************
    430    *
    431    * @functype:
    432    *   T2_Hints_StemsFunc
    433    *
    434    * @description:
    435    *   A method of the @T2_Hints class used to set the table of stems in
    436    *   either the vertical or horizontal dimension.  Equivalent to the
    437    *   `hstem', `vstem', `hstemhm', and `vstemhm' Type 2 operators.
    438    *
    439    * @input:
    440    *   hints ::
    441    *     A handle to the Type 2 hints recorder.
    442    *
    443    *   dimension ::
    444    *     0 for horizontal stems (hstem), 1 for vertical ones (vstem).
    445    *
    446    *   count ::
    447    *     The number of stems.
    448    *
    449    *   coords ::
    450    *     An array of `count' (position,length) pairs in 16.16 format.
    451    *
    452    * @note:
    453    *   Use vertical coordinates (y) for horizontal stems (dim=0).  Use
    454    *   horizontal coordinates (x) for vertical stems (dim=1).
    455    *
    456    *   There are `2*count' elements in the `coords' array.  Each even
    457    *   element is an absolute position in font units, each odd element is a
    458    *   length in font units.
    459    *
    460    *   A length can be negative, in which case it must be either -20 or
    461    *   -21.  It is interpreted as a `ghost' stem, according to the Type 1
    462    *   specification.
    463    *
    464    */
    465   typedef void
    466   (*T2_Hints_StemsFunc)( T2_Hints   hints,
    467                          FT_UInt    dimension,
    468                          FT_UInt    count,
    469                          FT_Fixed*  coordinates );
    470 
    471 
    472   /*************************************************************************
    473    *
    474    * @functype:
    475    *   T2_Hints_MaskFunc
    476    *
    477    * @description:
    478    *   A method of the @T2_Hints class used to set a given hintmask (this
    479    *   corresponds to the `hintmask' Type 2 operator).
    480    *
    481    * @input:
    482    *   hints ::
    483    *     A handle to the Type 2 hints recorder.
    484    *
    485    *   end_point ::
    486    *     The glyph index of the last point to which the previously defined
    487    *     or activated hints apply.
    488    *
    489    *   bit_count ::
    490    *     The number of bits in the hint mask.
    491    *
    492    *   bytes ::
    493    *     An array of bytes modelling the hint mask.
    494    *
    495    * @note:
    496    *   If the hintmask starts the charstring (before any glyph point
    497    *   definition), the value of `end_point' should be 0.
    498    *
    499    *   `bit_count' is the number of meaningful bits in the `bytes' array; it
    500    *   must be equal to the total number of hints defined so far (i.e.,
    501    *   horizontal+verticals).
    502    *
    503    *   The `bytes' array can come directly from the Type 2 charstring and
    504    *   respects the same format.
    505    *
    506    */
    507   typedef void
    508   (*T2_Hints_MaskFunc)( T2_Hints        hints,
    509                         FT_UInt         end_point,
    510                         FT_UInt         bit_count,
    511                         const FT_Byte*  bytes );
    512 
    513 
    514   /*************************************************************************
    515    *
    516    * @functype:
    517    *   T2_Hints_CounterFunc
    518    *
    519    * @description:
    520    *   A method of the @T2_Hints class used to set a given counter mask
    521    *   (this corresponds to the `hintmask' Type 2 operator).
    522    *
    523    * @input:
    524    *   hints ::
    525    *     A handle to the Type 2 hints recorder.
    526    *
    527    *   end_point ::
    528    *     A glyph index of the last point to which the previously defined or
    529    *     active hints apply.
    530    *
    531    *   bit_count ::
    532    *     The number of bits in the hint mask.
    533    *
    534    *   bytes ::
    535    *     An array of bytes modelling the hint mask.
    536    *
    537    * @note:
    538    *   If the hintmask starts the charstring (before any glyph point
    539    *   definition), the value of `end_point' should be 0.
    540    *
    541    *   `bit_count' is the number of meaningful bits in the `bytes' array; it
    542    *   must be equal to the total number of hints defined so far (i.e.,
    543    *   horizontal+verticals).
    544    *
    545    *    The `bytes' array can come directly from the Type 2 charstring and
    546    *    respects the same format.
    547    *
    548    */
    549   typedef void
    550   (*T2_Hints_CounterFunc)( T2_Hints        hints,
    551                            FT_UInt         bit_count,
    552                            const FT_Byte*  bytes );
    553 
    554 
    555   /*************************************************************************
    556    *
    557    * @functype:
    558    *   T2_Hints_CloseFunc
    559    *
    560    * @description:
    561    *   A method of the @T2_Hints class used to close a hint recording
    562    *   session.
    563    *
    564    * @input:
    565    *   hints ::
    566    *     A handle to the Type 2 hints recorder.
    567    *
    568    *   end_point ::
    569    *     The index of the last point in the input glyph.
    570    *
    571    * @return:
    572    *   FreeType error code.  0 means success.
    573    *
    574    * @note:
    575    *   The error code is set to indicate that an error occurred during the
    576    *   recording session.
    577    *
    578    */
    579   typedef FT_Error
    580   (*T2_Hints_CloseFunc)( T2_Hints  hints,
    581                          FT_UInt   end_point );
    582 
    583 
    584   /*************************************************************************
    585    *
    586    * @functype:
    587    *   T2_Hints_ApplyFunc
    588    *
    589    * @description:
    590    *   A method of the @T2_Hints class used to apply hints to the
    591    *   corresponding glyph outline.  Must be called after the `close'
    592    *   method.
    593    *
    594    * @input:
    595    *   hints ::
    596    *     A handle to the Type 2 hints recorder.
    597    *
    598    *   outline ::
    599    *     A pointer to the target outline descriptor.
    600    *
    601    *   globals ::
    602    *     The hinter globals for this font.
    603    *
    604    *   hint_mode ::
    605    *     Hinting information.
    606    *
    607    * @return:
    608    *   FreeType error code.  0 means success.
    609    *
    610    * @note:
    611    *   On input, all points within the outline are in font coordinates. On
    612    *   output, they are in 1/64th of pixels.
    613    *
    614    *   The scaling transformation is taken from the `globals' object which
    615    *   must correspond to the same font than the glyph.
    616    *
    617    */
    618   typedef FT_Error
    619   (*T2_Hints_ApplyFunc)( T2_Hints        hints,
    620                          FT_Outline*     outline,
    621                          PSH_Globals     globals,
    622                          FT_Render_Mode  hint_mode );
    623 
    624 
    625   /*************************************************************************
    626    *
    627    * @struct:
    628    *   T2_Hints_FuncsRec
    629    *
    630    * @description:
    631    *   The structure used to provide the API to @T2_Hints objects.
    632    *
    633    * @fields:
    634    *   hints ::
    635    *     A handle to the T2 hints recorder object.
    636    *
    637    *   open ::
    638    *     The function to open a recording session.
    639    *
    640    *   close ::
    641    *     The function to close a recording session.
    642    *
    643    *   stems ::
    644    *     The function to set the dimension's stems table.
    645    *
    646    *   hintmask ::
    647    *     The function to set hint masks.
    648    *
    649    *   counter ::
    650    *     The function to set counter masks.
    651    *
    652    *   apply ::
    653    *     The function to apply the hints on the corresponding glyph outline.
    654    *
    655    */
    656   typedef struct  T2_Hints_FuncsRec_
    657   {
    658     T2_Hints              hints;
    659     T2_Hints_OpenFunc     open;
    660     T2_Hints_CloseFunc    close;
    661     T2_Hints_StemsFunc    stems;
    662     T2_Hints_MaskFunc     hintmask;
    663     T2_Hints_CounterFunc  counter;
    664     T2_Hints_ApplyFunc    apply;
    665 
    666   } T2_Hints_FuncsRec;
    667 
    668 
    669   /* */
    670 
    671 
    672   typedef struct  PSHinter_Interface_
    673   {
    674     PSH_Globals_Funcs  (*get_globals_funcs)( FT_Module  module );
    675     T1_Hints_Funcs     (*get_t1_funcs)     ( FT_Module  module );
    676     T2_Hints_Funcs     (*get_t2_funcs)     ( FT_Module  module );
    677 
    678   } PSHinter_Interface;
    679 
    680   typedef PSHinter_Interface*  PSHinter_Service;
    681 
    682 #ifndef FT_CONFIG_OPTION_PIC
    683 
    684 #define FT_DEFINE_PSHINTER_INTERFACE(class_, get_globals_funcs_,             \
    685                                      get_t1_funcs_, get_t2_funcs_)           \
    686   static const PSHinter_Interface class_ =                                   \
    687   {                                                                          \
    688     get_globals_funcs_, get_t1_funcs_, get_t2_funcs_                         \
    689   };
    690 
    691 #else /* FT_CONFIG_OPTION_PIC */
    692 
    693 #define FT_DEFINE_PSHINTER_INTERFACE(class_, get_globals_funcs_,             \
    694                                      get_t1_funcs_, get_t2_funcs_)           \
    695   void                                                                       \
    696   FT_Init_Class_##class_( FT_Library library,                                \
    697                           PSHinter_Interface*  clazz)                        \
    698   {                                                                          \
    699     FT_UNUSED(library);                                                      \
    700     clazz->get_globals_funcs = get_globals_funcs_;                           \
    701     clazz->get_t1_funcs = get_t1_funcs_;                                     \
    702     clazz->get_t2_funcs = get_t2_funcs_;                                     \
    703   }
    704 
    705 #endif /* FT_CONFIG_OPTION_PIC */
    706 
    707 FT_END_HEADER
    708 
    709 #endif /* __PSHINTS_H__ */
    710 
    711 
    712 /* END */
    713