include/freetype/internal/pshints.h

   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 */