freetype/ftlayout.txt

About FTLayout
==============
FTLayout is a layout engine stacked on FreeType2.  Currently
TrueTypeGX/AAT is supported as a file format.  OpenType is also
supported, but highly experimental.

FTLayout provides an generic interface which is shared by a layout
engine(GXLayout) for TrueTypeGX/AAT and a layout engine(OTLayout)for
OpenType for glyph substitution, one of the text layout function.

See "The TureType Font File"
(http://developer.apple.com/fonts/TTRefMan/RM06/Chap6.html)
about TrueTypeGX/AAT.

About GXLayout
==============
GXLayout provides interface for mort, morx, lcar, format 0, 2 3 kern, 
feat TrueTypeGX/AAT tables. 

We tested GXLayout against "Non-contextual glyph substitution" and
"Ligature substitution" in kochigx-substitute-20040218
fonts. "Non-contextual glyph substitution" in
kochigx-substitute-20040218 fonts represents "vertical
substitution". "Ligature substitution" in kochigx-substitute-20040218
fonts represents "Non-contextual glyph substitution".

We tested GXLayout against "fi" ligature("Ligature substitution") in 
MacOSX's dfonts. 

It seems that Pfaedit can generate TrueTypeGX/AAT font. However, we
have not tested GXLayout against fonts generated by Pfaedit yet.

About OTLayout
==============
(Different from GXLayout)OTLayout is not written from scratch; it
is just applied existing implementation to FTLayout, a newly designed
interface. The existing implementation stands for:

	The code ported by the author of Pango to FreeType2 for using 
	the code in Pango from TrueTypeOpen code in FreeType1
	implemented by FreeType developers.

What we have done is to make fit the existing implementation to
new FTLayout glyph substitution interface. As written above, OTLayout
in FTLayout is highly experimental. We have tested only punctuation
substitution in Japanese vertical writing. Currently OpenType/TrueType
is supported; OpenType/CFF is not supported. Hereafter in this
document we focus on GXLayout.

Install
=======
You have not changed the install procedure. However we recommend to
give --prefix=/somewhere-different-from-/usr-or-/usr/local to
configure command if FreeType2 is already installed on your system.
e.g. --prefix=/opt

We have taken care that we do not change the source/binary interfaces
of FreeType2. However FTLayout development is based on the FreeType
code of HEAD in FreeType2's CVS repository(as of Mon Feb 23 14:30:49
2004). If source/binary interfaces are not compatible between in
FreeType2 on your system and that of HEAD, installing FreeType2 with
FTLayout into /usr/lib or /usr/local/lib will be trouble. Take care.

Demo program
============
fi and gxdemo are bundled as GXLayout demo programs. To build the demo
programs, type following command line in src/gxlayout after installing
FreeType2 with FTLayout:
	  
	  $ make -f demo.mk

