1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
|
The FreeType Engine
Core Library User Guide
or
How to use the engine in your applications and font servers
---------------------------------------------------
Introduction
I. Basic Concepts
1. Concepts
2. Handles
3. Conventions of use
4. Object classes
II. Extensions
1. What is an extension?
2. Where to find them
3. Writing your own extension
Conclusion
--------------------------------------------------------------------
Introduction
============
This file has been written to present the FreeType core library to
would-be writers of applications and font servers. It first
describes the concepts on which the engine is based, then how to
use it to obtain glyph metrics, outlines and bitmaps.
The last part discusses the ability to add and use extensions to
the core library to get access to supplemental TrueType tables
which are not currently provided by the core engine. If you would
like to write your own extensions, read also the FreeType
developer's guide.
I. Basic Concepts
=================
1. Concepts
-----------
FreeType defines several kinds of structures called `objects',
that are used to manage the various abstractions required to
access and display fonts.
In care of good encapsulation, these objects are not directly
accessible from a client application. Rather, the user receives
a `handle' for each object he or she queries and wants to use.
This handle is a stand-alone reference; it cannot be used like a
pointer to access directly the object's data.
2. Properties
-------------
It is however possible to obtain and set object properties
through several functions of the API. For example, you can
query a face object's properties with only a handle for it,
using the function TT_Get_Face_Properties().
Note that the data will be returned in a user-allocated
structure, but will also contain pointers addressing directly
some data found within the object.
A client application should never modify the data through these
pointers! In order to set new properties' values, the user must
always call a specific API function to do so, as a certain
number of other related data might not appear in the returned
structure and imply various non-visible coherency and coercion
rules.
3. Conventions of use
---------------------
o All API functions have their label prefixed by `TT_', as well
as all external (i.e. client-side) types.
o To allow the use of FreeType's core engine in threaded
environments, nearly all API functions return an error code,
which is always set to 0 in case of success.
The error codes' type is `TT_Error', and a listing of them is
given in the API references (see `apiref.txt' and
`apirefx.txt').
Some functions do not return an error code. Their result is
usually a value that becomes negative in case of error (this
is used for functions where only one kind of error can be
reported, like an invalid glyph index).
An important note is that the engine should not leak memory
when returning an error, e.g., querying the creation of an
object will allocate several internal tables that will be
freed if a disk error occurs during a load.
o A handle is acquired through API functions labeled along the
names:
TT_Open_xxxx(), TT_New_xxxx()
where `xxxx' is the object's class (Face, Instance, etc).
Examples:
TT_Open_Face(), TT_Open_Collection(),
TT_New_Instance(), TT_New_Glyph()
o A handle is closed through an API labeled
TT_Close_xxxx() or TT_Done_xxxx()
where `xxxx' is the object's class (Face, Instance, etc).
Examples:
TT_Close_Face(), TT_Done_Instance(), TT_Done_Glyph()
o Properties are obtained through an API labeled
TT_Get_xxxx_yyyy()
where `xxxx' is the object's class, and `yyyy' its property.
Examples:
TT_Get_Face_Properties(), TT_Get_Instance_Metrics()
TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap()
o Properties are set through an API labeled
TT_Set_xxxx_yyyy()
where `xxxx' is the object's class, and `yyyy' its property.
Examples:
TT_Set_Instance_Resolutions(),
TT_Set_Instance_CharSize()
4. Object Classes
-----------------
The following object classes are defined in this release of the
engine:
o The Engine objects
The FreeType library can be built to be completely re-entrant,
even though its default build doesn't support threads (more on
this in the `threads.txt').
As a consequence, it is possible to open several instances of
the library, called `engines'. Each engine has its own set of
current objects (faces, instances, etc.), and there is no
sharing between them.
The idea is that the library could be compiled as a shared
library or DLL, and then be able to provide several distinct
engines to independent client applications. In this case,
each client program must create its own engine with
TT_Init_FreeType() to hold its data.
Closing an engine will destroy _all_ objects that were
allocated since its opening, releasing all resources, etc.,
with the exception of user-allocated outline objects.
o The Face objects
A face contains the data that is specific to a single TrueType
font file. It presents information common to all glyphs and
all point sizes like font-specific metrics and properties.
You can open a face object by simply giving a pathname to the
TrueType file. You can later close (i.e. discard) the face
object.
You can also open a single face embedded in a TrueType
collection.
See also:
TT_Open_Face(), TT_Open_Collection(), TT_Close_Face(),
TT_Get_face_Properties()
o The Instance objects
An instance is also called a `pointsize' or a `fontsize' in
some windowing systems. An instance holds the information
used to render glyphs on a specific device at a given point
size; it is always related to an opened face object.
For instance, if you want to generate glyphs for text from the
same typeface at `sizes' of 10 and 12 points, all you need is
one face object, from which you will create two distinct
instances.
A device is defined by its horizontal and vertical resolution,
usually specified in dots per inch (dpi). A point size is a
scaling number, given as _absolute_ values in points, where 1
point = 1/72 inch.
The `pixel' size, also known as the `ppem' value (for Points
Per EM square) is computed from both the device resolution and
the point size. It determines the size of the resulting glyph
bitmaps on your screen or sheet of paper.
The default device resolution for any new instance is 96dpi in
both directions, which corresponds to VGA screens. The
default point size is 10pt. The high-level API allows you to
change this whenever you want for any given instance object.
Note that closing a face object will automatically destroy all
its child instances (even though you can release them yourself
to free memory).
See also:
TT_New_Instance(), TT_Done_Instance(),
TT_Get_Instance_Metrics(), TT_Set_Instance_Resolutions(),
TT_Set_Instance_Pointsize()
o The Glyph objects
A Glyph object is a _container_ for the data that describes
any glyph of a given font. This means that it typically
holds:
- Glyph metrics information, like bounding box or advance
width.
- Outline arrays sized large enough to hold any glyph from the
face. This size is extracted from the face's internal
`maxProfile' table to optimize memory costs.
- Other important parameters related to the `fine' rendering
of the glyphs. This includes things like the
dropout-control mode used at low sizes.
- And it doesn't contain a bitmap or a pixmap!
A glyph object is used to load, hint, and rasterize a single
glyph, as taken from the font file.
See also:
TT_New_Glyph(), TT_Done_Glyph(), TT_Get_Glyph_Metrics(),
TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap(),
TT_Get_Glyph_Pixmap()
o The Character Map (CharMap) handle
Glyphs can be indexed in a TrueType file in any order,
independently of any standard character encoding, like ASCII
or Unicode. For this reason, each file comes with one or more
character mapping tables, used to translate from one specific
encoding's character codes to font glyph indices.
There are many encoding formats, and each one can be
distinguished by two values:
- its platform ID
- its platform-specific encoding ID
Their values are defined in the TrueType specification and
won't be commented there. The FAQ lists the most commonly
used (platform,encoding) pairs.
It is possible to enumerate the charmaps provided by a
TrueType font and to use any of these to perform translations.
The charmaps are loaded into memory only on demand to save the
space taken by the maps that are not needed on your system.
They are part of the face object, however.
This means that even though a charmap can be accessed through
a handle (obtained through the TT_Get_CharMap() function), it
isn't a stand-alone object. For example, you never need to
de-allocate it; this is automatically done by the engine when
its face object expires.
See also:
TT_Get_CharMap_Count(), TT_Get_CharMap_ID(),
TT_Get_CharMap(), TT_Char_Index().
o The Outline Objects
An outline is a vector representation of a glyph. It is made
of several control points joined by line segments and Bezier
arcs, themselves gathered in closed paths called `contours'.
The outline have also several flags, or attributes, which are
used by the scan-line converter to select the best rendering
algorithms to convert the glyph's bitmap.
Unlike other objects in FreeType, outlines aren't managed
through handles, but directly with the structure `TT_Outline',
defined for client applications. Each glyph container
contains an outline sized large enough to hold any glyph from
its parent face. Client applications can access it with
TT_Get_Glyph_Outline(). However, one can also create its own
outlines if needed with TT_New_Outline() and
TT_Clone_Outline().
Note that user-created outlines are NOT tracked by the
library. Hence, the client must release them himself with one
or more calls to TT_Done_Outline().
A various number of methods/operations are defined for the
outline class to simplify its management.
IMPORTANT NOTE: **********************************************
The definition of TT_Outline may change in the future.
Developers are thus advised to always use the outline
methods provided by the API rather than reading or setting
data themselves.
**************************************************************
See also:
TT_New_Outline(), TT_Clone_Outline(), TT_Copy_Outline(),
TT_Done_Outline(), TT_Get_Outline_BBox(),
TT_Get_Outline_Bitmap(), TT_Get_Outline_Pixmap(),
TT_Translate_Outline(), TT_Transform_Outline()
o Bitmaps and Pixmaps
One very important aspect of FreeType is that it is unable to
create bitmaps on its own. Rather, it is up to the client
application to do it, and pass a reference, in the form of a
TT_Raster_Map, to the scan-line converter (the component in
charge of generating bitmaps from outlines).
Hence the importance of the TT_Raster_Map structure, which
layout is:
struct
{
int rows; /* number of rows */
int cols; /* number of columns (bytes) per row */
int width; /* number of pixels per line */
int flow; /* bitmap orientation */
void* bitmap; /* bit/pixmap buffer */
long size; /* bit/pixmap size in bytes */
} TT_Raster_Map;
- The `rows' field contains the total number of rows in the
bitmap.
- The `width' field gives the number of pixels per row (a bit
or a byte, depending on the map's nature).
- The `cols' field gives the number of columns, i.e. bytes,
taken by each row in the map buffer.
IMPORTANT: The `cols' field must be a multiple of 4 for
pixmaps!
Typically, its value should be `(width+7)/8' for bitmaps,
and `(width+3) & -4' for pixmaps.
- The `flow' field gives the map's vertical orientation.
For example, if the first bytes of the bitmap buffer pertain
to its upper row, the flow is said to be going `down', and
the field should take the value `TT_Flow_Down'. If these
bytes pertain to its lowest row, the flow is going `up', and
the value is `TT_Flow_Up'.
As an example, the PC video modes use a `down' flow, where
the first VRAM byte corresponds to the upper and leftmost
corner of the screen.
- The `bitmap' field is a typeless pointer to the map's
buffer.
- The `size' field contains the buffer's size in bytes. It is
usually computed as follows:
size = rows * cols;
NOTE: For bitmaps, the leftmost-pixel is related to the
highest (i.e. most significant) bit of its byte.
There is currently no support for the opposite
convention found in some systems.
(It can be easily added if you really need it, just
ask the development team.)
II. Step-by-step Example
========================
Here is an example to show, step by step, how a client application
can open a font file, set one or several instances, load any
glyph, then render it to a bitmap.
1. Initialize the engine
------------------------
This is the first thing to do. You need to initialize an engine
through a call to TT_Init_FreeType(). This function will set up
a various number of structures needed by the library.
This allocates about 68kByte, of which 64kByte are dedicated to
the scan-line converter's `render pool', a workspace used for
bitmap generation. Note that even though this space is bounded,
the raster is able to render a glyph to any size or bitmap, even
horribly huge ones.
NOTE: You can reduce the size of this pool by modifying the
constant RASTER_RENDER_POOL in the file `ttraster.c'. A
smaller pool will result in slower rendering at large
sizes. Take care of never assigning a value smaller than
4kByte however, as bugs may start to lurk in!
Example:
TT_Engine engine;
error = TT_Init_FreeType( &engine );
if ( error )
{
printf( "could not create engine instance\n");
...
}
2. Initialize the extensions you need
-------------------------------------
FreeType provides several extensions which are optional,
separately compilable components to add some rare features to
the engine and its API.
You need to explicitly initialize the extensions you want to
use. Each extension must provide an initialization function,
following the naming convention:
TT_Init_xxx_Extension( engine );
where `xxx' is the extension's `kind'.
Example:
error = TT_Init_Kerning_Extension( engine );
if ( error )
...
3. Open the font file
---------------------
There are two ways to open a font face, depending on its file
format:
- If it is a TrueType file (ttf), you can simply use the API
named TT_Open_Face(), which takes the file's pathname as
argument, as well as the address of the returned face handle.
Check the returned error code to see if the file could be
opened and accessed successfully.
TT_Face face; /* face handle */
error = TT_Open_Face( engine, "/fonts/arial.ttf", &face );
if ( error )
{
printf( "could not open the file\n" );
...
}
- If the font is embedded in a TrueType collection (ttc), you
can use the API named TT_Open_Collection(), which takes also
the font's index within the collection's directory.
TT_Face face; /* face handle */
/* Load the collection's second face (index=1) */
error = TT_Open_Collection( engine, "/fonts/mingli.ttc",
1, &face );
if ( error )
{
printf( "could not open the file\n" );
...
}
- Finally, when you do not know the number of faces embedded in
a TrueType collection, the following technique can be used:
o Call TT_Open_Face() with the collection file's pathname.
This API recognizes collections automatically and always
return a handle for its first embedded font.
o Get the face's properties through TT_Get_Face_Properties().
These contain, among other things, the total number of fonts
embedded in the collection, in its field `num_Faces'.
TT_Face face; /* face handle */
TT_Face_Properties props; /* face properties */
/* open the first collection font */
error = TT_Open_Face( engine, "/fonts/mingli.ttc",
&face );
if ( error )
{
printf( "could not open the file\n" );
...
}
/* Get the face properties */
TT_Get_Face_Properties( face, &props );
/* Now print the number of faces */
printf( "there are %d faces in this collection file\n",
props->num_Faces );
4. Create an instance from the face object
------------------------------------------
You must create an instance (also known as a `pointsize') which
contains information relative to the target output device's
resolutions and a given point size.
o The instance object is created through TT_New_Instance():
TT_Instance instance;
error = TT_New_Instance( face, &instance );
if ( error )
{
printf( "could not create instance\n" );
...
}
TECHNICAL NOTE: Creating a new instance executes its font
program. This can fail if the font is broken.
Never assume that the error code returned here
is always 0.
o You must set the instance's properties to suit your needs.
These are simply its device resolutions, set through
TT_Set_Instance_Resolutions(), and its point size, set through
TT_Set_Instance_CharSize():
/* Set the target horizontal and vertical resolution to */
/* 300dpi in each direction (typically for a printer). */
/* A fresh instance's default resolutions are 96dpi in */
/* both directions. */
error = TT_Set_Instance_Resolutions( instance, 300, 300 );
if ( error )
{
printf( "could not set resolution\n" );
...
}
/* Now set the point size to 12pt. Default is 10pt. */
/* Don't forget that the size is expressed in 26.6 fixed */
/* float format, so multiply by 64. */
error = TT_Set_Instance_CharSize( instance, 12 * 64 );
if ( error )
{
printf( "could not set point size\n" );
...
}
TECHNICAL NOTE: These calls may execute the font's `prep'
program, which can fail if the font is broken.
Never assume that the error code returned is
are always 0.
o You can also set the instance's transformation flags to tell
the glyph loading function that you are going to perform a
transformation (like rotation or slanting) on the glyph. Note
that the glyph loader doesn't perform the transformation. It
only informs the glyphs' hinting instruction streams about
these flags which may use it to disable or enable various
features (grid-fitting, drop-out control, etc).
Use e.g.
TT_Set_Instance_Transforms( FALSE, TRUE );
to indicate that you're going to stretch, but not rotate, this
instance's glyphs. Default is, of course, both FALSE.
5. Create a glyph container
---------------------------
You need a glyph object to serve as a container for the glyphs
you want to load from the face. This is done simply by
TT_Glyph glyph; /* glyph object handle */
error = TT_New_Glyph( face, &glyph );
if ( error )
{
printf( "could not create glyph\n" );
...
}
6. Find your platform's character mappings
------------------------------------------
Each font file can come with one or more character mapping
tables, used to convert character codes to glyph indices. You
must know the values of the `platformID' and `encodingID' as
defined in the TrueType specification for your platform. For
example, Windows Unicode encoding is (platform:3,encoding:1),
while Apple Unicode is (platform:0,encoding:0). Both formats
differ in internal storage layout and can be used transparently
with the same inputs with FreeType.
The function TT_Get_CharMap_Count() returns the number of
character mappings present in a face. You can then enumerate
these with the function TT_Get_CharMap_ID(). Once you've found
a mapping usable for your platform, use TT_Get_CharMap() to
return a TT_CharMap handle that will be used later to get glyph
indices.
7. Load the glyph
-----------------
The glyph loader is easily queried through TT_Load_Glyph().
This API function takes several arguments:
o An instance handle to specify at which point size and
resolution the loaded glyph should be scaled and grid-fitted.
o A glyph container, used to hold the glyph's data in memory.
Note that the instance and the glyph must relate to the _same_
font file. An error would be produced immediately otherwise.
o A glyph index, used to reference the glyph within the font
file. This index is not a platform specific character code,
and a character's glyph index may vary from one font to
another. To compute glyph indices from character codes, use
the TT_CharMap handle created in section 6 with
TT_Char_Index().
We strongly recommend using the Unicode charmap whenever
possible.
o A load mode, indicating what kind of operations you need.
There are only two defined for the moment:
TTLOAD_SCALE_GLYPH:
If set, this flag indicates that the loaded glyph will be
scaled (according to the instance specified as an
argument) to fractional pixel coordinates (26.6). If not,
the coordinates will remain integer FUnits. Please refer
to the TrueType specification and the FreeType header
files for more details on the 26.6 format and other data
types.
TTLOAD_HINT_GLYPH:
This flag is only in effect if the TTLOAD_SCALE_GLYPH flag
is set. It indicates that the glyph must also be `hinted'
resp. `grid-fitted' for better display results. Note that
this also means that the glyph metrics will be
grid-fitted, including the bounding box.
You can simply `or' the flags. As most applications will
require both flags to be set, the constant TTLOAD_DEFAULT is
defined as:
#define TTLOAD_DEFAULT (TTLOAD_SCALE_GLYPH | \
TTLOAD_HINT_GLYPH )
Example:
error = TT_Load_Glyph( instance, glyph, 36,
TTLOAD_DEFAULT );
if ( error )
{
printf("could not load the glyph\n");
...
}
8. Query glyph properties
-------------------------
You're then able to query various glyph properties:
o The glyph metrics can be obtained through
TT_Get_Glyph_Metrics(). The data returned in the metrics
structure is:
- the glyph's left side bearing (bearingX)
- the glyph's top side bearing (bearingY)
- the glyph's advance width (advance)
- the glyph's bounding box (bbox)
These values are expressed in 26.6 pixel units when the glyph
was loaded with scaling, or in FUnits if not. To obtain
vertical metrics you should use the function
TT_Get_Glyph_Big_Metrics().
o The glyph outline can be queried through
TT_Get_Glyph_Outline(). This can be useful to process the
point coordinates (e.g. applying stretching or rotation) with
functions like TT_Apply_Outline_Matrix() or
TT_Apply_Outline_Translation(). Note that these functions do
not recompute a glyph's metrics after the transformation!
The outline's structure is described in the reference
`apiref.txt'.
A bitmap or pixmap for the glyph can be queried with the API
functions TT_Get_Glyph_Bitmap() and TT_Get_Glyph_Pixmap().
These functions take a glyph handle as an argument, as well as
a bitmap/pixmap description block and two offsets.
The target map is described through a TT_Raster_Map object,
which structure is defined in the reference (see
`apiref.txt'). The offsets are given in the same units as the
points coordinates and glyph metrics: 26.6 pixel units for a
scaled glyph, and FUnits for an unscaled one.
IMPORTANT TECHNICAL NOTE: If the glyph has been scaled and
hinted, the offsets _must_ be
multiples of 64 (i.e. integer pixel
offsets). Otherwise, you would ruin
the grid fitting (which usually
results in ugly glyphs).
Example:
TT_Glyph_Metrics metrics;
TT_Outline outline;
TT_Raster_Map bitmap;
TT_Get_Glyph_Metrics( glyph, &metrics );
TT_Get_Glyph_Outline( glyph, &outline );
/* set up the bitmap */
...
TT_Get_Glyph_Bitmap( glyph, &bitmap, 0, 0 );
9. When you are done
--------------------
o You can close any font face object with TT_Close_Face(). This
call will automatically discard its child instances, glyphs
and charmaps.
o You can also close the engine with a single call to
TT_Done_FreeType(). This will release _all_ objects that were
previously allocated (with the exception of user-created
outlines), and close all font files, as well as extensions
that were inited for it.
III. Extensions
===============
1. What is an extension?
------------------------
FreeType allows you to access a various number of TrueType
tables, as well as to render individual glyphs. However:
1. It doesn't perform some high-level operations, like
generating a string text from many individual glyphs.
2. It doesn't perform kerning (which can be needed by operations
mentioned in item 1).
3. It doesn't give access to all the defined TrueType tables,
especially the optional ones.
While item 1 is a feature that will never go into FreeType's
core engine, which goal is to provide easy access to font data
and rendering _individual_ glyphs, point 2 and 3 can be added to
the engine's features through extensions.
An extension is simply a small piece of code that extends the
engine's abilities and APIs. It is possible to extend the
engine without touching the core's source code, this is
described in chapter 3 below.
2. The two kinds of extensions
------------------------------
There are basically two kinds of extensions, which require
different implementations.
a. API extensions
An API extension is a set of functions that extend the
FreeType core API to give access to tables that are already
loaded by the engine, but not provided for now. An example of
such data can be:
- the horizontal metrics table (hmtx)
- the `gasp' table
This kind of extension is made of:
o an API extension header file, following the usage convention
introduced here (all labels prefixed with `TT_'), and which
will be included by the clients which want to use the
extension. By convention, such header names begin with
`ftx' (for FreeType eXtension).
Examples: ftxgasp.h, ftxhmtx.h
o One or more functions used to give access to the tables that
are already loaded and managed by the engine. They usually
only copy pointers to the target structure given by the
client application since these structures are not accessible
through the 'normal' API. An API extension doesn't need to
be initialized before being used.
b. Engine extensions
It can sometimes be useful to load and manage several tables
that are not considered by the core engine. These extensions
need to provide additional functions to fit into FreeType's
internal object management model, and are more sophisticated
than API extensions.
An example is given in this distribution to provide kerning
support (or more technically spoken, access to the kerning
tables found within the TrueType files). It is made of:
o An API extension providing new interfaces to the client
applications that need it. See the file `ftxkern.h'
resp. `apirefx.txt'.
o A specific implementation, providing services to create,
load, and manage kerning tables as additional parts of a
face object. In the case of kerning, the directory of
tables is loaded when the face is opened, and tables
themselves are fetched from the file on demand. This
implies several `hooks' in the core engine. See the files
`ttkern.h' and `ttkern.c'. These are called `engine
extensions'.
o A specific extension initialization function, namely
TT_Init_Kerning_Extension(), that must be called after an
engine's creation, and before any face object allocation.
This function will `register' the extension within the
engine and make its API workable.
3. Writing your own extensions
------------------------------
As it was suggested earlier, writing an engine extension is a
delicate process, as the additional code must follow a certain
number of design rules, presented in the FreeType developer's
guide. Unfortunately, there is currently no extension writer's
guide.
By writing your own extensions, it will be possible to support
more advanced TrueType formats like TrueType GX or OpenType in a
near future, without having to torture the engine core source at
each iteration.
If you encounter some difficulties when trying to create your
own extension, please read the core source file carefully, and
in the event that you may need changes that are not fitted to
the current extension mechanism, do not hesitate to contact the
authors at `devel@freetype.org'.
Conclusion
==========
The engine source code has become rather stable since now, and
its quality compares very favorably to Windows and the Macintosh
rasterizers. Its internals will continue to change, though very
slowly, even if the API isn't expected to grow much in a near
future.
FreeType is really a glyph-oriented TrueType driver. Its
purpose is to open and manage font files in order to load single
glyphs and render them as cleanly as possible. A number of
features, important to developers, like text string rendering,
font mapping and underlining/stroking, to name a few, aren't
provided there even though they'd be highly appreciated.
We hope you have success and fun using this engine. Much time
has been taken to make it one of the best in its genre.
Remember that it is not intended to be a complete font server or
text rendering library, but a pretty solid base for these kinds
of applications, as well as others.
We thank you for your time and consideration.
David Turner, Robert Wilhelm, Werner Lemberg,
and all the FreeType enthusiasts...
--- End of user.txt ---
|