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 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 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 ... #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 or