← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/vnc4/gutsy

« back to all changes in this revision

Viewing changes to unix/xc/extras/FreeType/docs/user.txt

  • Committer: Bazaar Package Importer
  • Author(s): Ola Lundqvist
  • Date: 2006-05-15 20:35:17 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20060515203517-l4lre1ku942mn26k
Tags: 4.1.1+X4.3.0-10
* Correction of critical security issue. Thanks to Martin Kogler
  <e9925248@student.tuwien.ac.at> that informed me about the issue,
  and provided the patch.
  This flaw was originally found by Steve Wiseman of intelliadmin.com.
* Applied patch from Javier Kohen <jkohen@users.sourceforge.net> that
  inform the user that only 8 first characters of the password will
  actually be used when typing more than 8 characters, closes:
  #355619.

Show diffs side-by-side

added added

removed removed

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