alunitk -- Allegro Unicode Toolkit v0.9 ======================================== by Ky Kimport, 2000 Contents: 1. Introduction 2. Giftware Notice 3. Installing the Grabber Plugin 4. The FNTW Datafile Object 4.1. Creating FNTW-style fonts 4.1.1. Bitmap Format 4.1.2. Grabber Plugin 4.2. Using FNTW-style fonts in your program 4.2.1. Normal Textout Routines 4.2.2. Modified GUI Routines 4.2.3. Limitations and Possible Problems 4.3. FNTW vs. FONT 5. The GNU Unifont 5.1. Where to get it, where to learn more 5.2. Grabber Plugin 6. Future Work / Wish List 7. Contacting Me 1. Introduction ---------------- Anyone who knows me well knows that I'm into foreign scripts as a sort of hobby... so when the new version of Allegro offered Unicode support, I had a field day. After adding a few features to handle foreign scripts in my current project, I thought to myself, "Hey, why not clean this up a bit, document it, give it a bad pun of a name, and send it to my fellow Allegroids?" Hence, alunitk was let loose on the world. Currently, alunitk has support for a new FNTW datafile object which adds character offset and width information to facilitate interconnected scripts (such as Devanagari) and combining accents. It also includes support for the GNU Unicode Bitmap Font in the Grabber. This is an addon for the Allegro game programming library. If you don't have Allegro, Alunitk won't do you any good. For more information on Allegro, visit http://www.talula.demon.co.uk/allegro/ 2. Giftware Notice ------------------- Alunitk is provided as a gift to the Allegro community. You may freely distribute, reverse engineer, decompile incorporate in another program (including commercial programs), or make derivative works from this software. All I ask is that no names are removed from the contributor list. 3. Installing the Grabber Plugin --------------------------------- Copy the contents of alunitk's plugin folder to the Grabber plugin folder (it should be in allegro/tools/plugins), and from a command prompt in your main Allegro directory, type "make grabber" . 4. The FNTW Datafile Object ---------------------------- The FNTW datafile object will get loaded into a standard Allegro FONT structure, and makes use of the mystic renderhook, widthhook, and heighthook fields, so that it can be used with familiar text routines. Details follow... 4.1. Creating FNTW-Style Fonts ------------------------------- 4.1.1. Bitmap Format --------------------- The Bitmap Format for a FNTW is a lot like the traditional 8-bit bitmap font format: characters are read in from a grid, separated by color 255. Color 0 is empty space, and color 1 is what gets drawn. In addition, colors 2 through 7 serve to define width information: Color (in example) Function 0 White Empty Space 1 Black Part of Drawn Character 2 Blue Start of Character 3 Dark Blue Start + Drawn 4 Red Start of Next Character 5 Dark Red Next Start + Drawn 6 Magenta This Start + Next Start 7 Dark Magenta Drawn + This Start + Next Start 255 Gray Character Border You might need to look at the examples provided to get a better idea. Essentially, in addition to drawing the character, you put two more dots down specifying the width of the character. The blue dot from one character will be lined up with the red dot of the character before. If you don't put any dots, it will assume that the character takes up the full width it has been given -- thus, an traditional 8-bit bitmap font will read in correctly as FNTW format. 4.1.2. Grabber Plugin ---------------------- Once you've made the bitmap font, you need to grab it into a datafile using the Grabber, just like a normal font. The interface is a lot like the FONT interface, except that when viewing a font, it gives you two extra values for each character -- 'O', which is the character offset, and 'W' which is the character's width. 4.2. Using FNTW-style fonts in your program -------------------------------------------- 4.2.1. Initialization ---------------------- void register_datafile_fontw(void) This function must be called sometime before you load your datafile. It lets Allegro's built in datafile routines know about the FNTW type. The datafile object will get stored in a normal FONT structure, so to load your font it's the familiar FONT *f = my_datafile[MY_FNTW_OBJECT].dat; 4.2.2. Normal Textout Routines ------------------------------- All of the basic textout functions (textout(), textout_centre(), textout_right(), textout_justify(), and the textprintf_*() equivalents) will work just fine with FNTW, with one exception: Any text_mode except for -1 will cause characters to print out incorrectly. I will rarely use any text_mode other than -1 anyway, but if you're not like me this is something that you will have to watch out for. 4.2.3. Modified GUI Routines ----------------------------- Because several of the GUI routines use opaque text modes (modes other than -1), I have rewritten several of them to only use text_mode(-1) so they will work correctly with both FNTW-style fonts and traditional fonts. Here is a list (each function parallels a built-in GUI function). int dfw_text_proc(int msg, DIALOG *d, int c); int dfw_ctext_proc(int msg, DIALOG *d, int c); int dfw_rtext_proc(int msg, DIALOG *d, int c); int dfw_check_proc(int msg, DIALOG *d, int c); int dfw_radio_proc(int msg, DIALOG *d, int c); int dfw_edit_proc(int msg, DIALOG *d, int c); int dfw_list_proc(int msg, DIALOG *d, int c); int dfw_text_list_proc(int msg, DIALOG *d, int c); int dfw_textbox_proc(int msg, DIALOG *d, int c); 4.2.4. Limitations and Possible Problems ----------------------------------------- Well, like I said before, FNTW doesn't work in text modes other than the transparent -1, so you'll need to do some rectfill()ing if you want your text to have a background. The other problem you might run into is characters hanging over the edges of your boundaries, especially in GUI elements -- you can see this somewhat in the example program and also the grabber. 4.3. FNTW vs. FONT ------------------- As cool as FNTW is, it's no all-around replacement for FONT. FONT allows you to have multicolored/antialiased text, and doesn't run into the problems or limitations I described above. 5. The GNU Unifont ------------------- The GNU Unifont is the brainchild of Roman Czyborra, and is a rather extensive and active Unicode support project. Alunitk provides a grabber plugin for importing GNU Unifont-format fonts. 5.1. Where to get it, where to learn more ------------------------------------------ The GNU Unifont makes its home at http://czyborra.com/unifont/ , along with a very thorough discussion of Unicode implementation (if you'd rather not read it all, though, scroll to the very bottom of the page to get the link to the unifont itself). The Unifont is not included in the Alunitk distribution since, first, it's not mine, and second, it's updated quite a bit and by forcing you to download it from the source you'll get the most current version. 5.2. Grabber Plugin -------------------- The Grabber plugin will allow for Unifont import into both FONT and FNTW data types. The Unifont has a .hex extension -- the plugin will treat all files of type .hex as if they were in the Unifont format. Currently, the only way to import only selected ranges is to hand-crop the file. The format is human-readable, so doing small manipulations like cropping shouldn't pose much of a threat. 6. Future Work / Wish List --------------------------- Bidirectional (BIDI) text support... implementing a full automatic BIDI version of textout has a lot of considerations attatched to it; what I'm thinking of doing is making some kind of directionality tag where the user specifies what is left-to-right and what is right-to-left... Adding some sort of accent hooks to the structure, to allow for correct display of combining accents -- a decent amount of support is available with the current structure, but it still won't look right in all cases. 7. Contacting Me ----------------- All feedback is encouraged! Questions, suggestions for improvement, your own modifications to the library, thank-yous, constructive criticism, ruthless slander... E-mail: kkimport@mail.dotcom.fr I do my best to read the Allegro mailing lists, but I often get behind... if you send something about alunitk to the lists you might want to cc it to me to grab my attention. Alunitk Page: http://tts.cjb.net/djalleg/alunitk.htm Homepage: http://tts.cjb.net/