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.
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.
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.
- 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.
The first step to use GLC is to create a context which is simply done by the code below :
When glcGenContext() is executed, the variable
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() :
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.
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
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.
- 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.
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() :
You can call glcAppendCatalog() as much as needed, to add several directories to the catalog list of GLC.
- 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 :
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 count, i;
count = glcGeti(GLC_CATALOG_COUNT);
for (i = 0; i \< count; i++)
printf("%s\n", glcGetListc(GLC_CATALOG_LIST, i));
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 :
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 :
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 :
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);
Now, our text will be rendered at coordinates (50, 50) in red color.
It is time now to render the famous "Hello world!" string :
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 :
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.
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 the rendering style of the text is not GLC_BITMAP, then you should use
glScale() instead of
glRasterPos() and glcScale().
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.