Helper libraries, tools and resources for SDL

Overview

This section focuses on the listing of:

• the major libraries that can be complementary to SDL. Promised, it is not an infamous plug for our own libraries, Ceylan and OSDL!
• the various tools that proved useful for SDL applications
• some resources directly related to the use of these libraries and tools

Due to the amount of relevant informations, this is still a document in progress and any help would be appreciated.

Table of contents

The SDL family

Around the SDL core library, there are some other libraries that provide complementary services. Each of these so-called standard libraries, whose name begins with "SDL_", focuses on a particular theme:

• SDL_image allows to load into SDL surfaces a large number of popular image formats: BMP, PNM (PPM/PGM/PBM), XPM, LBM, PCX, GIF, JPEG, PNG, TGA, and TIFF [Wiki]
• SDL_sound [more infos about sound with SDL]
• SDL_mixer is a multi-channel audio mixer library [Wiki] [more infos about sound with SDL]
• SDL_net is a cross-platform networking library [Wiki]
• SDL_ttf
• SDL_gfx provides drawing primitives and other support functions

Some less known SDL-related libraries exist, such as SDL_rtf, which allows to display Rich Text Format (RTF) documents in a SDL application.

Build-related tools

• CMake, portable build system
• Scons, portable build based on python

Package-related tools

Once written and tested, an application has to be officially released and distributed. As SDL-based applications are often cross-platform, the distribution and packaging concerns are particularly strong.

• Autopackage, to build linux binaries compatible with many distributions

Fonts section

Font libraries

The most known library to display TrueType fonts in the SDL world is SDL_ttf.

Alternatives to SDL_ttf, other popular add-on libraries for rendering bitmap text, are SFont, Krnfont, and Kyra. They use a single bitmap image with spacing information in the top pixel row to define a font.

For simple text display, one can use the dedicated primitives provided by SDL_gfx (see stringColor and stringRGBA).

To get more control over one's text and less overhead, one might use FreeType directly, instead of going through SDL_TTF, although FreeType is deemed difficult to use that way.

One can use as well Glyph Keeper.

Fonts & OpenGL

Bitmap Font Builder makes it easy to create bitmaps for use in OpenGL (and DirectX) applications.

The Polyfonts library draws text into all types of SDL surfaces. It works the same on software and hardware surfaces as it does on OpenGL surfaces, where the fonts are stored as geometry in the form of OpenGL rendering commands and vertex data. That means that all the fonts can be drawn in any size and any orientation.

Polyfonts has a large number of fonts converted to geometry, so they can be rendered without ever creating a texture. It includes a number of stroke fonts that can be drawn very quickly with OpenGL, but because of the large number of triangles needed to represent most outline fonts it can be a bit slow for rendering antialiased outline fonts. Use pre-rendering in that case.

Other OpenGL-related tools for fonts are OpenGL-FreeType Library (OGLFT) and, if you are working in C++, FTGL [homepage]. They both require FreeType and convert TTF fonts to geometry, and then render then from that.

More infos about OpenGL textures related to fonts.

Pre-rendering

To display static or even TTF text, pre-rendering is the safe and efficient way. For text that changes, render all glyphs to surfaces or, with OpenGL, to textures. Paste them together to form text.

More precisely, for outline fonts one may render each glyph/size/color once when it is first used by the program, and convert it to a surface or texture at that point. Then the text is either drawn by surface blitting or texture mapping on quads, for each individual glyph in a string.

It also means one have a texture for each glyph that has been used; it is surprising how few glyphs are ever used. This method seems to be a good way to render antialiased text.

Where to find fonts you can freely use

Since, with SDL_ttf for example, displaying Truetype fonts is made easy, one just has to find freely-distributable fonts for his application. This can be a tricky task, since many "free fonts" found in the Internet infringe licensing schemas. Here are some pointers to the most known fonts which are freely distributable, roughly sorted by decreasing confidence in their legality. Some of these fonts are released under the GPL license.

Please ensure that you have been granted permission or you obtained a license of use for the fonts you use, if they are not truly free for your needs.

• larabiefonts: awesome work indeed
• SDL_ttf recommended fonts: Free UCS Outline Fonts, FontHead (freeware)
• Gnome fonts
• Polyfonts provides some fonts too
• Kvota, for cyrillic glyphs
• dejavu
• 1001fonts
• freeunifont
• FreakyFonts
• Varian Fonts
• Microsoft (non-free)
• Google Font search

The most beautiful fonts that are free for use often do not include enough characters for internationalization.

SDL_ttf section

The SDL_ttf library is one of the standard SDL libraries. [Wiki]

SDL_ttf 2.x uses FreeType 2 (not 1.2, as stated in the docs).

SDL_ttf hints

• For each call to text = TTF_RenderText_Solid( myFont, message, color ), there must be a call to SDL_FreeSurface( text )
• On program exit, or when you do not need the font anymore, call TTF_Closefont( myFont )
• When you are done using the ttf library (usually at exit), do TTF_Quit()
• Always check that your font file exists before giving it to TTF_Font (TTF_OpenFont does not seem to check it!)
• If you are planning a GNU/Linux version, do not use TTF_RenderText_Solid,, that does not work on this platform. One may use, as a work-around, SDL_RenderText_Shaded and set the colorkey of the surface.

