1
/* Copyright (C) 2001-2006 Artifex Software, Inc.
4
This software is provided AS-IS with no warranty, either express or
7
This software is distributed under license and may not be copied, modified
8
or distributed except as expressly authorized under the terms of that
9
license. Refer to licensing information at http://www.artifex.com/
10
or contact Artifex Software, Inc., 7 Mt. Lassen Drive - Suite A-134,
11
San Rafael, CA 94903, U.S.A., +1(415)492-9861, for further information.
14
/* $Id: ttobjs.h 8022 2007-06-05 22:23:38Z giles $ */
16
/* Changes after FreeType: cut out the TrueType instruction interpreter. */
19
/*******************************************************************
23
* Objects definition unit.
25
* Copyright 1996-1998 by
26
* David Turner, Robert Wilhelm, and Werner Lemberg.
28
* This file is part of the FreeType project, and may only be used
29
* modified and distributed under the terms of the FreeType project
30
* license, LICENSE.TXT. By continuing to use, modify, or distribute
31
* this file you indicate that you have read the license and
32
* understand and accept it fully.
34
******************************************************************/
49
/* This file contains the definitions and methods of the four */
50
/* kinds of objects managed by the FreeType engine. These are: */
55
/* There is always one face object per opened TrueType font */
56
/* file, and only one. The face object contains data that is */
57
/* independent of current transform/scaling/rotation and */
58
/* pointsize, or glyph index. This data is made of several */
59
/* critical tables that are loaded on face object creation. */
61
/* A face object tracks all active and recycled objects of */
62
/* the instance and execution context classes. Destroying a face */
63
/* object will automatically destroy all associated instances. */
66
/* Instance objects: */
68
/* An instance object always relates to a given face object, */
69
/* known as its 'parent' or 'owner', and contains only the */
70
/* data that is specific to one given pointsize/transform of */
71
/* the face. You can only create an instance from a face object. */
73
/* An instance's current transform/pointsize can be changed */
74
/* at any time using a single high-level API call, */
75
/* TT_Reset_Instance(). */
77
/* Execution Context objects: */
79
/* An execution context (or context in short) relates to a face. */
80
/* It contains the data and tables that are necessary to load */
81
/* and hint (i.e. execute the glyph instructions of) one glyph. */
82
/* A context is a transient object that is queried/created on */
83
/* the fly: client applications never deal with them directly. */
88
/* A glyph object contains only the minimal glyph information */
89
/* needed to render one glyph correctly. This means that a glyph */
90
/* object really contains tables that are sized to hold the */
91
/* contents of _any_ glyph of a given face. A client application */
92
/* can usually create one glyph object for a given face, then use */
93
/* it for all subsequent loads. */
95
/* Here is an example of a client application : */
96
/* (NOTE: No error checking performed here!) */
99
/* TT_Face face; -- face handle */
100
/* TT_Instance ins1, ins2; -- two instance handles */
101
/* TT_Glyph glyph; -- glyph handle */
103
/* TT_Init_FreeType(); */
105
/* -- Initialize the engine. This must be done prior to _any_ */
108
/* TT_Open_Face( "/some/face/name.ttf", &face ); */
110
/* -- create the face object. This call opens the font file */
112
/* TT_New_Instance( face, &ins1 ); */
113
/* TT_New_Instance( face, &ins2 ); */
115
/* TT_Set_Instance_PointSize( ins1, 8 ); */
116
/* TT_Set_Instance_PointSize( ins2, 12 ); */
118
/* -- create two distinct instances of the same face */
119
/* -- ins1 is pointsize 8 at resolution 96 dpi */
120
/* -- ins2 is pointsize 12 at resolution 96 dpi */
122
/* TT_New_Glyph( face, &glyph ); */
124
/* -- create a new glyph object which will receive the contents */
125
/* of any glyph of 'face' */
127
/* TT_Load_Glyph( ins1, glyph, 64, DEFAULT_GLYPH_LOAD ); */
129
/* -- load glyph indexed 64 at pointsize 8 in the 'glyph' object */
130
/* -- NOTE: This call will fail if the instance and the glyph */
131
/* do not relate to the same face object. */
133
/* TT_Get_Outline( glyph, &outline ); */
135
/* -- extract the glyph outline from the object and copies it */
136
/* to the 'outline' record */
138
/* TT_Get_Metrics( glyph, &metrics ); */
140
/* -- extract the glyph metrics and put them into the 'metrics' */
143
/* TT_Load_Glyph( ins2, glyph, 64, DEFAULT_GLYPH_LOAD ); */
145
/* -- load the same glyph at pointsize 12 in the 'glyph' object */
148
/* TT_Close_Face( &face ); */
150
/* -- destroy the face object. This will destroy 'ins1' and */
151
/* 'ins2'. However, the glyph object will still be available */
153
/* TT_Done_FreeType(); */
155
/* -- Finalize the engine. This will also destroy all pending */
156
/* glyph objects (here 'glyph'). */
162
struct _TExecution_Context;
165
#ifndef TFace_defined
166
#define TFace_defined
167
typedef struct _TFace TFace;
169
typedef TFace* PFace;
171
#ifndef TInstance_defined
172
#define TInstance_defined
173
typedef struct _TInstance TInstance;
175
typedef TInstance* PInstance;
177
#ifndef TExecution_Context_defined
178
#define TExecution_Context_defined
179
typedef struct _TExecution_Context TExecution_Context;
181
typedef TExecution_Context* PExecution_Context;
183
typedef struct _TGlyph TGlyph;
184
typedef TGlyph* PGlyph;
187
/*************************************************************/
189
/* ADDITIONAL SUBTABLES */
191
/* These tables are not precisely defined by the specs */
192
/* but their structures is implied by the TrueType font */
195
/*************************************************************/
199
/* The Graphics State (GS) is managed by the */
200
/* instruction field, but does not come from */
201
/* the font file. Thus, we can use 'int's */
204
struct _TGraphicsState
210
TT_UnitVector dualVector;
211
TT_UnitVector projVector;
212
TT_UnitVector freeVector;
215
TT_F26Dot6 minimum_distance;
219
TT_F26Dot6 control_value_cutin;
220
TT_F26Dot6 single_width_cutin;
221
TT_F26Dot6 single_width_value;
225
Byte instruct_control;
235
typedef struct _TGraphicsState TGraphicsState;
238
extern const TGraphicsState Default_GraphicsState;
241
/*************************************************************/
243
/* EXECUTION SUBTABLES */
245
/* These sub-tables relate to instruction execution. */
247
/*************************************************************/
249
# define MAX_CODE_RANGES 3
251
/* There can only be 3 active code ranges at once: */
252
/* - the Font Program */
253
/* - the CVT Program */
254
/* - a glyph's instructions set */
256
# define TT_CodeRange_Font 1
257
# define TT_CodeRange_Cvt 2
258
# define TT_CodeRange_Glyph 3
267
typedef struct _TCodeRange TCodeRange;
268
typedef TCodeRange* PCodeRange;
271
/* Defintion of a code range */
273
/* Code ranges can be resident to a glyph (i.e. the Font Program) */
274
/* while some others are volatile (Glyph instructions). */
275
/* Tracking the state and presence of code ranges allows function */
276
/* and instruction definitions within a code range to be forgotten */
277
/* when the range is discarded. */
279
typedef TCodeRange TCodeRangeTable[MAX_CODE_RANGES];
281
/* defines a function/instruction definition record */
285
Int Range; /* in which code range is it located ? */
286
Int Start; /* where does it start ? */
287
Byte Opc; /* function #, or instruction code */
288
Bool Active; /* is it active ? */
291
typedef struct _TDefRecord TDefRecord;
292
typedef TDefRecord* PDefRecord;
293
typedef TDefRecord* PDefArray;
295
/* defines a call record, used to manage function calls. */
305
typedef struct _TCallRecord TCallRecord;
306
typedef TCallRecord* PCallRecord;
307
typedef TCallRecord* PCallStack; /* defines a simple call stack */
310
/* This type defining a set of glyph points will be used to represent */
311
/* each zone (regular and twilight) during instructions decoding. */
314
int n_points; /* number of points in zone */
315
int n_contours; /* number of contours */
317
PCoordinates org_x; /* original points coordinates */
318
PCoordinates org_y; /* original points coordinates */
319
PCoordinates cur_x; /* current points coordinates */
320
PCoordinates cur_y; /* current points coordinates */
322
Byte* touch; /* current touch flags */
323
Short* contours; /* contour end points */
326
typedef struct _TGlyph_Zone TGlyph_Zone;
327
typedef TGlyph_Zone *PGlyph_Zone;
331
#ifndef TT_STATIC_INTERPRETER /* indirect implementation */
333
#define EXEC_OPS PExecution_Context exc,
334
#define EXEC_OP PExecution_Context exc
335
#define EXEC_ARGS exc,
338
#else /* static implementation */
340
#define EXEC_OPS /* void */
341
#define EXEC_OP /* void */
342
#define EXEC_ARGS /* void */
343
#define EXEC_ARG /* void */
347
/* Rounding function, as used by the interpreter */
348
typedef TT_F26Dot6 (*TRound_Function)( EXEC_OPS TT_F26Dot6 distance,
349
TT_F26Dot6 compensation );
351
/* Point displacement along the freedom vector routine, as */
352
/* used by the interpreter */
353
typedef void (*TMove_Function)( EXEC_OPS PGlyph_Zone zone,
355
TT_F26Dot6 distance );
357
/* Distance projection along one of the proj. vectors, as used */
358
/* by the interpreter */
359
typedef TT_F26Dot6 (*TProject_Function)( EXEC_OPS TT_F26Dot6 Vx,
362
/* reading a cvt value. Take care of non-square pixels when needed */
363
typedef TT_F26Dot6 (*TGet_CVT_Function)( EXEC_OPS Int index );
365
/* setting or moving a cvt value. Take care of non-square pixels */
367
typedef void (*TSet_CVT_Function)( EXEC_OPS Int index,
370
/* subglyph transformation record */
373
TT_Fixed xx, xy; /* transformation */
374
TT_Fixed yx, yy; /* matrix */
375
TT_F26Dot6 ox, oy; /* offsets */
378
typedef struct _TTransform TTransform;
379
typedef TTransform *PTransform;
381
/* subglyph loading record. Used to load composite components */
382
struct _TSubglyph_Record
384
Int index; /* subglyph index */
385
Bool is_scaled; /* is the subglyph scaled? */
386
Bool is_hinted; /* should it be hinted? */
387
Bool preserve_pps; /* preserve phantom points? */
395
Int arg1; /* first argument */
396
Int arg2; /* second argument */
398
Int element_flag; /* current load element flag */
400
TTransform transform; /* transform */
402
TT_Vector pp1, pp2; /* phantom points */
404
Int leftBearing; /* in FUnits */
405
Int advanceWidth; /* in FUnits */
408
typedef struct _TSubglyph_Record TSubglyph_Record;
409
typedef TSubglyph_Record* PSubglyph_Record;
410
typedef TSubglyph_Record* PSubglyph_Stack;
412
/* A note regarding non-squared pixels: */
414
/* (This text will probably go into some docs at some time, for */
415
/* now, it is kept there to explain some definitions in the */
416
/* TIns_Metrics record). */
418
/* The CVT is a one-dimensional array containing values that */
419
/* control certain important characteristics in a font, like */
420
/* the height of all capitals, all lowercase letter, default */
421
/* spacing or stem width/height. */
423
/* These values are found in FUnits in the font file, and must be */
424
/* scaled to pixel coordinates before being used by the CVT and */
425
/* glyph programs. Unfortunately, when using distinct x and y */
426
/* resolutions (or distinct x and y pointsizes), there are two */
427
/* possible scalings. */
429
/* A first try was to implement a 'lazy' scheme where all values */
430
/* were scaled when first used. However, while some values are always */
431
/* used in the same direction, and some other are used in many */
432
/* different circumstances and orientations. */
434
/* I have found a simpler way to do the same, and it even seems to */
435
/* work in most of the cases: */
437
/* - all CVT values are scaled to the maximum ppem size */
439
/* - when performing a read or write in the CVT, a ratio factor */
440
/* is used to perform adequate scaling. Example: */
445
/* we choose ppem = x_ppem = 14 as the CVT scaling size. All cvt */
446
/* entries are scaled to it. */
449
/* y_ratio = y_ppem/ppem (< 1.0) */
451
/* we compute the current ratio like: */
453
/* - if projVector is horizontal, */
454
/* ratio = x_ratio = 1.0 */
455
/* - if projVector is vertical, */
456
/* ratop = y_ratio */
458
/* ratio = sqrt((proj.x*x_ratio)^2 + (proj.y*y_ratio)^2) */
460
/* reading a cvt value returns ratio * cvt[index] */
461
/* writing a cvt value in pixels cvt[index] / ratio */
463
/* the current ppem is simply ratio * ppem */
466
/* metrics used by the instance and execution context objects */
469
TT_F26Dot6 pointSize; /* point size. 1 point = 1/72 inch. */
471
Int x_resolution; /* device horizontal resolution in dpi. */
472
Int y_resolution; /* device vertical resolution in dpi. */
474
Int x_ppem; /* horizontal pixels per EM */
475
Int y_ppem; /* vertical pixels per EM */
478
Long x_scale2; /* used to scale FUnits to fractional pixels */
481
Long y_scale2; /* used to scale FUnits to fractional pixels */
483
/* for non-square pixels */
487
Int ppem; /* maximum ppem size */
488
Long ratio; /* current ratio */
490
Long scale2; /* scale for ppem */
492
TT_F26Dot6 compensations[4]; /* device-specific compensations */
494
Bool rotated; /* `is the glyph rotated?'-flag */
495
Bool stretched; /* `is the glyph stretched?'-flag */
498
typedef struct _TIns_Metrics TIns_Metrics;
499
typedef TIns_Metrics *PIns_Metrics;
503
/***********************************************************************/
505
/* FreeType Face Type */
507
/***********************************************************************/
514
/* maximum profile table, as found in the TrueType file */
515
TMaxProfile maxProfile;
518
/* it seems that some maximum values cannot be */
519
/* taken directly from this table, but rather by */
520
/* combining some of its fields; e.g. the max. */
521
/* number of points seems to be given by */
522
/* MAX( maxPoints, maxCompositePoints ) */
524
/* For this reason, we define later our own */
525
/* max values that are used to load and allocate */
526
/* further tables. */
528
/* The glyph locations table */
531
/* The HMTX table data, used to compute both left */
532
/* side bearing and advance width for all glyphs */
534
/* the font program, if any */
538
/* the cvt program, if any */
542
/* the original, unscaled, control value table */
546
/* The following values _must_ be set by the */
547
/* maximum profile loader */
549
Int numGlyphs; /* the face's total number of glyphs */
550
Int maxPoints; /* max glyph points number, simple and composite */
551
Int maxContours; /* max glyph contours number, simple and composite */
552
Int maxComponents; /* max components in a composite glyph */
558
/***********************************************************************/
560
/* FreeType Instance Type */
562
/***********************************************************************/
566
PFace face; /* face object */
570
TIns_Metrics metrics;
572
Int numFDefs; /* number of function definitions */
573
PDefArray FDefs; /* table of FDefs entries */
575
Int numIDefs; /* number of instruction definitions */
576
PDefArray IDefs; /* table of IDefs entries */
577
Int countIDefs;/* The number of defined IDefs (igorm). */
578
Byte IDefPtr[256]; /* Map opcodes to indices of IDefs (igorm). */
580
TCodeRangeTable codeRangeTable;
583
TGraphicsState default_GS;
585
Int cvtSize; /* the scaled control value table */
588
Int storeSize; /* The storage area is now part of the */
589
PLong storage; /* instance */
594
/***********************************************************************/
596
/* FreeType Execution Context Type */
598
/***********************************************************************/
600
struct _TExecution_Context
604
/* instructions state */
606
Int error; /* last execution error */
608
Int curRange; /* current code range number */
609
PByte code; /* current code range */
610
Int IP; /* current instruction pointer */
611
Int codeSize; /* size of current range */
613
Byte opcode; /* current opcode */
614
Int length; /* length of current opcode */
616
Bool step_ins; /* true if the interpreter must */
617
/* increment IP after ins. exec */
619
Int numFDefs; /* number of function defs */
620
PDefRecord FDefs; /* table of FDefs entries */
622
Int numIDefs; /* number of instruction defs */
623
PDefRecord IDefs; /* table of IDefs entries */
624
Int countIDefs;/* The number of defined IDefs (igorm). */
625
Byte IDefPtr[256]; /* Map opcodes to indices of IDefs (igorm). */
627
PByte glyphIns; /* glyph instructions buffer */
628
Int glyphSize; /* glyph instructions buffer size */
630
Int callTop, /* top of call stack during execution */
631
callSize; /* size of call stack */
632
PCallStack callStack; /* call stack */
634
TCodeRangeTable codeRangeTable; /* table of valid coderanges */
635
/* useful for the debugger */
637
Int storeSize; /* size of current storage */
638
PStorage storage; /* storage area */
640
Int stackSize; /* size of exec. stack */
641
Int top; /* top of exec. stack */
642
PStorage stack; /* current exec. stack */
645
new_top; /* new top after exec. */
647
TT_F26Dot6 period; /* values used for the */
648
TT_F26Dot6 phase; /* 'SuperRounding' */
649
TT_F26Dot6 threshold;
651
TIns_Metrics metrics; /* instance metrics */
653
Int cur_ppem; /* ppem along the current proj vector */
654
Long scale1; /* scaling values along the current */
655
Long scale2; /* projection vector too.. */
656
Bool cached_metrics; /* the ppem is computed lazily. used */
657
/* to trigger computation when needed */
659
TGlyph_Zone zp0, /* zone records */
665
Bool instruction_trap; /* If True, the interpreter will */
666
/* exit after each instruction */
668
TGraphicsState GS; /* current graphics state */
670
TGraphicsState default_GS; /* graphics state resulting from */
671
/* the prep program */
672
Bool is_composite; /* ture if the glyph is composite */
677
/* latest interpreter additions */
679
Long F_dot_P; /* dot product of freedom and projection */
681
TRound_Function func_round; /* current rounding function */
683
TProject_Function func_project, /* current projection function */
684
func_dualproj, /* current dual proj. function */
685
func_freeProj; /* current freedom proj. func */
687
TMove_Function func_move; /* current point move function */
689
TGet_CVT_Function func_read_cvt; /* read a cvt entry */
690
TSet_CVT_Function func_write_cvt; /* write a cvt entry (in pixels) */
691
TSet_CVT_Function func_move_cvt; /* incr a cvt entry (in pixels) */
693
gsfix_jmp_buf trap; /* Error throw trap. */
702
/********************************************************************/
704
/* Code Range Functions */
706
/********************************************************************/
708
/* Goto a specified coderange */
709
TT_Error Goto_CodeRange( PExecution_Context exec, Int range, Int IP );
710
/* Unset the coderange */
711
void Unset_CodeRange( PExecution_Context exec );
713
/* Return a pointer to a given coderange record. */
714
/* Used only by the debugger. */
715
PCodeRange Get_CodeRange( PExecution_Context exec, Int range );
717
/* Set a given code range properties */
718
TT_Error Set_CodeRange( PExecution_Context exec,
723
/* Clear a given coderange */
724
TT_Error Clear_CodeRange( PExecution_Context exec, Int range );
727
PExecution_Context New_Context( PFace face );
729
TT_Error Done_Context( PExecution_Context exec );
732
TT_Error Context_Load( PExecution_Context exec,
735
TT_Error Context_Save( PExecution_Context exec,
738
TT_Error Context_Run( PExecution_Context exec,
741
TT_Error Instance_Init( PInstance ins );
743
TT_Error Instance_Reset( PInstance ins,
746
TT_Error Instance_Create( void* _instance,
749
TT_Error Instance_Destroy( void* _instance );
751
TT_Error Context_Destroy( void* _context );
753
TT_Error Context_Create( void* _context, void* _face );
755
/********************************************************************/
757
/* Handy scaling functions */
759
/********************************************************************/
761
TT_Pos Scale_X( PIns_Metrics metrics, TT_Pos x );
762
TT_Pos Scale_Y( PIns_Metrics metrics, TT_Pos y );
764
/********************************************************************/
766
/* Component Initializer/Finalizer */
768
/* Called from 'freetype.c' */
769
/* The component must create and register the face, instance and */
770
/* execution context cache classes before any object can be */
773
/********************************************************************/
775
TT_Error Face_Create( PFace _face);
776
TT_Error Face_Destroy( PFace _face);
782
#endif /* TTOBJS_H */