diff options
Diffstat (limited to 'ftlayout.txt')
| -rw-r--r-- | ftlayout.txt | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/ftlayout.txt b/ftlayout.txt new file mode 100644 index 000000000..d1623fb6a --- /dev/null +++ b/ftlayout.txt @@ -0,0 +1,291 @@ +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> |