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