Glyph Keeper - A text rendering library

Glyph Keeper

Latest version: 0.25 (March 23, 2005)
Home | Introduction | License | Screenshots | Files | Compiling | Manual | Reference | Examples | Future | Thanks | Links | Guestbook

User's Manual

  • Getting started
  • Rendering text
  • Setting text properties
  • Using glyph cache
  • Character remapping
  • Allegro-specific usage of Glyph Keeper

Getting started

Before we start

First of all I suppose that you already succeeded compiling Glyph Keeper. You should have 'glyph.o' (or 'glyph.obj') file, don't forget to link it to your program. Also you should link FreeType and your target library - Allegro or SDL. (There is also a file IO target, intended for testing your Glyph Keeper / FreeType installation. It needs nothing more than 'stdio' for output.)

Including Glyph Keeper header file

Every source file that will use Glyph Keeper's routines, should have #include "glyph.h" in the begining. It may be #include <glyph.h> if you already copied 'glyph.h' into your compiler's 'include' directory. Or it may be #include "glyph-keeper/include/glyph.h" if you placed Glyph Keeper files under the 'glyph-keeper' directory.

Unless your target is file IO, you should specify it somewhere. If you are using Glyph Keeper with Allegro, you should add #define GLYPH_TARGET GLYPH_TARGET_ALLEGRO before including glyph.h. Or it may be -DGLYPH_TARGET=GLYPH_TARGET_ALLEGRO in the compiler command line. For SDL do the same, just put GLYPH_TARGET_SDL instead.

Compatibility with older Glyph Keeper versions

Glyph Keeper is evolving and sometimes API changes are necessary, but the old API is usually still available through the bunch of #defines. There is a macro GLYPH_NO_LEGACY, that you can define in your program before including "glyph.h" to disable compatibility with the old messy API.

Checking Glyph Keeper version

glyph.h defines a few macros for this. For example, in Glyph Keeper version 0.21.3 they are:

#define GK_VERSION_MAJOR  0
#define GK_VERSION_MINOR  21
#define GK_VERSION_PATCH  3
#define GK_VERSION_STR    "0.21.3"
#define GK_DATE_STR       "2005-02-07"

Initializing / Finalizing

Often you must call some 'init()' and 'done()' functions before and after using a library. Glyph Keeper does not require this. Initialization will happen when you first call Glyph Keeper routine. Cleanup code will be registered with atexit() and will be called at program shutdown. But if for some reason you need to control the order of things happening, you can do it with gk_library_init() and gk_library_cleanup().

Setting font search path

When you open a font from file, you provide a file name, and Glyph Keeper looks for this file in current directory and opens it. But sometimes it is convenient to keep font files in the same place, shared between multiple programs. Glyph Keeper lets you specify a font search path - list of directories where Glyph Keeper will look for a font file that you are trying to open. The font search path is set with gk_set_font_path() function.

You can set list of several directories, separate them with semicolon ';'. Always include the last slash character for each directory. For example, on Windows you may call

gk_set_font_path("C:\\fonts\\;C:\\WINDOWS\\Fonts\\");

After that when you try to load, for example, "times.ttf", it will be first searched in the current directory, then in C:\fonts, and finally in C:\WINDOWS\Fonts.

Font search path is empty by default. You can set it to 0 or to an empty string to make it empty again.

Loading a font from file

GLYPH_FACE *face = gk_load_face_from_file("arial.ttf",0); if (!face) { /* can't load -> complain, recover.. */ }

A pointer to GLYPH_FACE struct is used to refer to the loaded font face. You should always check returned value, 0 returned means failure.

Loading a font from a memory buffer

GLYPH_FACE *face2 = load_face_from_memory(data,size,0);

This will load font face not from a file, but from memory location. It is helpful if you use some special way to distribute fonts with your program, for example if you compress them and pack together into a datafile.

Creating a renderer

In Glyph Keeper all text properties are organized in one structure – GLYPH_REND. Such properties include font face, font size, color, angle, transparency, rendering mode (monochrome or antialiased, hinted or not) and some more. So, the way is to set up once a renderer object and then use it to render text with the same settings. Naturally, you can have several renderers with different settings and use them in any order. Also, you can change any of the renderer's properties and continue using it. Creating a renderer:

GLYPH_REND *rend = gk_create_renderer(face,0); if (!rend) { /* can't create -> complain, recover.. */ }

Always check its return value, 0 means failure (although the only reason to fail may be out of memory). Created renderer is immediately ready to use, if you passed a valid FONT_FACE* as a first parameter. New renderer will have all settings set to default values, you will probably need to change size, color, etc.

Rendering text

Printing out a single character

When you are going to print out some text, all text properties should be already configured in a renderer object. Then only minimum information will be passed into rendering function: a target bitmap, a renderer object, a text to print and coordinates:

gk_put_char(bmp,rend,'A',100,100);

This code will draw a capital 'A' on the bitmap pointed by 'bmp'. Left top corner of 'A' glyph will appear at the bitmap coordinates (100,100). Use gk_put_char_center() if you want a character centered at (100,100).

Rendering a single character

int x = 100<<6;
int y = 100<<6;
gk_render_char(bmp,rend,'A',&x,&y);

This prints a single 'A' to the bitmap. The difference from put_char() is that the coordinates x and y are passed by reference, and specify text origin point instead of left-top corner. After the character is printed out, the coordinates are changed to become the origin point of next character to be printed. This lets you print out a line of text by calling render_char() for each character in a line. Like this:

int x = 100<<6;
int y = 100<<6;
gk_render_char(bmp,rend,'H',&x,&y);
gk_render_char(bmp,rend,'e',&x,&y);
gk_render_char(bmp,rend,'l',&x,&y);
gk_render_char(bmp,rend,'l',&x,&y);
gk_render_char(bmp,rend,'o',&x,&y);

Please notice that "<<6", it is important. It means that 'x' and 'y' are expressed in 1/64th of a pixel The above code will start printing at (100,100) position, so it sets (x,y) to (100*64,100*64). (As you know 100<<6 is another way to say 100*64). If the coordinates were passed in integer pixels, a significant rounding error might have been accumulated during the angled text output. Whole text baseline might have drifted to the one side or another. Subpixel accuracy helps to avoid this problem.

Rendering a line of text

gk_render_line_utf8(bmp,rend,"Hello, World!",100,200);