SDL_ttf troubleshooting

Problem when trying to read fonts from RWops, when the font data is somewhere in a larger file

This is because SDL_ttf seeks to some offset from SEEK_SET or SEEK_END. If the RWops object is created with SDL_RWFromFP, SEEK_END naturally refers to the end of the file, and SEEK_SET to the beginning of the file, not to the position of the file pointer at the time when the RWops object was created. This can by solved by making a more flexible RWops creation function, which allows the user to specify which range of the file is to be used.

Using TTF_RenderText_Solid and encountering problems

Try using another function, such as TTF_RenderText_Blended

You see unexpected empty squares (little boxes)

One may see only empty squares instead of the expected characters. This little box is the default glyph that you get when you ask for nonexistent glyphs. Here are the most common reasons and solutions for that issue:

• always check the glyph indexes first
• if classical letters are often available, not all fonts support all symbols
• using a wrong version of libttf. Older versions do not handle all the features of some fonts. You might be using the version of libttf that is legal to use in the US. That version of the library does not implement certain patented features of the TTF specification. It does not implement them because it can not legal do so.
• you are using a bitmap font, which SDL_ttf does not handle well.

With the same code, the font displays with different sizes on different systems

For example, when using a program like MS-Word or PaintShop Pro to draw the font at a given point size (32 for instance) it looks much larger than if SDL_ttf is used to blit it on the screen using the showfont demo. The difference is that PaintShop is rendering the TTF font at 72 dpi, whereas SDL is rendering it at the dpi of your monitor, where is probably 96 dpi (hence appearring smaller).

Problem compiling with FreeType (needed by SDL_ttf)

In SDL_ttf.c, add the following:

#include <ft2build.h> #include FT_FREETYPE_H #include FT_OUTLINE_H #include FT_TRUETYPE_IDS_H #include <freetype/internal/ftobjs.h>

and remove the following:

#include <freetype/freetype.h> #include <freetype/ftoutln.h> #include <freetype/ttnameid.h>

Or see our LOANI automatic installer: generateSDL_ttf in loani-requiredTools.sh auto-corrects SDL_ttf.c.

Freetype and SDL versions

Freetype 2.1.5 is the last known version of Freetype to work seamlessly with SDL_ttf 2.0.6.

Abstract file-system, encryption, compression & related

PhysicsFS

PhysicsFS is a file-system library. This efficient library is convenient, however it does not come packaged with most Linux distributions that allow you to install via CD. This is not a problem though in windows where you can just drop in the DLL.

