Chapter 5: Text and font handling
This chapter will introduce you on how to load fonts and write to the screen. The ability for this is not implemented in the original SDL library itself but Sam Lantinga provides an add-on to SDL called SDL_TTF to work with texts based on the FreeType project and their FreeType 2.0 release. Fortunately the JEDI-SDL project also provides this unit for Freepascal called SDL_TTF as well. So for preparation we have to do three things (sorry the following instructions are for Windows only but should be similar for Linux system as well. The examples after the three steps of installing should work for Linux, too.):You need this .dll file:
| Software | Version | Source | Description |
|---|---|---|---|
| SDL_ttf-2.0.10-win32.zip | 2.0.10 | http://www.libsdl.org/projects/SDL_ttf/ | This is the corresponding dynamic link library file. |
You should extract the zip-file and get two files. A text file and the important SDL_ttf.dll. Analogous to SDL.dll in chapter 1 you have to copy them to the system32-folder. If you forget this and run the examples below you will get an error with exitcode = 309.
First of all we want to discuss the principle behind adding text to the screen within the SDL environment. Any text which is written to the screen is a simple surface itself which gets blit to the screen surface as done with graphics seen in previous chapters. In practice this means we need the screen surface again and a surface onto which can be written (here: "fontface"). The text content in the fontface surface will then be blitted to the screen surface. A simple diagram may illustrate this.
You probably wondered already how to get the text to the "fontface" though. Exactly therefore we need the new SDL_TTF unit which has to be loaded by adding SDL_TTF to the uses clause. It provides the command TTF_RENDERTEXT_...(font, text, colour) which creates a surface with a given font, text and colour. This procedure is illustrated by the first arrow in the diagram. In fact there is not just one but many different TTF_RENDERTEXT_... modes which differ (hinted at by the three dots) in arguments list, quality, render speed and other properties. The following table will give you an overview. For dynamic ingame text or chats the solid mode is the best choice since it is the fastest rendering mode and also provides simple transparency. The following table will give you a brief overview of the modes and their properties.
| Function | Transparency | Antialiasing | Colour depth and format | Quality | Speed |
|---|---|---|---|---|---|
| TTF_RENDERTEXT_... in general creates surfaces with the given text (of type pChar) in ISO 8859-1 (Latin1) format; analogous you can use TTF_RENDERUTF8_... to get the the text in the corresponding UNICODE Transformation Format 8. | |||||
| TTF_RENDERTEXT_SOLID(font, text, colour); | yes (colorkey, 0 pixel) | no | 8-bit palettized (RGB) | low | very fast |
| TTF_RENDERTEXT_SHADED(font, text, colour1, colour2); | no (0 pixel is background colour) | yes | 8-bit palettized (RGB) | high | fast |
| TTF_RENDERTEXT_BLENDED(font, text, colour); | yes (alpha channel) | yes | 32-bit unpalettized (RGBA) | very high | slow |
| TTF_RENDERGLYPH_... in general creates surfaces with the corresponding UNICODE glyph letter (of type WORD); analogous you can use TTF_RENDERUNICODE_... to get the corresponding UNICODE letter but attention: you have to give the letter's number as pointer, so number is of type ^WORD. | |||||
| TTF_RENDERGLYPH_SOLID(font, number, colour); | yes (colorkey) | no | 8-bit palettized (RGB) | low | very fast |
| TTF_RENDERGLYPH_SHADED(font, number, colour1, colour2); | no (0 pixel is background colour) | yes | 8-bit palettized (RGB) | high | fast |
| TTF_RENDERGLYPH_BLENDED(font, number, colour); | yes (alpha channel) | yes | 32-bit unpalettized (RGBA) | very high | slow |
All of the given commands are functions and will return the NIL pointer (instead of the new surface) if the text or letter rendering failed. Let's have a look at the code.
PROGRAM chap5;
USES SDL, SDL_TTF;
VAR
screen, fontface:pSDL_SURFACE;
loaded_font:pointer;
colour_font, colour_font2:pSDL_COLOR;
i:BYTE;
BEGIN
SDL_INIT(SDL_INIT_VIDEO);
screen:=SDL_SETVIDEOMODE(400,200,32,SDL_SWSURFACE);
IF screen=NIL THEN HALT;
IF TTF_INIT=-1 THEN HALT;
loaded_font:=TTF_OPENFONT('C:\WINDOWS\fonts\arial.ttf',40);
NEW(colour_font);
NEW(colour_font2);
colour_font^.r:=255; colour_font^.g:=0; colour_font^.b:=0;
colour_font2^.r:=0; colour_font2^.g:=255; colour_font2^.b:=255;
fontface:=TTF_RENDERTEXT_SHADED(loaded_font,'HELLO WORLD!',colour_font^,colour_font2^);
SDL_BLITSURFACE(fontface,NIL,screen,NIL);
SDL_FLIP(screen);
READLN;
DISPOSE(colour_font);
DISPOSE(colour_font2);
SDL_FREESURFACE(screen);
SDL_FREESURFACE(fontface);
TTF_CLOSEFONT(loaded_font);
TTF_QUIT;
SDL_QUIT;
END.
|
As always now we look at the code step by step.
PROGRAM chap5; USES SDL, SDL_TTF; VAR screen, fontface:pSDL_SURFACE; loaded_font:pointer; colour_font, colour_font2:pSDL_COLOR; i:BYTE; |
The program is initilized with the name "chap5". The unit SDL as well SDL_TTF has to be given in the uses clause! Remember please that the True Type Font system is an individual separate project and therefore you have to add this unit separately.
There are two pSDL_SURFACE variables. screen is for displaying at the physical screen as known, fontface will store the generated text by the True Type Font system before it is blitted to the screen finally. loaded_font will store font and is of pointer type. colour_font and colour_font2 are storing the text and background colour of the generated text later, they are of a specific SDL colour type which will be discussed in more detail later. i is a counting variable as known.
BEGIN
SDL_INIT(SDL_INIT_VIDEO);
screen:=SDL_SETVIDEOMODE(400,200,32,SDL_SWSURFACE);
IF screen=NIL THEN HALT;
IF TTF_INIT=-1 THEN HALT;
loaded_font:=TTF_OPENFONT('C:\WINDOWS\fonts\arial.ttf',40);
|
First the SDL system has to initilized as known from all the previous chapters. To initialize the TTF (True Type Font) system you have to use TTF_INIT which returns -1 if something failed. Notice again that the whole true type support is an own additional project (FreeType project) to the SDL library, so this cannot to be initilized by the SDL_INIT command.
To load a certain font you use TTF_OPENFONT(font,point size), or more specific TTF_OPENFONT(const filename:PCHAR; ptsize:INTEGER):pTTF_FONT. This command is a function that returns a usual pointer (which pTTF_FONT actually is)! The parameters are the absolute(!) path to the font (e.g. C:\WINDOWS\fonts\arial.ttf) and the point size which detemines the size of the letters. These font information are accessed by the loaded_font pointer initially defined.
NEW(colour_font); NEW(colour_font2); colour_font^.r:=255; colour_font^.g:=0; colour_font^.b:=0; colour_font2^.r:=0; colour_font2^.g:=255; colour_font2^.b:=255; |
So next we have to determine the colour of the letters and the message itself. The colour is determined by a pSDL_COLOR record, which is of course kind of pointer. In pSDL_COLOR record there are three elements (actually four, but the forth is unused) which can be accessed by .r,.g and .b and determine as common the shares of red, green and blue colour. You will agree that writing a function allocation of RGB triples can be senseful, especially if you have to handle many different colours but for our example we won't do this though since we just have to define two colours. The fact that pSDL_COLOR is of pointer type needs us to set colour_font and colour_font2 up by NEW command and free it finally by DISPOSE. These commands you should be familiar with because they are usual Pascal commands.
fontface:=TTF_RENDERTEXT_SHADED(loaded_font,'HELLO WORLD!',colour_font^,colour_font2^); |
Now we use TTF_RENDERTEXT_SHADED(font, text, colour1, colour2), or more specific TTF_RENDERTEXT_SHADED(font:pTTF_FONT; const text:PCHAR; fg:tSDL_COLOR; bg:tSDL_COLOR):pSDL_SURFACE, which we introduced recently (check the table). It returns a pSDL_SURFACE. We return it to fontface. The parameters are the used font as pointer (loaded_font), the message string and the colours (colour_font, colour_font2). colour_font will provide the foreground colour which should be red since we defined R=255, G=0, B=0. The background should get cyan since we defined R=0, G=255, B=255. If the rendering process works fine we have the text in the specified colours in fontface.
SDL_BLITSURFACE(fontface,NIL,screen,NIL); SDL_FLIP(screen); READLN; DISPOSE(colour_font); DISPOSE(colour_font2); SDL_FREESURFACE(screen); SDL_FREESURFACE(fontface); TTF_CLOSEFONT(loaded_font); TTF_QUIT; SDL_QUIT; END. |
The fontface surface is a usual SDL surface so you can now do every manipulation you want or at least blit it to the screen surface and display the text after updating/flipping.
Finally all the variables and surfaces have to disposed as known. Like every SDL surface has to be free'd and SDL system has to be quit so has the TTF system. The procedures TTF_CLOSEFONT(font:pTTF_FONT) and TTF_QUIT have to be used to do this.
Now you are able to write ;).
This file contains the source code: chap5.pas (right click and "save as")
This file is the executable: chap5.exe (right click and "save as")
 |
The final result should look and behave like this: The text "Hello World!" is displayed having red letters on cyan background. |
to mainpage
Creation/Updates: 27/5/2011; 8/8/2010; 19/4/2009; 13/7/2008; 7/10/2007; 15/6/2007
There is no guarantee that things will work! You do everything described here on your own risk! © M. Molski 2005-2011. All product and company names, brand names, trademarks and logos are the property of their respective owners.