SDL_Pango Documentation

0.1.2

Introduction

Pango is the text rendering engine of GNOME 2.x. SDL_Pango connects the engine to SDL. In Windows, pre-built binary package (MSI and merge module) is provided.

Distribution

If you are a game software developer, you should know the difficulties of distribution. So I will start to introduce SDL_Pango from the viewpoint of distribution.

In Un*x, SDL_Pango is hard to use as system-independent module, because it depends on fontconfig and Pango which are designed as system-singleton modules. If you use SDL_Pango, your software will require those modules installed to target system. If your software is shipped as shrink-wrap package, it may cause much problem on your support desk. You should carefully design your installation process.

In Windows, SDL_Pango is distributed as "merge module" which contains fontconfig and Pango. Those binaries are modified as side-by-side components. You should use Windows Installer and merge the module on your MSI package. The merge module not only contains files, but also includes custom action which must be run at installation.

High-level API

From the viewpoint of text rendering, the heart of SDL_Pango is high-level API. Other text rendering APIs, like DrawText() of Windows, font and text must be specified separately. In SDL_Pango, font specification is embedded in text like HTML:

    <span font_family="Courier New"><i>This is Courier New and italic.</i></span>

Color, size, subscript/superscript, obliquing, weight, and other many features are also available in same way.

Internationalized Text

Internationalized text is another key feature. Text is specified by UTF-8. RTL script (Arabic and Hebrew) and complicated rendering (Arabic, Indic and Thai) are supported. You can see it with GNOME 2.x.

Getting Started

Get latest files

Get latest files from http://sourceforge.net/projects/sdlpango/ .

Install Header and Library

In Windows and VS2003, I strongly recommend you to install MSI package. It contains Pango and fontconfig binaries which are modified as side-by-side components. It is nearly impossible to build them. (I spent much time to build them...)

In MinGW, I recommend you to use VS2003. Otherwise you may run into the maze of distribution. If you insist MinGW, you should use MinGW binary archive.

In Un*x, installation consists of:

    ./configure
    make
    make install

Includes

To use SDL_Pango functions in a C/C++ source code file, you must use the SDL_Pango.h include file:

    #include "SDL_Pango.h"

In Windows, SDL_Pango.h is installed on %ProgramFiles%\SDL_Pango Development\include (usually C:\Program Files\SDL_Pango Development\include). You should add this directory to include path.

Compiling

In Un*x, to link with SDL_Pango you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_Pango is quite easy.

Note: Some systems may not have the SDL_Pango library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

    cc -c `sdl-config --cflags` mysource.c

Simple Example for linking an object file:

    cc -o myprogram mysource.o `sdl-config --libs` -lSDL_Pango

Now myprogram is ready to run.

You can see a sample of autoconfiscation in 'test' directory.

In Windows, MSI package installs many dlls to %ProgramFiles%\SDL_Pango Development\import_lib. To link with SDL_Pango you should use SDL_Pango.lib.

SDL_Pango.dll depends on many dlls and other many files. Those dlls are installed on %ProgramFiles%\SDL_Pango Development\bin. MSI package adds the directory to PATH environment variable.

Development

Font Handling

In Un*x, font handling depends on fontconfig of your system.

In Windows, local.conf of fontconfig is placed on %ProgramFiles%\SDL_Pango Development\etc\fonts. You should know about fontconfig's font cache mechanism.

Step-by-step Example

The operation of SDL_Pango is done via context.

    SDLPango_Context *context = SDLPango_CreateContext();

Specify default colors and minimum surface size.

    SDLPango_SetDefaultColor(context, MATRIX_TRANSPARENT_BACK_WHITE_LETTER);
    SDLPango_SetMinimumSize(context, 640, 0);

Set markup text.

    SDLPango_SetMarkup(context, "This is <i>markup</i> text.", -1);

Now you can get the size of surface.

    int w = SDLPango_GetLayoutWidth(context);
    int h = SDLPango_GetLayoutHeight(context);

Create surface to draw.

    int margin_x = 10;
    int margin_y = 10;
    SDL_Surface *surface = SDL_CreateRGBSurface(SDL_SWSURFACE, 
        w + margin_x * 2, h + margin_y * 2,
        32, (Uint32)(255 << (8 * 3)), (Uint32)(255 << (8 * 2)),
        (Uint32)(255 << (8 * 1)), 255);

And draw on it.

    SDLPango_Draw(context, surface, margin_x, margin_y);

You must free the surface by yourself.

    SDL_FreeSurface(surface);

Free context.

    SDLPango_FreeContext(context);

You can see actual code in test/testbench.cpp.

Packaging

In Un*x, do it yourself.

In Windows, font files must be installed on apprication folder (usually C:\Program Files\[Manufacturer]\[ProductName]). The property of apprication folder must be TARGETDIR (this is default setting of VS2003). SDL.dll also must be installed on apprication folder. Add SDL_Pango.msm to your MSI package.

Acknowledgment

SDL_Pango is developed with financial assistance of Information-technology Promotion Agency, Japan.

• NAKAMURA Ken'ichi <nakamura@sbp.fp.a.u-tokyo.ac.jp>

---