1 /****************************************************************************
   2  *
   3  * ttobjs.h
   4  *
   5  *   Objects manager (specification).
   6  *
   7  * Copyright (C) 1996-2019 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  */
  17 
  18 
  19 #ifndef TTOBJS_H_
  20 #define TTOBJS_H_
  21 
  22 
  23 #include <ft2build.h>
  24 #include FT_INTERNAL_OBJECTS_H
  25 #include FT_INTERNAL_TRUETYPE_TYPES_H
  26 
  27 
  28 FT_BEGIN_HEADER
  29 
  30 
  31   /**************************************************************************
  32    *
  33    * @Type:
  34    *   TT_Driver
  35    *
  36    * @Description:
  37    *   A handle to a TrueType driver object.
  38    */
  39   typedef struct TT_DriverRec_*  TT_Driver;
  40 
  41 
  42   /**************************************************************************
  43    *
  44    * @Type:
  45    *   TT_GlyphSlot
  46    *
  47    * @Description:
  48    *   A handle to a TrueType glyph slot object.
  49    *
  50    * @Note:
  51    *   This is a direct typedef of FT_GlyphSlot, as there is nothing
  52    *   specific about the TrueType glyph slot.
  53    */
  54   typedef FT_GlyphSlot  TT_GlyphSlot;
  55 
  56 
  57   /**************************************************************************
  58    *
  59    * @Struct:
  60    *   TT_GraphicsState
  61    *
  62    * @Description:
  63    *   The TrueType graphics state used during bytecode interpretation.
  64    */
  65   typedef struct  TT_GraphicsState_
  66   {
  67     FT_UShort      rp0;
  68     FT_UShort      rp1;
  69     FT_UShort      rp2;
  70 
  71     FT_UnitVector  dualVector;
  72     FT_UnitVector  projVector;
  73     FT_UnitVector  freeVector;
  74 
  75     FT_Long        loop;
  76     FT_F26Dot6     minimum_distance;
  77     FT_Int         round_state;
  78 
  79     FT_Bool        auto_flip;
  80     FT_F26Dot6     control_value_cutin;
  81     FT_F26Dot6     single_width_cutin;
  82     FT_F26Dot6     single_width_value;
  83     FT_UShort      delta_base;
  84     FT_UShort      delta_shift;
  85 
  86     FT_Byte        instruct_control;
  87     /* According to Greg Hitchcock from Microsoft, the `scan_control'     */
  88     /* variable as documented in the TrueType specification is a 32-bit   */
  89     /* integer; the high-word part holds the SCANTYPE value, the low-word */
  90     /* part the SCANCTRL value.  We separate it into two fields.          */
  91     FT_Bool        scan_control;
  92     FT_Int         scan_type;
  93 
  94     FT_UShort      gep0;
  95     FT_UShort      gep1;
  96     FT_UShort      gep2;
  97 
  98   } TT_GraphicsState;
  99 
 100 
 101 #ifdef TT_USE_BYTECODE_INTERPRETER
 102 
 103   FT_LOCAL( void )
 104   tt_glyphzone_done( TT_GlyphZone  zone );
 105 
 106   FT_LOCAL( FT_Error )
 107   tt_glyphzone_new( FT_Memory     memory,
 108                     FT_UShort     maxPoints,
 109                     FT_Short      maxContours,
 110                     TT_GlyphZone  zone );
 111 
 112 #endif /* TT_USE_BYTECODE_INTERPRETER */
 113 
 114 
 115 
 116   /**************************************************************************
 117    *
 118    * EXECUTION SUBTABLES
 119    *
 120    * These sub-tables relate to instruction execution.
 121    *
 122    */
 123 
 124 
 125 #define TT_MAX_CODE_RANGES  3
 126 
 127 
 128   /**************************************************************************
 129    *
 130    * There can only be 3 active code ranges at once:
 131    *   - the Font Program
 132    *   - the CVT Program
 133    *   - a glyph's instructions set
 134    */
 135   typedef enum  TT_CodeRange_Tag_
 136   {
 137     tt_coderange_none = 0,
 138     tt_coderange_font,
 139     tt_coderange_cvt,
 140     tt_coderange_glyph
 141 
 142   } TT_CodeRange_Tag;
 143 
 144 
 145   typedef struct  TT_CodeRange_
 146   {
 147     FT_Byte*  base;
 148     FT_Long   size;
 149 
 150   } TT_CodeRange;
 151 
 152   typedef TT_CodeRange  TT_CodeRangeTable[TT_MAX_CODE_RANGES];
 153 
 154 
 155   /**************************************************************************
 156    *
 157    * Defines a function/instruction definition record.
 158    */
 159   typedef struct  TT_DefRecord_
 160   {
 161     FT_Int    range;          /* in which code range is it located?     */
 162     FT_Long   start;          /* where does it start?                   */
 163     FT_Long   end;            /* where does it end?                     */
 164     FT_UInt   opc;            /* function #, or instruction code        */
 165     FT_Bool   active;         /* is it active?                          */
 166     FT_Bool   inline_delta;   /* is function that defines inline delta? */
 167     FT_ULong  sph_fdef_flags; /* flags to identify special functions    */
 168 
 169   } TT_DefRecord, *TT_DefArray;
 170 
 171 
 172   /**************************************************************************
 173    *
 174    * Subglyph transformation record.
 175    */
 176   typedef struct  TT_Transform_
 177   {
 178     FT_Fixed    xx, xy;     /* transformation matrix coefficients */
 179     FT_Fixed    yx, yy;
 180     FT_F26Dot6  ox, oy;     /* offsets                            */
 181 
 182   } TT_Transform;
 183 
 184 
 185   /**************************************************************************
 186    *
 187    * A note regarding non-squared pixels:
 188    *
 189    * (This text will probably go into some docs at some time; for now, it
 190    * is kept here to explain some definitions in the TT_Size_Metrics
 191    * record).
 192    *
 193    * The CVT is a one-dimensional array containing values that control
 194    * certain important characteristics in a font, like the height of all
 195    * capitals, all lowercase letter, default spacing or stem width/height.
 196    *
 197    * These values are found in FUnits in the font file, and must be scaled
 198    * to pixel coordinates before being used by the CVT and glyph programs.
 199    * Unfortunately, when using distinct x and y resolutions (or distinct x
 200    * and y pointsizes), there are two possible scalings.
 201    *
 202    * A first try was to implement a `lazy' scheme where all values were
 203    * scaled when first used.  However, while some values are always used
 204    * in the same direction, some others are used under many different
 205    * circumstances and orientations.
 206    *
 207    * I have found a simpler way to do the same, and it even seems to work
 208    * in most of the cases:
 209    *
 210    * - All CVT values are scaled to the maximum ppem size.
 211    *
 212    * - When performing a read or write in the CVT, a ratio factor is used
 213    *   to perform adequate scaling.  Example:
 214    *
 215    *     x_ppem = 14
 216    *     y_ppem = 10
 217    *
 218    *   We choose ppem = x_ppem = 14 as the CVT scaling size.  All cvt
 219    *   entries are scaled to it.
 220    *
 221    *     x_ratio = 1.0
 222    *     y_ratio = y_ppem/ppem (< 1.0)
 223    *
 224    *   We compute the current ratio like:
 225    *
 226    *   - If projVector is horizontal,
 227    *       ratio = x_ratio = 1.0
 228    *
 229    *   - if projVector is vertical,
 230    *       ratio = y_ratio
 231    *
 232    *   - else,
 233    *       ratio = sqrt( (proj.x * x_ratio) ^ 2 + (proj.y * y_ratio) ^ 2 )
 234    *
 235    *   Reading a cvt value returns
 236    *     ratio * cvt[index]
 237    *
 238    *   Writing a cvt value in pixels:
 239    *     cvt[index] / ratio
 240    *
 241    *   The current ppem is simply
 242    *     ratio * ppem
 243    *
 244    */
 245 
 246 
 247   /**************************************************************************
 248    *
 249    * Metrics used by the TrueType size and context objects.
 250    */
 251   typedef struct  TT_Size_Metrics_
 252   {
 253     /* for non-square pixels */
 254     FT_Long     x_ratio;
 255     FT_Long     y_ratio;
 256 
 257     FT_UShort   ppem;               /* maximum ppem size              */
 258     FT_Long     ratio;              /* current ratio                  */
 259     FT_Fixed    scale;
 260 
 261     FT_F26Dot6  compensations[4];   /* device-specific compensations  */
 262 
 263     FT_Bool     valid;
 264 
 265     FT_Bool     rotated;            /* `is the glyph rotated?'-flag   */
 266     FT_Bool     stretched;          /* `is the glyph stretched?'-flag */
 267 
 268   } TT_Size_Metrics;
 269 
 270 
 271   /**************************************************************************
 272    *
 273    * TrueType size class.
 274    */
 275   typedef struct  TT_SizeRec_
 276   {
 277     FT_SizeRec         root;
 278 
 279     /* we have our own copy of metrics so that we can modify */
 280     /* it without affecting auto-hinting (when used)         */
 281     FT_Size_Metrics*   metrics;        /* for the current rendering mode */
 282     FT_Size_Metrics    hinted_metrics; /* for the hinted rendering mode  */
 283 
 284     TT_Size_Metrics    ttmetrics;
 285 
 286     FT_ULong           strike_index;      /* 0xFFFFFFFF to indicate invalid */
 287 
 288 #ifdef TT_USE_BYTECODE_INTERPRETER
 289 
 290     FT_Long            point_size;    /* for the `MPS' bytecode instruction */
 291 
 292     FT_UInt            num_function_defs; /* number of function definitions */
 293     FT_UInt            max_function_defs;
 294     TT_DefArray        function_defs;     /* table of function definitions  */
 295 
 296     FT_UInt            num_instruction_defs;  /* number of ins. definitions */
 297     FT_UInt            max_instruction_defs;
 298     TT_DefArray        instruction_defs;      /* table of ins. definitions  */
 299 
 300     FT_UInt            max_func;
 301     FT_UInt            max_ins;
 302 
 303     TT_CodeRangeTable  codeRangeTable;
 304 
 305     TT_GraphicsState   GS;
 306 
 307     FT_ULong           cvt_size;      /* the scaled control value table */
 308     FT_Long*           cvt;
 309 
 310     FT_UShort          storage_size; /* The storage area is now part of */
 311     FT_Long*           storage;      /* the instance                    */
 312 
 313     TT_GlyphZoneRec    twilight;     /* The instance's twilight zone    */
 314 
 315     TT_ExecContext     context;
 316 
 317     /* if negative, `fpgm' (resp. `prep'), wasn't executed yet; */
 318     /* otherwise it is the returned error code                  */
 319     FT_Error           bytecode_ready;
 320     FT_Error           cvt_ready;
 321 
 322 #endif /* TT_USE_BYTECODE_INTERPRETER */
 323 
 324   } TT_SizeRec;
 325 
 326 
 327   /**************************************************************************
 328    *
 329    * TrueType driver class.
 330    */
 331   typedef struct  TT_DriverRec_
 332   {
 333     FT_DriverRec  root;
 334 
 335     TT_GlyphZoneRec  zone;     /* glyph loader points zone */
 336 
 337     FT_UInt  interpreter_version;
 338 
 339   } TT_DriverRec;
 340 
 341 
 342   /* Note: All of the functions below (except tt_size_reset()) are used    */
 343   /* as function pointers in a FT_Driver_ClassRec.  Therefore their        */
 344   /* parameters are of types FT_Face, FT_Size, etc., rather than TT_Face,  */
 345   /* TT_Size, etc., so that the compiler can confirm that the types and    */
 346   /* number of parameters are correct.  In all cases the FT_xxx types are  */
 347   /* cast to their TT_xxx counterparts inside the functions since FreeType */
 348   /* will always use the TT driver to create them.                         */
 349 
 350 
 351   /**************************************************************************
 352    *
 353    * Face functions
 354    */
 355   FT_LOCAL( FT_Error )
 356   tt_face_init( FT_Stream      stream,
 357                 FT_Face        ttface,      /* TT_Face */
 358                 FT_Int         face_index,
 359                 FT_Int         num_params,
 360                 FT_Parameter*  params );
 361 
 362   FT_LOCAL( void )
 363   tt_face_done( FT_Face  ttface );          /* TT_Face */
 364 
 365 
 366   /**************************************************************************
 367    *
 368    * Size functions
 369    */
 370   FT_LOCAL( FT_Error )
 371   tt_size_init( FT_Size  ttsize );          /* TT_Size */
 372 
 373   FT_LOCAL( void )
 374   tt_size_done( FT_Size  ttsize );          /* TT_Size */
 375 
 376 #ifdef TT_USE_BYTECODE_INTERPRETER
 377 
 378   FT_LOCAL( FT_Error )
 379   tt_size_run_fpgm( TT_Size  size,
 380                     FT_Bool  pedantic );
 381 
 382   FT_LOCAL( FT_Error )
 383   tt_size_run_prep( TT_Size  size,
 384                     FT_Bool  pedantic );
 385 
 386   FT_LOCAL( FT_Error )
 387   tt_size_ready_bytecode( TT_Size  size,
 388                           FT_Bool  pedantic );
 389 
 390 #endif /* TT_USE_BYTECODE_INTERPRETER */
 391 
 392   FT_LOCAL( FT_Error )
 393   tt_size_reset( TT_Size  size,
 394                  FT_Bool  only_height );
 395 
 396 
 397   /**************************************************************************
 398    *
 399    * Driver functions
 400    */
 401   FT_LOCAL( FT_Error )
 402   tt_driver_init( FT_Module  ttdriver );    /* TT_Driver */
 403 
 404   FT_LOCAL( void )
 405   tt_driver_done( FT_Module  ttdriver );    /* TT_Driver */
 406 
 407 
 408   /**************************************************************************
 409    *
 410    * Slot functions
 411    */
 412   FT_LOCAL( FT_Error )
 413   tt_slot_init( FT_GlyphSlot  slot );
 414 
 415 
 416   /* auxiliary */
 417 #define IS_HINTED( flags )  ( ( flags & FT_LOAD_NO_HINTING ) == 0 )
 418 
 419 
 420 FT_END_HEADER
 421 
 422 #endif /* TTOBJS_H_ */
 423 
 424 
 425 /* END */