ftlayout.txt - third_party/freetype2 - Git at Google

 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>
	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>