With MinGW, to avoid main.c: undefined reference to `WinMain@16', use: make LDFLAGS=-lmingw32.

Boost Filesystem Library

To be found here, its drawback is that Boost implies numerous dependencies.

One can use zziplib to read ZIP archives.

fnkdat

fnkdat provides a platform independant interface for determining common directory names [homepage].

Graphics & rendering

SGE (SDL Graphics Extension)

http://www.etek.chalmers.se/~e8cal1/sge/

SDL_gfx

Windows DLL

To compile SDL_gfx for Dev-Cpp or for Mingw32, basically you need to add a couple of defines that are not set by default:

-DBUILDING_DLL=1
-DBUILD_DLL=1
-DWIN32

One needs to simply compile the library sources (.c/.h) with the defines -DWIN32 and -DBUILD_DLL when creating the DLL. Use the define -DWIN32 when using the DLL.

There are VC6 and VC7 project files included in the SDL_gfx distribution, but some users reported that there were not working properly.

Using rotozoom

The rotozoom routine creates a new surface. You usually use it like this (pseudocode):

sourceSurface = loadimage( "image.png" ) ;
const unsigned int steps = 10 ;

float angle ;

for ( unsigned int i = 0; i < steps; i++ )
{
   angle = i * 360 / steps ;
   rotatedSurfaces[i] = rotozoom( sourceSurface, angle, ...) ;
}

This pre-rotates your images and caches them for later use. It works well for smaller images since caching uses memory. To get good quality, your input should be 32bit (i.e. PNG with transparency) and interpolation should be enabled in the rotozoom routine.

A smarter approach would be to cache only a few images relevant to the current game state (i.e. angle-20, angle-10, angle, angle+10, angle+20) and re-render to update the cache as needed when the game state is changed. That way, you can optimize to save a rotozoom for every single state change.

Once you have the new surface, you can determine its center from its dimensions and blit as usual using clipping to limit its visibility to a rectangular area.

Vector graphics libraries

Here are some hardware accelerated vector graphics libraries:

• SVGL
• SDL_svg
• Batik (Java-based)
• Haven (for Haskell)
• Anti-Grain Geometry can draw to SDL surfaces

Using dedicated vector graphics libraries can help a lot, since OpenGL and DirectX are much more low level. Consider the OpenGL calls which would be required to render this vector-graphic image.

Both Smoke and SVGL aim to render such vector graphics by converting the conventional vector-graphics primitives (gradient and radial fills; areas enclosed by implicit lines and curves; stroked contours etc.) into OpenGL primitives (filling commands and triangle meshes). The hardest part of this is the efficient tesselation of vector "areas" into triangle meshes

Scaling

It can be performed thanks to SDL_gfx, it is bilinear but SDL_gfx is not as portable as SDL. Zooming is only supported for 8-bpp and 32-bpp surfaces.

A sdl-stretch library is available too.

sdl_glscale patch

Hardware acceleration does not occur in windowed mode. Stephane Marchesin made a new SDL video backend that uses OpenGL to scale the display.

This backend uses another backend to get the window creation and keyboard handling stuff, so it is "portable". For now, it is only tested under linux/X11/i386 but it should work for other platforms with OpenGL support. It's by no means fast, but it can be useful.

Get the patch here. To choose the new screen size, do the following:

export SDL_VIDEODRIVER=glscale
export SDL_VIDEODRIVER_GLSCALE_X=<desired width>
export SDL_VIDEODRIVER_GLSCALE_Y=<desired height>

By default, a 2x window scaling is used.

Image handling

• libpng and zlib must be installed to load a PNG
• SDL_image

Displaying movies & animations

• libxine does all the decoding work. Kaffeine is just a frontend to libxine.
• SMPEG, to play MPEG video files to an SDL surface. See their plaympeg.c example to learn how to use it. Blitting to an off-screen surface is recommended, since blitting directly to the screen might create timing problems, with SMPEG blitting over the other screen renderings without control. You really need to use threaded audio or SMPEG does not work very well. Not that it works particularly well anyway... If you are using Linux you are probably best off using ffmpeg, which is more work but is far better at the job. To overcome some SMPEG build issues, add -lstdc++ into the file smpeg-config [more infos]. Note also that audio must have been initialized before playing videos with smpeg, even if the video does not have any sound. It looks like SMPEG only supports mpeg-1. The way to get SMPEG compiled with shared and static is to use ltconfig and ltmain.sh from the FINK project [see]. The project team gave up on 2001.
• ffmpeg project contains libavcodec, which now has native support for sorensen (used for quicktime), and virtually every other codec you could want. ffmpeg also contains ffplay, which is a simple SDL-based player.
• XviD codec and core Library: very high compression and quality, cross-platform, LGPL

GUI: Graphical User Interface with SDL

• Agar, able to work on top of SDL and/or OpenGL, is the one we favor in OSDL; the GUI is very well suited for games, portable, well designed and well maintained, pure C, easy to integrate
• aedGUI, quick and nice
• Qt, used by KDE. However pay attention to the license if Windows is one of the targeted platform. See also: SDL + Qt example
• WxWidgets (formerly known as wxWindows)
• FLTK, whose usage is really easy: small and the dimensions do not distort over different platforms
• Guichan is a portable C++ GUI library designed for games using Allegro, SDL and/or OpenGL. Its approach is rather minimalistic and you usually end up improving existing widgets to implement basic functionality that is supposed to be available out-of-the-box like password input or listboxes. But it is lightweight and designed for games, relatively new though, not very stable. Not tested in .net2003
• GiGi, OpenGL Graphic User Interface Library (LGPL), needs a number of extra libraries
• SDL can be directly used
• Fox-toolkit, use non-native graphical objects, similar to wxWidgets and Qt, but has less features and is faster
• Ultimate++, Linux and Windows only
• Gtk++, C-based, can be used in C++ with Gtkmm or VDK
• CeGUI, much more complex and mature than guichan

You may also wish to look at the SDL library listing, which has, among other things, several GUI libraries listed.

Sound

• FMOD: the problem with it is that is not a free software, but it is usable for non commercial projects
• SDL_sound is a library that handles the decoding of several popular sound file formats, such as .WAV and .MP3, and supports several others by using external libraries. It only decodes audio files for playing, it does not play them itself [API]
• SDL_mixer, which uses MikMod for module playback. SDL_mixer does all its heavy processing in a seperate thread, so you do not need to spin a thread to keep the audio seperate. Unless there is another reason to keep a seperate thread, just call Mix_LoadWAV and Mix_PlayChannel from the main thread
• Ogg Vorbis is a completely open, patent-free, professional audio encoding and streaming technology with all the benefits of Open Source
• Sphinx2 is a speaker-independent decoding engine for continuous speech

See also: our sound with SDL section.

Events

Fast events is basically a replacement for the event handling functions in SDL. It gets rid of the 10 ms delay (Linux 2.4 time-slice) in the WaitEvent function, and uses threads to update/change the event queue. This makes the event handling go faster.

Other features

OGLCONSOLE is a GPL powerful "never-fail" quake-style drop-down interactive command console for all OpenGL applications.

Thanks to David Wührer for having checked the links.

Please react!

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line!