fi and gxdemo will be built.

   - fi command
   With rules defined in a font file specified as the first argument
   for fi, try to substitute "fi" glyph string; and print the result
   to stdout. The default value defined in feat table is used as font
   feature settings in substitution. If you want to try different
   settings, gxdemo is suitable.

   Example:

   	$ ./fi /Library/Fonts/Zapfino.dfont 
	-------------------
	File: /Library/Fonts/Zapfino.dfont
	Name: Zapfino
	[IN]f: 536, i: 552
	[OUT]f: 1089, i: 65535<empty>   

   This output stands for
   - [IN] is input glyph string,
   - [OUT] substituted glyph string,
   - ([IN])the glyph id for `f' is 536,
   - ([IN])the glyph id for `i' is 552, and
   - ([OUT])as the result of substitution, we get single glyph which
     is 1089. 536, 552 are ligature into 1089.

   Only FreeType2 with FTLayout and standard C library are used in
   fi.

   - gxdemo
   gxdemo is a tool to inspect tables in a TrueTypeGX/AAT font and 
   the behavior of GXLayout with GUI.

   Run gxdemo with a target TrueTypeGX/AAT font file from a terminal.
   gxdemo's window has multiple tabs.

   In "Features" tab, you can change the feature settings. Pressing
   "Reset" button and the settings are reset; setting are set to the
   default values defined in feat table. With "Run" button, you can
   try to substitute glyphs under the setting given in this "Features"
   tab. Pressing "Run" button, "Input: " prompt is appeared in the
   terminal. Give the glyph ids separated by space and type return key
   at the end of input glyph ids. Then substituted glyph ids are
   printed on the terminal.

   Example:
   	$ ./gxdemo ~/.fonts/kochigx-mincho-subst.ttf 
	Input:       200 19 20 300
	Substituted: 200 14571 65535<empty> 300 

   In "Glyph" tab, you can render a glyph by giving a glyph id.

   In "Dump" tab, you can dump the TrueTypeGX/AAT tables of the font
   in pseudo XML format with pressing "Dump Font Tables" button.  Also
   with pressing "Dump Feature Request" button, you can dump the
   current font feature settings in "Features" tab in a text format.

   Batch dump mode is also available. To dump mort and feat from a
   terminal, type 

   	$ ./gxdemo --batch --table=mort:feat font.ttf  

   We, FTLayout developers used
   mlview(http://www.freespiders.org/projects/gmlview/) to browse
   the XML formated dump datum.

   In "Trace" tab, you can set FreeType2's trace level. To examine
   the process of glyph substitution, set "gxvm" and "gxchain" to 3.

   Different from fi, gxdemo uses gtk+ GUI toolkit. To build gxdemo,
   following libraries are needed:
   - glib-2.0
   - gtk+-2.0
   - libgnomecanvas-2.0
   - popt
   At least Red Hat Linux 9 includes these libraries.

Using FTLayout and GXLayout
===========================
To do glyph substitution in your program, you have to use both
FTLayout interface(as generic interface) and GXLayout interface(as
concrete interface). The symbols in FTLayout have "FTL" as prefix.
The symbols in GXLayout have "GXL" as prefix. Symbols in FTLayout
are declared in include/freetype/ftlayout.h. Symbols in GXLayout
are declared in include/freetype/gxlayout.h. To include these header
files in your source file, you have to obey to the way of FreeType2;
you have to specify the header files in symbols:

      #include<ft2build.h>
      ...
      #include FT_LAYOUT_H
      #include FT_GXLAYOUT_H


The outlines of usage are:

    1. Create a face
       This procedure is the same as before.
       Create a `face' from the target font file after
       initialize the library itself.

    2. Check the existence of substitution tables
       You can check the existence of substitution table
       in the target font by the logical AND operation between
       face::face_flags and FT_FACE_FLAG_GLYPH_SUBSTITUTION.
       
    3. Check the type of layout engine
       You can check whether the type of text layout engine
       is GXLayout or OTLayout by invoking FTL_Query_EngineType.
       Hereafter, we assume the engine type is GXLayout.
       
    4. Create a request
       A `request' is needed in FTLayout to specify the
       font feature settings in substitution. You can create more
       than one requests against one face and specify the font 
       feature settings independently each of them; and activate
       one of them. Invoke FTL_New_FeaturesRequest with a face to
       create a requests. Invoke FTL_Done_FeaturesRequest to release a
       request.

    5. Set the features and settings to the request
       Concrete text layout engine(GXLayout)'s interface is used to 
       specify the font feature settings to a request. Following
       functions are available to specify:

       - GXL_FeaturesRequest_Get_Feature returns a object(feature)
         which represents Nth feature of a face.

       - GXL_FeaturesRequest_Get_Feature_Count returns the number of
       	 features in a face.

       - GXL_Feature_Get_Setting returns a object(setting) which
         requests Nth setting of a feature.
	 
       - GXL_Feature_Get_Setting_Count returns the number of settings
         in a feature.

       - GXL_Feature_Get_Name returns the name of given feature.

       - GXL_Setting_Get_State returns the state (enable or disable)
       	 of given setting.

       - GXL_Setting_Get_Name returns the name of given setting.

       - GXL_Feature_Is_Setting_Exclusive returns whether given
	 setting is exclusive or not.

       These functions may be useful to construct GUI thorough which
       application users can specify the font features settings.
       "Features" tab of gxdemo may be good example to construct 
       GUI.

       The writing direction(vertical or horizontal) have to be
       specified also in FTLayout level. Use

       	  FTL_Set_FeaturesRequest_Direction

       to specify. Whether you have to specify the direction in
       GXLayout level or not depends on the target font file.

    6. Activate request
       After setting a request by functions explained in 5., 
       You have to activate it. Use

       	   FTL_Activate_FeaturesRequest

       to activate a face. (Only one request is active for
       a face at the same time.)

    7. Create input/output glyph array
       FTL_New_Glyphs_Array is used to create a glyph array.
       To substitute two glyph arrays are needed to store
       input glyphs(input) and substituted result(output).

       About the input, you have to set the length and fill the array
       with glyphs by your self. Use


              FTL_Set_Glyphs_Array_Length

       to set the length of glyph array. Use `gid' field of glyph
       array to fill the input glyphs.
       
       The length of output are automatically set by FTLayout.

    8. Substitute
       Invoke 

       	      FTL_Substitute_Glyphs
	      
       with a face, input and output.

Other than 5. are procedures are done in fi command. Therefore fi.c
may be good simple example to substitute glyphs.

TODO
====
- lazy table loading
- verification table data during loading not in 
  substitution time
- more detailing error codes and using them


License
=======
The licenses of FTLayout and GXLayout are the same as that
of FreeType2. About OTLayout, see src/otlayout/README.

Acknowledgments
===============
This development is supported by Information-technology Promotion
Agency, Japan(IPA). We would like to appreciate the supports.

Mitsuru Oka advised us about OpenType and Pango. We would like to
appreciate his advices.

Contact
=======
Masatake YAMATO
<yamato@redhat.com> or <jet@gyve.org>