This code will print "Hello, World!" to the bitmap 'bmp' with the font, color and other settings from 'rend'. The (100,200) point is used as text origin, similar to render_char(). This function expects coordinates in integer pixels, and it takes them as values, not pointers.

There are also UTF-16 and UTF-32 versions of this function. UTF-32 example:

unsigned text[] = {'I','b','a','n','e','z','!',0}; gk_render_line_utf32(bmp,rend,text,100,200);

Setting text properties

Setting font size

gk_rend_set_size_pixels(rend,24,24);

or

gk_rend_set_size_subpixel(rend,24<<6,24<<6);

This will set renderer's text size to 24x24 pixels. But what thing exactly becomes 24x24? It is the font's EM box, which historically means size of capital 'M'. These days it is not always the case, and fonts may look rather different at the same EM size.

You can set horisontal and vertical size independently. You may need it if you use graphics mode with non-square pixels, like 640x400, or just if you want letters to appear longer or wider than they really are.

Note, that text size is applied before text rotation. If you set text size to 24x40 (narrow letters), the letters will remain narrow in whatever angle you print them. It means that for angled text (printed along non-horisontal baseline) you can't workaround non-square pixels by setting special text size.

I will say again, to make clear. Currently angled text will look distorted in non proportional device resolutions, like 640x400 (unless your screen is really 640x400 in physical size). In future I may add independent setting for device resolution, so it will work fine. But for now you'd better avoid rendering angled text on non-proportional display.

Use gk_rend_set_size_subpixel() if you need subpixel accuracy in setting size.

Setting text color

You are probably used to specify text color each time you render text. This is how Allegro, AllegTTF and AllegroFont work. Glyph Keeper way is different - text color is specified once in the renderer, and then automatically used for each subsequent text output with that renderer.

gk_rend_set_text_color(rend,255,255,0);

This example will set text color to yellow (red = 255, green = 255, blue = 0). These color values are independent from your current color depth, they always are from 0 to 255. Black color is (0,0,0), white is (255,255,255), irrespective of the graphics mode you currently use. Of course, if you are rendering to the 8-bit bitmap, you may not see the exact color you specified in renderer - a nearest palette color will be used. But if later you use the same renderer with truecolor bitmap you get the right color.

Setting text transparency

Glyph Keeper can render transparent text, like in this example. Text letters are blended with the original image, so both can be seen. To enable transparent rendering you need to change renderer's alpha transparency setting - a number which spans from 0 to 255. 255 means opaque mode, no background will be visible, this is the default setting for every newly created renderer. 0 means actually no rendering is done, the background is left intact. Setting transparency to any number from 1 to 254 will enable transparent rendering:

gk_rend_set_text_alpha(rend,127);

Transparent rendering will work in any color depth except 8-bit. In 8-bit mode always opaque text will be produced. If you know what you are doing you will not want to render transparent text in 8-bit mode anyway. (But if you really need it you can first render it in some hicolor mode and then convert to 8-bit). For hi/true-color modes, 16-bit and 32-bit rendering is already optimized and is much faster than 15 or 24-bit.

Although you can do this, it's better not to render transparent text directly on screen or video bitmap. The reason is that transparent rendering involves both reading and writing to the bitmap, which is usually much slower for video RAM. Also, Glyph Keeper is not fully tested with different video hardware, banked VESA modes, X-modes and so on.

Setting color and transparency together

gk_rend_set_text_alpha_color(rend,0x9F01FF9C);

This line is taken from the example code. It sets transparency to 0x9F and color (r,g,b) to (0x01,0xFF,0x9C). Calling this function works a bit faster than setting transparency and color separately, because 0x9F01FF9C is exactly how it will be stored in the renderer structure anyway.

Using glyph cache

Introduction

Glyph cache is most important part of Glyph Keeper. It was the main purpose of writing it, and that's why it is named 'Glyph Keeper'. I was using other font libs and I once became frustrated about the way they did caching (among other things), if they did it at all. Then I started crafting some structures that would do what I wanted, and it ended up as a library.

