When it comes to drawing the final layout there are quite some choices to make. This page will try to explain some of the available options.

Not all output drivers will support all the available options. Please read there for further information

Gamma

Some output drivers support gamma correct blending when drawing. That means they can be used to draw onto surfaces that do have a non linear intensity curve.

Most consumer level displays do have a non linear intensity curve, that means that the grey with the intensity values 128 is not half as bright as the one with intensity 255.

This has repercussions on blending. When not correctly done it will result in black shadows along blend lines and in letters that appear too thin.

To resolve this problem use the following rules:

• when drawing into a display buffer use the gamma value of 2.2
• when drawing into non display buffers use gamma 1 (but make sure that you properly blend when you draw that buffer onto the surface

The SDL output driver provides gamma values for output. OpenGL provides the possibility to set framebuffers to sRGB which results in proper blending when drawn into.

Sub pixel placement

Sub pixel placement allows more accurate placement of pixels onto the screen. It requires a 1:1 correspondence between the framebuffer and the display, so it doesn't work on CRTs and it also doesn't work when the display has to scale the framebuffer.

But when all conditions are met you will get a sharper result and more evenly distributed letters.

The output routines need to know the sub pixel arrangement to make the right drawing decisions. If you can not find out and don't want to ask the user for that information don't use it. When used wrongly it will result in ugly output.

Also keep in mind that drawing with sub pixel placement is not possible on surfaces that include an alpha channel because the resulting surface can not properly drawn onto any other surface. This would require separate alpha channel for each colour component.

Sub pixel drawing only properly works when drawing directly onto the target. When drawing onto surfaces with an alpha channel, the alpha of all the pixels are untouched assuming that the background is properly prepared for the glyphs (e.g. opaque)

Output Classes

Output functions are always a member of a class. These classes encapsulate the state for drawing, but more importantly they encapsulate the glyph cache.

The glyph cache is there to avoid unnecessary re-rasterization of the glyphs. Each output class might come with its own type of cache.

When you want to draw you create an instance of those classes and then use the draw function of that instance.

OpenGL drawing

The OpenGL output class is a bit different from the usual C++ code, as it requires you to include the OpenGL header of your choice before you include the header for this module.

This is so because there is no proper header and each project might choose a different extension wrangler.

The class has a template argument V with which you choose your OpenGL version.

• 1 results in an output class for OpenGL up to version 1.1. It uses the fixed function pipeline and display lists. Sub-pixel placement requires 3 drawing passes
• 1 creates the output class for OpenGL 2.0 - 2.1. It uses vertex buffers and shaders for output. It also requires 3 drawing passes for sub-pixel drawing
• 3 finally is intended OpenGL starting with version 3.0. It uses vertex array objects and the ARB_BlendFuncExtended extension for single pass sub-pixel placement

All 3 OpenGL output classes use the same type of glyph-cache: a texture atlas. The functions will place as many glyphs of the layout to show into the atlas, output that portion, wipe the atlas and refill it with the next batch until it is filled again and so on. So it is important for performance to have a texture atlas that is big enough to hold all required glyphs.

You can specify 2 sizes for the texture atlas: an initial size and a maximal size. The output class will create square textures of the given sizes starting with the initial size and doubling that until it reached at least the maximal size (it might end up with a bigger size).

The OpenGL output classes can work with a cache object that stores information to quickly draw a layout. This class has a different content depending on the chosen OpenGL version, so it is kept opaque for the user Create an instance of this class and give a pointer to this instance to the drawing function. It will then fill the cache in such a way that redrawing the same layout later on (even at a different position) will be much faster (twice usually). You need a separate instance of this class for each layout and you need to make sure on your own, that the class is deleted, when the layout changes. Once the cache is filled the show function will always draw the same, independent of the layout.

The drawing function will invalidate the cache and recreate it though, when the texture cache has changed. Size increasing will be handled without drawing cache invalidation, but when the cache had to be flushed all existing drawing caches are invalid.

A few tips regarding texture atlas usage:

• stay away from blurr, it occupies quite a bit more space than a normal glyph. It also requires underlines to be within the cache. At a minimum keep the blurr very small
• sub-pixel output requires 3 times as much space as normal anti-aliased output
• you can get a pointer to the cache with the getData funtion to see how much is occupied

TODO list touched state.