summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/docs/user.txt
blob: d24d693b0ae7bb1eac20e7836010ac71dd61387c (plain)
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 ---