Glyph Keeper's glyph cache is presented by a GLYPH_KEEP structure. That's it, glyph cache is a distinct entity, not bound to a specific renderer or font face. Cache object exists on its own, providing caching facility to one or more renderers. This works even if renderers have different font faces and sizes, so the whole program can be served by a single cache object (it's even not a bad idea to use only one cache object).

Creating cache object

GLYPH_KEEP *keep; keep = gk_create_keeper(1000,2*1024*1024); if (!keep) { /* complain, recover */ )

When you create a glyph cache, you specify its maximum storage capacity: maximum number of glyphs it can store and maximum memory space it can use. In this example a cache is created with the limit of 1000 stored glyphs and 2 MB of maximum memory usage. It means that whenever a new glyph is going to be stored in cache, and <number of currently stored glyphs is 1000> OR <cache memory consumption would exceed 2 MB after that new glyph is stored>, in such case some (one or more) of least recently used cached glyphs will be first deleted from a cache, until it becomes possible to add a new glyph to the cache without exceeding the limits.

If you pass 0 in place of glyph number limit, there will be no upper limit for number of stored glyphs. If you pass 0 as memory limit, there will be no limit for occupied memory. Depending on the pattern of text rendering usage of your program, you may choose limiting only glyph number, only memory usage, or using both limits of a glyph cache (or even having cache with no limitations). Beware, that if you use only glyph count limit, glyph cache memory usage may grow very large, if you start using larger font sizes. So, for a common case usage I recommend having memory-limited cache, with unlimited number of glyphs:

keep = gk_create_keeper(0,2*1024*1024);

Conecting a glyph cache to a renderer

As you know, every aspect of text rendering is specified in a renderer object (GLYPH_REND structure). This includes glyph caching. Easiest way of setting a renderer to use cache is to provide a cache object when creating a renderer:

GLYPH_REND *rend = gk_create_renderer(face,keep);

Another way is to attach a cache to already created renderer:

gk_rend_set_keeper(rend,keep);

Once a renderer has been set to use cache, all glyphs it is asked to render are first looked up in cache. If the glyph is found it is returned to the drawing routine immediately, otherwise it is rendered, added into the cache, and returned. Glyphs are arranged in cache in most recently used order - whenever a glyph is successfully found in cache it is moved to the begining of the list.

A single cache object may be used with several renderers. In such case all glyphs are arranged in a single most-recently-used ordered list. If one of the renderer is starting to be used a lot, it may drive other renderer's glyphs out of cache.

If you need you can always return a renderer into its original un-cached mode:

gk_rend_set_keeper(rend,0);

Precaching

Although all rendered glyphs are automatically placed into cache (if the renderer is connected to cache object), sometimes you may prefer to put glyphs into the cache manually. This may be useful if you expect a CPU-intensive work soon, that will also require some text rendering. In such case you can prepare the character glyphs beforehand, so that when needed they are simply taken out of cache.

There are several functions doing precaching, it is best to show them by example. The following 5 code fragments all do the same thing: prepare glyphs for characters 'a', 'b', 'c', 'd' and 'e' and put them into glyph cache:

  1. gk_precache_char(rend,'a');
gk_precache_char(rend,'b');
gk_precache_char(rend,'c');
gk_precache_char(rend,'d');
gk_precache_char(rend,'e');
  2. gk_precache_range(rend,'a','e');
  3. const char* char_set = "abcde"; gk_precache_set_utf8(rend,char_set);
  4. const unsigned short[] char_set = {'a','b','c','d','e',0}; gk_precache_set_utf16(rend,char_set);
  5. const unsigned[] char_set = {'a','b','c','d','e',0}; gk_precache_set_utf32(rend,char_set);

Checking cache state

You can check current cache limits:

int glyph_count_limit = gk_keeper_glyph_limit(keep); int memory_limit = gk_keeper_byte_limit(keep);

Checking current number of cached glyphs and amount of memory currently used by cache:

int glyph_count = gk_keeper_glyph_count(keep); int memory_used = gk_keeper_byte_count(keep);

Disposing glyph cache

Normally you don't have to care about it - glyph caches will be disposed automatically at the shutdown time of your program, or when you call glyph_keeper_library_done() manually. But I can imagine situations when a program suddenly needs to use all available memory, still keeping capability to render text. In such case you can safely dispose a glyph cache:

gk_done_keeper(keep);

All cached glyphs and index tables of cache object 'keep' will be removed from the memory. All renderers that were using that cache object will be automatically switched to work without cache.

Character remapping

Introduction

Imagine that the font you use lacks some characters. Should you modify the font? What if font's license doesn't allow it, or if it's a standard system font that you don't distribute? Perhaps those missing characters can be found in some other font, that you can distribute with your program, or another one of system fonts (or in a handmade font you made just for those characters). Now how to combine these two fonts together? You will need to add some logic to all your text output, to use first font for all normal text output and second font for those characters.

Since version 0.23 Glyph Keeper supports character remapping. Its lets you combine several fonts together without altering the font files and without changing the way you output text. For example you may have one nice font for Latin script, another font for CJK (Chinese-Japanese-Korean) characters and another one for Cyrillic. Your program, after you set the character remapping, may read text from file or network, and immediately render it to screen. The proper font will be selected automatically.

Remapping a single character

Remapping is done with GLYPH_FACE objects. This example remaps an asterisk character (U+002A) of "face1" to the same character from another font face:

gk_remap_character(face1,'*',face2,'*');

After this call all renderers (GLYPH_REND objects) using face1 will render asterisk of face2, althouth all other text will still be in face1. Note, that it does not matter whether face1 has its own asterisk character, in any case from now on face1's asterisk will appear as face2's one. You can later override the remapping by calling this function again, for example:

gk_remap_character(face1,'*',face2,0x2217);

will map asterisk (U+002A) of face1 to "asterisk operator" (U+2217) of face2. You can cancel a remapping by either

gk_remap_character(face1,'*',0,0);

or

gk_unmap_character(face1,'*');

(these two lines are equivalent). After this the default behavior is restored. It means original face1's asterisk will be used, or "undefined character", if asterisk is missing in face1.

Remapping a range of characters

gk_remap_range(face1,'A',face2,'a',26);

This example will make all uppercase latin characters of face1 appear as lowercase characters of face2. To removing range remapping:

gk_remap_range(face1,'A',0,0,26);

or equivalent

gk_unmap_range(face1,'A',26);

Allegro-specific usage of Glyph Keeper

Allegro built-in text rendering

Allegro has built-in font loading and text rendering routines. They are limited to bitmap fonts, so angled or italicized text can't be produced (Talking about Allegro 4.1.18 - the latest version at the moment of this writing). Also it can't adjust font size, or render transparent or antialiased text. On the other hand, this simple rendering is very fast, robust, and does not require much memory. Also it does not require any glyph caching, since the loaded font is already a collection of glyph images. A unique feature is that BITMAP font may contain hand-crafted multi-colored character glyphs, such fonts can't be used with Glyph Keeper at this moment.

Allegro defines a FONT structure, where it keeps the font data, loaded from file. A FONT must be specified for every Allegro's text rendering function, so it is analogous to Glyph Keeper's GLYPH_REND structure. Allegro provides some convenient text rendering functions, including a printf-style formatted text output. Also Allegro text rendering functions take text in a current encoding, which may be set to UTF-8. (Allegro does not support UTF-16 or UTF-32)

Creating a FONT stucture with Glyph Keeper

Since version 0.20 Glyph Keeper can produce a FONT objects, that can be used with Allegro's text rendering functions. FONT objects, created with Glyph Keeper, can render text with all features - scalable, antialiased, hinted, transparent, angled and oblique rendering is possible. In this way any existing program, even it it has thousands of calls to Allegro text rendering functions, can be converted to take advantage of high quality text rendering with just a few lines of code.

A FONT object can be created for a given renderer - a GLYPH_REND object:

FONT* font1 = gk_create_allegro_font(rend1);

New FONT object 'font1' is created for this specific renderer - 'rend1'. Now any text rendered using 'font1' with Allegro functions will have same appearance as if it was rendered with 'rend1' and Glyph Keeper's functions. Also, you may change any the renderer's settings and the FONT object will immediately produce text with these new settings.

So, at first you will need set up all you need with Glyph Keeper - load a font faces from file, create glyph cache, create renderers, configure renderers to produce text you like. Then you create a FONT objects for each of the renderers, and you just use them and forget about Glyph Keeper for the rest of your program (ideally, at least).

2005-01-26: Allegro 4.1.18 changed the font vtable, so if you use Glyph Keeper to produce Allegro FONT objects, and you have Allegro 4.1.18, you need to upgrade to Glyph Keeper 0.20.1 or later.

What if you will try to produce two FONT objects for the same renderer? Nothing special. A second time no new FONT object will be created, just the pointer to the first one will be returned to you. It will be like just copying the same address value to the second variable. The renderer keeps a link back to its FONT object. Also, When the renderer is destroyed, it takes FONT object with him.

Destroying Glyph Keeper-generated FONT object

In short, you don't have to care about it. It will be disposed automatically at the end of your program run, or when you call gk_library_cleanup(). Also, the FONT object will be gone when you dispose the renderer with gk_done_renderer(). If you need you can call Allegro's destroy_font() and the FONT object will be gone. In any case, don't try to use a FONT object, which was disposed by any of the mentioned ways.

Text height issue

Allegro font routines are designed to work with bitmap fonts - fonts where every character glyph is explicitly specified in a font file. This has several consequences on Allegro text rendering: 1. Text height can be known for a font. With bitmap fonts it is possible to define a text height measure and to actually find it for a given font. This is, of course, convenient for a text layout, when you need to know how large space a line of text can occupy. 2. As a consequence, for every text output Allegro routines take coordinates of the left-top corner of a text rectangle to be rendered. For example if you specify (20,20) you know that the text will appear lower and to the left from (20,20). This is very convenient and easy way to think about text output, as long as you work with bitmap fonts.

Glyph Keeper works with scalable fonts, which makes things more complex. Although ascender and descender values are specified in the font file, the exact height of a scalable font can not be found reliably for several reasons: 1. The ascender and descender values stored in a font file are sometimes erroneous. 2. The font may contain thousands of characters, checking the height of each of them may take some time. 3. Hinting process can change the shape of a character, making it a bit higher or lower. 4. In complex text rendering an accent marks or some other combined character may be attached to the base character, making it higher (This is not supported by current Glyph Keeper, but I hope to do this in future).

So, when you switch to the FONT objects generated by Glyph Keeper, you should be careful about text height. Allegro's text_height() will still give you the estimation of a font height, but you can't completely rely on this value. Sometimes it may be possible that a character is a little higher, suddenly. Such character may extend beyond the expected text rectangle, crossing to the lower or upper border. Incorrect ascender and descender values, or enabled hinting may also result in this problem. If you want to prevent anything jumping out of your text box, you may use bitmap clipping.

You can use FONT object for angled (non-horizontal) text rendering too. Just change the angle in the renderer structure, and continue using allegro text rendering functions. But be aware, that in that case the Allegro's text_height() will still return the height of horizontal text, calculated as (ascender - descender).

To be continued...
Valid HTML 4.01! Created in 2003-2005 by Kirill Kryukov
last modified 25-May-2005 		Open Source
Against TCPA No software patents No software patents


Glyph Keeper - A text rendering library

Glyph Keeper

Latest version: 0.25 (March 23, 2005)
Home | Introduction | License | Screenshots | Files | Compiling | Manual | Reference | Examples | Future | Thanks | Links | Guestbook

Compiling Glyph Keeper

Requirements

  1. OS with long file names support. Glyph Keeper file names are not in 8.3 format, they have to be changed to be used with DOS. (It's easy to make 8.3 names, I just don't want to cripple the default package, which will be used on long file name capable systems by most of people)
  2. ANSI C compliant compiler. Glyph Keeper was tested with GCC, Intel C++, MSVC, CodeWarrior, Digital Mars C++.
  3. FreeType library installed and ready to use. This is easy if the previous requirement is met. Please check FreeType documentation for details. If you are using Linux there is a chance you already have FreeType installed. Glyph Keeper is tested with FreeType 2.1.9. If you experience problems with older FreeType, try upgrading it. If your problem is with newer FreeType please tell me and I will fix Glyph Keeper to work with it.
  4. Target-supporting library installed and ready to use. It means if you are going to use Glyph Keeper with Allegro, Allegro headers should be located where compiler can find them. Similar for SDL. Text mode FILE IO target (Named GLYPH_TARGET_TEXT in glyph.h) does not need any extra libraries and can be used to test Glyph Keeper and FreeType installation without introducing extra dependencies.

Compiling

Once you have the compiler, FreeType and target library, it is straightforward to compile Glyph Keeper. You only need to compile "glyph.c", which #includes other *.c files. Here are example commands doing that:

Cygwin environment, GCC 3.3.3, default text target:

gcc -W -Wall -O3 -c -o glyph-text-cygwin.o glyph.c
All same, Allegro target:
gcc -W -Wall -O3 -DGLYPH_TARGET=GLYPH_TARGET_ALLEGRO -c -o glyph-allegro-cygwin.o glyph.c

Compiling Glyph Keeper with GCC under Linux:

gcc -I/usr/local/include/freetype2 -I../include -W -Wall -O3 -DGLYPH_TARGET=GLYPH_TARGET_ALLEGRO -c -o glyph-allegro.o glyph.c

Similar command should work with other GCC ports, just put correct paths and file names, and your favorite optimization options. I also use '-Werror -ansi -pedantic' to catch more errors, but it's not necessary for you.

Compiling Glyph Keeper with Intel C/C++ compiler may look like this:

icl -nologo -W3 -MD -fast -c -Fo"glyph-text-icl.obj" glyph.c

Installing

Successful compilation will produce a single object file, named 'glyph.o' or whatever name you give it. Just place it somewhere where linker can find it and add it to the link phase of your build script. If you like, you can make a 'glyph.lib' or 'libglyph.a' file with your 'lib' or 'ar' utility.

Now, the header file, 'glyph.h'. You can copy it into your compiler 'include' directory, your project directory, or any other place where your compiler will find it.

Configuring Glyph Keeper

Compiler macros, affecting Glyph Keeper:

GLYPH_DLL - defining this macro will give '__declspec(dllexport)' to Glyph Keeper API declarations. It is useful if you are going to produce Glyph Keeper DLL. Although, in general, I don't recommend doing Glyph Keeper DLL. Keeping FreeType as DLL is considerable.

GLYPH_SAFE - defining this macro while compiling Glyph Keeper (glyph.c) will switch on more Glyph Keeper internal consistency checking. Glyph Keeper may become a little slower, probably not noticeable slowdown. This macro is used to debug Glyph Keeper, not your program.

GLYPH_LOG - this macro controls Glyph Keeper logging. If this macro is defined, a logfile "glyph.log" will be created every time you run your program linked to Glyph Keeper. Many things will be written to this logfile, as your program calls Glyph Keeper routines. Normally you should only use this macro if you are debugging Glyph Keeper or making changes to it.
This macro first emerged in Glyph Keeper 0.15, it has no effect on earlier versions.

GLYPH_TARGET - this macro specifies Glyph Keeper target. It can be set to one of these values:

GLYPH_TARGET_TEXT - stdio output, glyphs are printed out to the FILE* stream.
GLYPH_TARGET_ALLEGRO - glyphs are rendered to the Allegro BITMAPs. GLYPH_TARGET_SDL - glyphs are rendered to the SDL surfaces.

The GLYPH_TARGET macro should be defined same for all files in your project, having '#include "glyph.h"'. It is better to define it in the compiler command line. If you don't define this macro explicitly, it will be set to GLYPH_TARGET_TEXT by default.

GLYPH_NO_LEGACY - if defined, disables compatibility with old versions of Glyph Keeper API. This macro has no effect on Glyph Keeper itself, but on your program. If you use this macro it should be defined before including "glyph.h". This macro appeared in Glyph Keeper 0.21.2.

NDEBUG - this macro has nothing to do with Glyph Keeper, since it does not use 'assert()'.

Valid HTML 4.01! Created in 2003-2005 by Kirill Kryukov
last modified 14-Mar-2005 		Open Source
Against TCPA No software patents No software patents


Glyph Keeper - A text rendering library

Glyph Keeper

Latest version: 0.25 (March 23, 2005)
Home | Introduction | License | Screenshots | Files | Compiling | Manual | Reference | Examples | Future | Thanks | Links | Guestbook

API Reference

  • Structures
  • Basic routines
  • GLYPH_FACE routines
  • GLYPH_KEEP routines
  • GLYPH_REND routines
  • Layout and rendering
  • Allegro-specific routines

Structures

typedef struct GLYPH_FACE
GLYPH_FACE structure represents a font face. Font face is a typographic term, it is used because single font may have several faces, like normal, bold, italic are different faces of the same font. A font file may contain several font faces, so here we will deal with an individual font face, rather than with the whole font.
A new GLYPH_FACE object is created when you load a font face from file with gk_load_face_from_file() (or from memory buffer with gk_load_face_from_memory()). After loading a font face from file you can create a renderer (GLYPH_REND object) that will use it. Also you may introduce new font face to existing renderer with gk_rend_set_face().
When you don't need a font face anymore, you can dispose it with gk_unload_face(). A call to gk_library_cleanup() will dispose (among other things) all font faces currently loaded.
typedef struct GLYPH_KEEP
This structure represents a glyph cache object. It takes some time to render a character glyph, so it makes good sense to remember once rendered glyphs to print them faster later.
GLYPH_KEEP object is created with gk_create_keeper(). Then you should connect it to one or more renderers (GLYPH_REND objects), otherwise it will be not used. One way to do it is to create a new renderer with gk_create_renderer(), providing GLYPH_KEEP* as a second parameter. Another way is to connect it to existing renderer with gk_rend_set_keeper().
A single GLYPH_KEEP object may work with several renderers at the same time. Even large program using many fonts may still have only one or two glyph caches. This makes easier to control and monitor cache size.
GLYPH_KEEP object can be disposed with gk_done_keeper(). When you do this, all renderers that were using this cache will automatically switch to uncached mode. gk_library_cleanup() will also dispose all caches.
typedef struct GLYPH_REND
This structure keeps together all text rendering settings, like font face, size, color, angle and so on. Every text output with Glyph Keeper requires a GLYPH_REND object.
A renderer (GLYPH_REND object) can be created with gk_create_renderer(). New renderer is immediately ready to use, as long as you provided valid font face when creating it. (If not, you can assign a font face later with gk_rend_set_face().) Default font size it 16 pixels, default rendering mode is antialiased hinted rendering, default color is 0x0000FF (blue), default transparency is 255 (opaque).
Renderer can be disposed with gk_done_renderer(). gk_library_cleanup() will dispose all currently existing renderers.
#define GLYPH_TARGET_SURFACE ...
You will need to provide a pointer to GLYPH_TARGET_SURFACE to all Glyph Keeper routines that actually produce some text. GLYPH_TARGET_SURFACE is simply an alias for target-specific surface: BITMAP for Allegro, SDL_Surface for SDL and FILE for text only mode.

Basic routines

void gk_set_messenger ( void (*func)(const char* const msg) );
This function sets user-provided messenger function, which will handle Glyph Keeper's messages. Glyph Keeper routines will produce diagnostic or error messages for various matters.
If no messenger function is provided, no text feedback or error messages will come out of Glyph Keeper. Set to 0 to 'unset' the messenger function.
Although it is better to set messenger function once in the begining and keep it same through the program session, there is no any problem in changing messenger to another one, as many times as you like.
void gk_set_font_path ( char* path );
Sets font search path - a list of directories where a font file will be searched when you load a font from file. 'path' can include several directories, separated by semicolon. All directories should include the final slash character. 'path' should be an ASCII string. After calling this function only reference to the 'path' will be kept by Glyph Keeper, the string itself is not copied. So, don't dispose the path string after setting. Also, every change you make to the path string will have immediate effect.
void gk_library_init();
Glyph Keeper initialization. There is no need to call this function in your program - it will be called automatically when you load first font face, or create first keeper or renderer object. This function does several simple things: 1. It initializes FreeType. 2. Creates Glyph Keeper log file 'glyph.log' if GLYPH_LOG macro is defined. 3. Registers cleanup code gk_library_cleanup() with atexit(), if it was not registered yet. You can call this function, if you want to separate FreeType initialization from loading first font for some reason.
void gk_library_cleanup();
Glyph Keeper shutdown function. Basically it does nothing more than complete cleanup. All data allocated by Glyph Keeper will be disposed: all objects of type GLYPH_FACE, GLYPH_KEEP and GLYPH_REND will be gone, all pointers to them will become invalid. FreeType library will be also dismissed.
It is OK to call this function and later load some new font and start using Glyph Keeper again in the same program session. Just be careful not to use any old pointers after this call.
Actually you are not required to call this function in your program. Glyph Keeper initialization will register this function with the atexit(), and it will be called in the end of your program anyway.
There is no problem to call this function twice or any number of times. So, you can still call it at the end, if you like. Or if you want to control the order of things happening.
int gk_bytes_allocated();
Returns amount of memory, allocated in heap by Glyph Keeper, in bytes. FreeType memory is not counted. (I don't know how to get this information from FreeType) (FIXME). If you call this function immediately after gk_library_cleanup() you should obtain 0.

GLYPH_FACE routines

GLYPH_FACE* gk_load_face_from_file ( char* fname, int face_index );
Loads font face from a file 'fname'. If there is no such file in the current directory, the font search path will be searched for this file. One file may contain several font faces, use 'face_index' to specify wich one to load. Use 'face_index' = 0 to load first font face, or if there is only one font face in the file. This function returns 0 on failure.
Glyph Keeper currently only supports scalable fonts (TrueType, OpenType etc), that have Unicode character map.
GLYPH_FACE* gk_load_face_from_memory ( unsigned char* data, int size, int face_index );
Loads font face from a memory buffer, pointed by 'data'. Returns a pointer to new GLYPH_FACE object if successful, returns 0 on failure.
GLYPH_FACE object returned by this function does not contain copy of the 'data' contents, that data is used directly. So, you must not dispose the memory occupied by 'data' until you destroy the font face with gk_unload_face(), or better until you call gk_library_cleanup().
void gk_unload_face ( GLYPH_FACE* f );
You can manually dispose GLYPH_FACE object with this function. All renderers using is will automatically become unuseful until you set them to use another font face. All currently loaded font faces can be also disposed with gk_library_cleanup().
const char* gk_face_family ( GLYPH_FACE* f );
const char* gk_face_style ( GLYPH_FACE* f );
const char* gk_face_postscript_name ( GLYPH_FACE* f );
const char* gk_face_driver_name ( GLYPH_FACE* f );
These functions extract various information from font face. Don't free() the char* after using.
int gk_face_is_horizontal ( GLYPH_FACE* f );
int gk_face_is_vertical ( GLYPH_FACE* f );
These functions check the directions supported by the font face. They can both return true for the same font face, if the font face contains both horisontal and vertical metrics.
int gk_face_ascender ( GLYPH_FACE* f );
Vertical distance from the baseline to the topmost point of any glyph in the face. Positive, expressed in font units.
int gk_face_descender ( GLYPH_FACE* f );
Vertical distance from the baseline to the bottommost point of any glyph in the face. Negative, expressed in font units.
int gk_face_line_spacing ( GLYPH_FACE* f );
Vertical distance from one baseline to the next one when writing several lines of text. Always positive, expressed in font units.
int gk_face_number_of_glyphs ( GLYPH_FACE* f );
Returns total number of glyphs in a font face. This is not necessarily the same with the number of characters this font face can render.
int gk_face_has_character ( GLYPH_FACE* f, unsigned code );
Returns non-zero, if font face 'f' has character 'code', including remapped characters. Returns zero otherwise.
int gk_face_has_own_character ( GLYPH_FACE* f, unsigned code );
Returns non-zero, if font face 'f' has its own definition of character 'code', without remapping. Returns zero otherwise.
int gk_face_number_of_characters ( GLYPH_FACE* f );
Returns number of characters, that can be rendered with this font face. Remapped characters are also counted. On the other hand, if a character is disabled due to the remapping, it is not counted.
int gk_face_number_of_own_characters ( GLYPH_FACE* f );
Returns number characters defined in this font face, without remapping.
void gk_remap_character ( GLYPH_FACE* face1, unsigned code1, GLYPH_FACE* face2, unsigned code2 );
Remaps character 'code1' of 'face1' so that character 'code2' of 'face2' is used instead. This function has immediate effect, all renderers using 'face1' will start printing character code2 of face2 whenever they are asked to render character code1. Note, that character code1 does not have to be defined in face1 for remapping to work.
If face1 has character code1, but face2 does not have character code2, remapping will be set anyway, disabling possibility of rendering character code1 of face1. "undefined character" will be used instead.
If 'face2' is 0, remapping is removed for this character (code1 of face1). Original character of face1 will be used, or "undefined character" if it is not defined.
Character remapping is discussed in detail in the manual.
void gk_unmap_character ( GLYPH_FACE* face, unsigned code );
Removes any remapping assosiated with character 'code' of font face 'face'. Equivalent to gk_remap_character(face,code,0,0);
void gk_remap_range ( GLYPH_FACE* face1, unsigned code1, GLYPH_FACE* face2, unsigned code2, unsigned range_size );
Remaps a whole range of characters. It is identical to
for (i=0; i<range_size; i++) gk_remap_character(face1,code1+i,face2,code2+i); (Actually this is how it really works).
void gk_unmap_range ( GLYPH_FACE* face, unsigned code, unsigned range_size );
Unmaps a range of characters, like this:
for (i=0; i<range_size; i++) gk_unmap_character(face,code+i);

GLYPH_KEEP routines

GLYPH_KEEP* gk_create_keeper ( unsigned max_glyphs, unsigned max_memory );
Creates new GLYPH_KEEP object, limited to keep not more than 'max_glyphs' glyphs and to use not more than 'max_memory' bytes in memory. You can set 'max_glyphs' and/or 'max_memory' to 0 to have no limit. This function returns 0 on failure.
void gk_done_keeper ( GLYPH_KEEP* keeper );
This function is useful to destroy GLYPH_KEEP object. Normally there is no particular need to call it - all GLYPH_KEEP objects will be automatically destroyed by gk_library_cleanup(). Note that you can safely destroy GLYPH_KEEP object, even if some renderer (GLYPH_REND object) is using it. Renderer will just switch to work without cache. But don't use in any way pointer to the destroyed keeper.
int gk_keeper_glyph_count ( GLYPH_KEEP* keeper );
Returns number of glyphs currently cached by the keeper.
int gk_keeper_glyph_limit ( GLYPH_KEEP* keeper );
Returns maximum number of glyphs a keeper can keep.
int gk_keeper_byte_count ( GLYPH_KEEP* keeper );
Returns number of bytes used by a keeper. This includes GLYPH_KEEP structure, its indexes and all cached glyphs.
int gk_keeper_byte_limit ( GLYPH_KEEP* keeper );
Returns maximum number of bytes this keeper may use in memory.
void gk_keeper_debug ( GLYPH_KEEP* keeper );
Prints some information about keeper's current state. Printing goes through the messenger function.

GLYPH_REND routines

GLYPH_REND* gk_create_renderer ( GLYPH_FACE* face, GLYPH_KEEP* keeper );
Creates new renderer - GLYPH_REND object. Renderer is set to use font face 'face' and glyph cache 'keeper'. If 'keeper' is 0, renderer will still work fine, just without cache. Caching can be turned on later by introducing a keeper with gk_rend_set_keeper(). If 'face' is 0, renderer will be still created, but can't be used until some font face is specified with gk_rend_set_face(). FT_RENDER_MODE_NORMAL is the default rendering mode. '?' (U+003F) is the default undefined character.
void gk_done_renderer ( GLYPH_REND* rend );
Deletes GLYPH_REND object from memory. Don't use in any way pointer to the destroyed renderer, it will crash your program.
void gk_rend_set_keeper ( GLYPH_REND* rend, GLYPH_KEEP* new_keeper );
Assigns a glyph cache - GLYPH_KEEP object to this renderer. In fact one GLYPH_KEEP object can cache glyphs for several renderers at the same time. If 'new_keeper' is 0, glyph caching will be turned off for this renderer.
void gk_rend_set_face ( GLYPH_REND* rend, GLYPH_FACE* new_face );
Assigns a new font face for this renderer. All rendered glyphs will be of that face. If 'new_face' is 0, the renderer will become unuseful - it can't render anything.
int gk_rend_set_size_subpixel ( GLYPH_REND* rend, unsigned new_hsize, unsigned new_vsize );
Sets new character size for the renderer. New size is set in the way, that font's EM square dimensions become 'new_hsize' x 'new_vsize', in 1/64th of a pixel. Returns 1 on success, 0 on failure. I don't know why it may fail, but please check for return code anyway.
int gk_rend_set_size_pixels ( GLYPH_REND* rend, unsigned new_pixel_hsize, unsigned new_pixel_vsize );
Similar to gk_rend_set_size_subpixel(), just takes new size arguments expressed in integer pixels. Returns 1 on success, 0 on failure.
void gk_rend_set_angle ( GLYPH_REND* rend, double new_angle );
Sets new angle in radians. Renderer with angle set to M_PI/2, for example, will produce text going vertically upside.
void gk_rend_set_italic ( GLYPH_REND* rend, int new_italic_angle );
Sets text obliquing angle, in degrees. Positive angles mean obliquing to the right, negative - to the left. Allowed angles are from -45 to 45. Use angle of 12 degrees to obtain a common italic text.
int gk_rend_ascender ( GLYPH_REND* rend );
int gk_rend_ascender_pixels ( GLYPH_REND* rend );
int gk_rend_descender ( GLYPH_REND* rend );
int gk_rend_descender_pixels ( GLYPH_REND* rend );
These finctions return renderer's ascender and descender in 1/64th of a pixel. ..._pixels - version returns same thing in integer pixels. Ascender is (should be) the vertical distance from the baseline to the highest point of a character, rendered with this renderer. Descender is the vertical distance from the baseline to the lowest point of any character. Note, that ascender is positive, while descender is usually negative.
int gk_rend_spacing ( GLYPH_REND* rend );
int gk_rend_spacing_pixels ( GLYPH_REND* rend );
Returns vertical distance between lines, in 1/64th of a pixel. Spacing returned by this function is not affected by renderer's angle setting. gk_rend_spacing_pixels() returns line spacing in integer pixels. Line spacing is usually larger than (ascender - descender).
int gk_rend_height ( GLYPH_REND* rend );
int gk_rend_height_pixels ( GLYPH_REND* rend );
Returns 'text height' = ascender - descender.
void gk_rend_set_hinting_off ( GLYPH_REND* rend );
void gk_rend_set_hinting_default ( GLYPH_REND* rend );
void gk_rend_set_hinting_force_autohint ( GLYPH_REND* rend );
void gk_rend_set_hinting_no_autohint ( GLYPH_REND* rend );
These functions control how this renderer will perform hinting. (to do: explain what hinting is)
void gk_rend_set_antialiasing_on ( GLYPH_REND* rend );
void gk_rend_set_antialiasing_off ( GLYPH_REND* rend );
Turn antialiasing on/off for a renderer. Every newly created renderer has antialiasing on by default, you should switch is off if you don't need it.
void gk_rend_set_undefined_char ( GLYPH_REND* rend, unsigned new_undefined_char );
You can specify which character will show up instead of the character, not present in font. Default character is '?', but with this function you can set it to anything. Setting it to 0 will prevent anything shown instead of undefined characters.
void gk_rend_set_error_char ( GLYPH_REND* rend, unsigned new_error_char );
Sometimes the character glyph is defined in font face, but some error happens when trying to render it. In such case the 'error_char' will appear instead of the failed character. Default 'error_char' is 0, which means nothing is shown instead of failed characters.
int gk_rend_has_character ( GLYPH_REND* rend, unsigned code );
Returns 1, if renderer can render a glyph for character 'code', otherwise returns 0.
int gk_rend_has_glyph ( GLYPH_REND* rend, unsigned code );
Returns 1, if renderer can render a non-empty glyph for character 'code', otherwise returns 0. Empty glyphs usually represent space characters, but are also abundant in some broken fonts.
void gk_rend_set_text_color ( GLYPH_REND* rend, unsigned char r, unsigned char g, unsigned char b );
This routine will set text color. With Glyph Keeper you don't have to provide text color for each text output operation, instead you set it once in renderer and all newly rendered text will have this color automatically. Color is specified in platform/gfx.mode independent way - 'r', 'g' and 'b' are in 0..255 range.
When a new renderer is created, it has blue text color by default. You can always revert to the default color by calling rend_set_text_color(rend,0,0,255);
void gk_rend_set_text_alpha ( GLYPH_REND* rend, unsigned char alpha );
unsigned gk_rend_get_text_alpha ( GLYPH_REND* rend );
Setting and querying renderer's alpha transparency, always from 0 to 255. This setting affect only text transparency, background rectangle is not transparent. With alpha = 0 no text will appear at all, with alpha = 255 opaque text will be rendered. If you are rendering text with background rectangle, the background rectangle will be drawn even if the text alpha is 0.
void gk_rend_set_text_alpha_color ( GLYPH_REND* rend, unsigned alpha_color );
unsigned gk_rend_get_text_alpha_color ( GLYPH_REND* rend );
Setting and querying text alpha transparency and color together. 'alpha_color' is in AARRGGBB format: (A<<24)+(R<<16)+(G<<8)+B. A, R, G and B are in 0..255 range.
void gk_rend_set_back_color ( GLYPH_REND* rend, int new_back_color );
int gk_rend_get_back_color ( GLYPH_REND* rend );
Setting and querying the background color, in 24-bit RRGGBB format ( (R<<16)|(G<<8)|B, 0 <= R G B <= 255 ).
void gk_rend_debug ( GLYPH_REND* rend );
Prints out renderer's settings via the messenger function.

Layout and rendering

int gk_char_width ( GLYPH_REND* rend, unsigned unicode );
int gk_text_width_utf8 ( GLYPH_REND* rend, char* text );
int gk_text_width_utf16 ( GLYPH_REND* rend, unsigned short* text );
int gk_text_width_utf32 ( GLYPH_REND* rend, unsigned* text );
These functions return width of text produced by renderer 'rend', in pixels. For angled text the width is not just length of a rendered string, but its horizontal width - it is smaller for angled string than for the same string printed horizontally. (Text angle is specified in the renderer object 'rend')
int gk_char_height ( GLYPH_REND* rend, unsigned unicode );
int gk_text_height_utf8 ( GLYPH_REND* rend, char* text );
int gk_text_height_utf16 ( GLYPH_REND* rend, unsigned short* text );
int gk_text_height_utf32 ( GLYPH_REND* rend, unsigned* text );
These functions return text height in pixels. For horizontal text height taken from the renderer structure and returned immediately, but for angled text all the height is calculated by rendering all glyphs one by one and accumulating their vertical advance.
void gk_char_size ( GLYPH_REND* rend, unsigned unicode, int* width, int* height );
void gk_text_size_utf8 ( GLYPH_REND* rend, char* text, int* width, int* height );
void gk_text_size_utf16 ( GLYPH_REND* rend, unsigned short* text, int* width, int* height );
void gk_text_size_utf32 ( GLYPH_REND* rend, unsigned* text, int* width, int* height );
These functions obtain both width and height of text, in pixels, and write them to '*width' and '*height'. It is faster to call one of these functions than obtaining text width and height separately.
void gk_char_advance ( GLYPH_REND* rend, unsigned unicode, int* adv_x, int* adv_y );
void gk_text_advance_utf8 ( GLYPH_REND* rend, char* text, int* x_adv, int* y_adv );
void gk_text_advance_utf16 ( GLYPH_REND* rend, unsigned short* text, int* x_adv, int* y_adv );
void gk_text_advance_utf32 ( GLYPH_REND* rend, unsigned* text, int* x_adv, int* y_adv );
These functions calculate text advance (in pixels) and writes it to '*x_adv' and '*y_adv'. Advance is horizontal and vertical shift applied to the pen position, when the text is rendered along the baseline. See the picture:
void gk_char_advance_subpixel ( GLYPH_REND* rend, unsigned unicode, int* adv_x, int* adv_y );
void gk_text_advance_subpixel_utf8 ( GLYPH_REND* rend, char* text, int* x_adv, int* y_adv );
void gk_text_advance_subpixel_utf16 ( GLYPH_REND* rend, unsigned short* text, int* x_adv, int* y_adv );
void gk_text_advance_subpixel_utf32 ( GLYPH_REND* rend, unsigned* text, int* x_adv, int* y_adv );
Text advance is returned in 1/64th of a pixel.
void gk_glyph_size ( GLYPH_REND* rend, unsigned unicode, int* width, int* height );
int gk_glyph_width ( GLYPH_REND* rend, unsigned unicode );
int gk_glyph_height ( GLYPH_REND* rend, unsigned unicode );
These functions measure a single glyph.
void gk_precache_char ( GLYPH_REND* rend, unsigned unicode );
void gk_precache_range ( GLYPH_REND* rend, unsigned range_start, unsigned range_end );
void gk_precache_set_utf8 ( GLYPH_REND* rend, char* char_set );
void gk_precache_set_utf16 ( GLYPH_REND* rend, unsigned short* char_set );
void gk_precache_set_utf32 ( GLYPH_REND* rend, unsigned* char_set );
These functions perform precaching - rendering character glyph and putting it into the cache for later usage. Precaching should be used to prepare glyphs that you expect to be used soon. Glyphs that are already in the cache are not rendered again, just moved to the head of cache's MRU-ordered glyph list. If the renderer does not have cache this functions have no effect.
gk_precache_char() precaches one character glyph. gk_precache_range() precaches continuous range of characters. gk_precache_set_utf8() precaches a set of characters, passed in a 0-terminated UTF-8 string. gk_precache_set_utf16() and gk_precache_set_utf32() do same thing taking character set in UTF-16 and UTF-32.
Also see the manual.
void gk_put_char ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned unicode, int x, int y );
Prints a unicode character to the surface 'bmp', using renderer 'rend'. Character glyph is positioned so that its left top corner will appear at (x,y). This is rather low-level function, it is not useful for rendering a line of text, because characters have varying height and also because this function doesn't respect character glyph's bearing and advance values. Also, this function never draws background rectangle.
void gk_put_char_center ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned unicode, int x, int y );
Similar to gk_put_char(), the only difference is that the character glyph is printed out centered at (x,y).
void gk_render_char ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned unicode, int* pen_x, int* pen_y );
Renders one character, starting with positioning pen at text origin point (*pen_x,*pen_y). *pen_x and *pen_y coordinates are expressed in 1/64th of a pixel. *pen_x and *pen_y will be incremented to become starting pen position for the next character. Also see the manual.
void gk_render_line_utf8 ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, char* text, int pen_x, int pen_y );
void gk_render_line_utf16 ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned short* text, int pen_x, int pen_y );
void gk_render_line_utf32 ( GLYPH_TARGET_SURFACE* bmp, GLYPH_REND* rend, unsigned* text, int pen_x, int pen_y );
Render one line of text. Text must be null-terminated string in one of the UTF encodings. The byte order mark (BOM) is supported for UTF-16 and UTF-32 text, so you can render text you recieve from network without caring about endianness.

Allegro-specific routines

FONT* gk_create_allegro_font ( GLYPH_REND* r );
This function creates a FONT object, corresponding the the renderer 'r'. (FONT is structure defined by Allegro for its built-in text rendering.) Returns pointer to created FONT structure or 0 on failure. Created FONT object can be used with any of Allegro functions and is supposed to produce text, with the font face, size, hinting, antialiasing and all other settings of the renderer 'r'. Please see the manual section for more details.
Please note that the FONT structure does have copy of renderer's data, it simply refers to the renderer. Don't dispose the renderer, if you are still going to use the FONT object made from it.

Valid HTML 4.01! Created in 2003-2005 by Kirill Kryukov
last modified 25-May-2005 		Open Source
Against TCPA No software patents No software patents