QuesoGLC

Home
News
Screenshots
Links
- GLC specs
- Unicode
- FreeType
- Fontconfig

Documentation

Sourceforge

First Steps

General description

GLC is a library that provides font services for OpenGL applications. When using GLC, there is no need for you to look for font directories, manage the font files, load and interpret glyphs data, tesselate polygons, antialias characters and issue GL commands to render text, since GLC takes care of that for you.

Although GLC is very easy to use, there are a few steps to follow in order to be ready to render text in your OpenGL application. This tutorial will guide you through the basic commands of GLC and will expose you a few concepts that GLC relies on.

Warning:: Since GLC uses OpenGL, a GL context must be bound to the current thread before any GLC command can be issued. This task must be done by the GLC client (i.e. the application that uses GLC). GLC does not verify if this has been done. If you try to issue GLC commands while no GL context is current, the result of the commands is undefined.

Setting up a GLC context

Just like OpenGL, GLC relies on the concept of context. A context is an entity that stores the state machine of GLC, that is, an entity that stores the font that is currently used, the type of rendering, the string encoding and so on.

Context creation

Unlike OpenGL, the GLC context commands are machine independant. The commands to create, manage and bind a context to the current thread are the same for every platform that supports GLC.

The first step to use GLC is to create a context which is simply done by the code below :

GLint ctx;

ctx = glcGenContext();

When glcGenContext() is executed, the variable ctx contains the ID of the context that has been created. This ID is unique and must be used each time a GLC command needs to identify a context.

Context binding

You can create just as many contexts as you want, but one and only one context can be used at a given time. Therefore, you must tell GLC which context you plan to use, even if you have created only one context. This operation is said to "make a context current" or to "bind a context to the current thread". This is achieved by calling glcContext() :

glcContext(ctx);

At this stage, whenever a GLC command is issued, the context ctx will execute the command.

You can change the current GLC context at any time by re-issuing a glcContext() command with a new context ID and if you want to release the current context without making a new context current, you just need to call glcContext(0);

Note:: If your application is multi-threaded, you can bind a different context to each thread. However a context can only be bound to one thread at a time.

Adding font directories

GLC grabs font files from directories that are called "catalogs" in the GLC specifications. Depending on the implementation, a GLC context may or may not have default directories where to look for font files and may or may not provide some default fonts.

QuesoGLC uses the Fontconfig library to automagically find the fonts that are available on your system. Moreover, the environment variable GLC_PATH can be used to set up some more default fonts. You may however want GLC to search for fonts in additional directories, especially if your application comes with its own fonts. This can be achieved with the command glcAppendCatalog() :

// For many Unixes (included Linux), /usr/lib/X11/fonts/Type1/ is a standard
// directory where X windows stores fonts in Adobe's Type1 format.

glcAppendCatalog("/usr/lib/X11/fonts/Type1/");

You can call glcAppendCatalog() as much as needed, to add several directories to the catalog list of GLC.

Note:: GLC internally manages a list of catalogs (that is, of directories) where it will look for directories that contains the font files. You can inspect this list with the command glcGetListc() as in the following code :

GLint count, i;

// Get the number of entries in the catalog list
count = glcGeti(GLC_CATALOG_COUNT);

// Print the path to the catalogs
for (i = 0; i \< count; i++)
    printf("%s\n", glcGetListc(GLC_CATALOG_LIST, i));

Choosing a font

Now, you may want to choose the font that will be used to render your text. In GLC, fonts are managed in a very similar way than contexts are : fonts are identified by a unique integer ID, and they need to be made current to the context before they are used. Hence, we need first to get an identifier which is not used by another font :

GLint myFont;

myFont = glcGenFontID();

The font ID myFont is unique and will be used thereafter to designate our font.

Each font has a family name (e.g. Palatino, Courier, Helvetica, ...) and a state variable that select one of the faces (e.g. Regular, Italic, Bold, Bold Italic, ...) that the font contains.

In our example, we want to use "Palatino Bold" to render the text. This is done with the following code :

glcNewFontFromFamily(myFont, "Palatino"); // Select the family of my font
glcFontFace(myFont, "Bold"); // Select the face of my font

At this stage, a new font "Palatino Bold" which is identified by myFont has been created in the current GLC context. We now want GLC to use myFont to render the text :

glcFont(myFont);

Rendering the text

We have now reached the final step : we are now able to render some text. First, we need to tell OpenGL (yes, OpenGL not GLC !!!) where the characters will be rendered. Indeed, when the glcRenderString() command will be executed, GLC will issue some GL commands but nothing will be displayed if we do not tell OpenGL where to render the string.

By default, QuesoGLC renders fonts at a size of 1 point. If we want our text to be readable, we must scale it :

// Render the text at a size of 100 points
glcScale(100.f, 100.f);

If we decide to render text in bitmap mode (which is the default render style of GLC), we need to give the raster position and (why not ?) the color of the text to OpenGL :

glColor3f(1.f, 0.f, 0.f);
glRasterPos2f(50.f, 50.f);

Now, our text will be rendered at coordinates (50, 50) in red color.

It is time now to render the famous "Hello world!" string :

glcRenderString("Hello world!");

That's it ! With a few lines of code, GLC allows to render some text in an OpenGL window.

As a reminder, the complete code is given below :

GLint ctx, myFont;

// Set up and initialize GLC
ctx = glcGenContext();
glcContext(ctx);
glcAppendCatalog("/usr/lib/X11/fonts/Type1/");

// Create a font "Palatino Bold"
myFont = glcGenFontID();
glcNewFontFromFamily(myFont, "Palatino");
glcFontFace(myFont, "Bold");
glcFont(myFont);

// Render the text at a size of 100 points
glcScale(100.f, 100.f);

// Render "Hello world!"
glColor3f(1.f, 0.f, 0.f);
glRasterPos2f(50.f, 50.f);
glcRenderString("Hello world!");

Most of the code above is executed once in a program : the GLC setup and the font creation are done at the beginning of the program, only the rendering part of the code (that is 3 lines !) may be located in the main loop of the application.

Note:: If the rendering style of the text is not GLC_BITMAP, then you should use glTranslate() and glScale() instead of glRasterPos() and glcScale().

What more ?

This is a basic tutorial which has shown you the basic steps to render some text with GLC. However, for the sake of clarity, no error has been checked in the example above. In GLC some functions returns a value and this value must be checked in order to verify that no error has occured. Nevertheless, the prefered way in GLC to check errors is to use glcGetError().

If you want to change the code above in order to fit it to your needs, the first place to look at is the reference documentation which is provided with QuesoGLC.

GLC also provides a nice set of functions (all of them beginning with glcGet* ) to introspect a context and see, for instance, which fonts are available.

The Measurement commands have not been used in the example above but you may use them to get some basic metrics of a string in order to precisely locate it on the screen (see the Measurement tutorial for instance).

The Transformation commands can be used with GLC_BITMAP rendering to obtain fancy effects (rotation and scaling) which are not available in GLX.

Finally, you can have a look at the tests and examples of QuesoGLC to learn how to use some GLC commands and which are their effect.

Generated on Sat Jan 20 20:11:44 2007 for QuesoGLC by