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 (C) 2001-2020 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 void
  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 strange
  98    *     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 the
 175    *   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 functions
 381    *     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 strange
 385    *     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 element
 457    *   is an absolute position in font units, each odd element is a length in
 458    *   font units.
 459    *
 460    *   A length can be negative, in which case it must be either -20 or -21.
 461    *   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_Int     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 or
 487    *     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 (this
 521    *   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' method.
 592    *
 593    * @input:
 594    *   hints ::
 595    *     A handle to the Type 2 hints recorder.
 596    *
 597    *   outline ::
 598    *     A pointer to the target outline descriptor.
 599    *
 600    *   globals ::
 601    *     The hinter globals for this font.
 602    *
 603    *   hint_mode ::
 604    *     Hinting information.
 605    *
 606    * @return:
 607    *   FreeType error code.  0 means success.
 608    *
 609    * @note:
 610    *   On input, all points within the outline are in font coordinates. On
 611    *   output, they are in 1/64th of pixels.
 612    *
 613    *   The scaling transformation is taken from the 'globals' object which
 614    *   must correspond to the same font than the glyph.
 615    *
 616    */
 617   typedef FT_Error
 618   (*T2_Hints_ApplyFunc)( T2_Hints        hints,
 619                          FT_Outline*     outline,
 620                          PSH_Globals     globals,
 621                          FT_Render_Mode  hint_mode );
 622 
 623 
 624   /**************************************************************************
 625    *
 626    * @struct:
 627    *   T2_Hints_FuncsRec
 628    *
 629    * @description:
 630    *   The structure used to provide the API to @T2_Hints objects.
 631    *
 632    * @fields:
 633    *   hints ::
 634    *     A handle to the T2 hints recorder object.
 635    *
 636    *   open ::
 637    *     The function to open a recording session.
 638    *
 639    *   close ::
 640    *     The function to close a recording session.
 641    *
 642    *   stems ::
 643    *     The function to set the dimension's stems table.
 644    *
 645    *   hintmask ::
 646    *     The function to set hint masks.
 647    *
 648    *   counter ::
 649    *     The function to set counter masks.
 650    *
 651    *   apply ::
 652    *     The function to apply the hints on the corresponding glyph outline.
 653    *
 654    */
 655   typedef struct  T2_Hints_FuncsRec_
 656   {
 657     T2_Hints              hints;
 658     T2_Hints_OpenFunc     open;
 659     T2_Hints_CloseFunc    close;
 660     T2_Hints_StemsFunc    stems;
 661     T2_Hints_MaskFunc     hintmask;
 662     T2_Hints_CounterFunc  counter;
 663     T2_Hints_ApplyFunc    apply;
 664 
 665   } T2_Hints_FuncsRec;
 666 
 667 
 668   /* */
 669 
 670 
 671   typedef struct  PSHinter_Interface_
 672   {
 673     PSH_Globals_Funcs  (*get_globals_funcs)( FT_Module  module );
 674     T1_Hints_Funcs     (*get_t1_funcs)     ( FT_Module  module );
 675     T2_Hints_Funcs     (*get_t2_funcs)     ( FT_Module  module );
 676 
 677   } PSHinter_Interface;
 678 
 679   typedef PSHinter_Interface*  PSHinter_Service;
 680 
 681 
 682 #define FT_DEFINE_PSHINTER_INTERFACE(        \
 683           class_,                            \
 684           get_globals_funcs_,                \
 685           get_t1_funcs_,                     \
 686           get_t2_funcs_ )                    \
 687   static const PSHinter_Interface  class_ =  \
 688   {                                          \
 689     get_globals_funcs_,                      \
 690     get_t1_funcs_,                           \
 691     get_t2_funcs_                            \
 692   };
 693 
 694 
 695 FT_END_HEADER
 696 
 697 #endif /* PSHINTS_H_ */
 698 
 699 
 700 /* END */