Working with text in SDL

Using SDL_ttf

Like SDL itself, SDL_ttf first needs to be initialized. The function for doing this is TTF_Init. Likewise, after the program ends, it needs to be uninitialized by calling TTF_Quit.

int TTF_Init(void);
void TTF_Quit(void);

TTF_Init will return 0 if all went well and -1 if an error occurred. TTF_Quit does not return any value.


Creation and Destruction

The creation and destruction functions deal with making and unmaking fonts. The structure that keeps font information is called TTF_Font.

TTF_Font * TTF_OpenFont(const char *file, int ptsize);

This function return pointer to a newly created TTF_Font object. The first parameter is a string that specifies the file name of a TTF file to load. The second parameter is the point size you desire for the font.

One point is 1/72 of an inch. Since computer monitors vary widely, it has been established that 72 pixels make up an inch, although the actual measurement may vary. Therefore, point size
equals pixel size, at least as far as computer graphics are concerned.

Like everything else in SDL, you need to destroy a font when you are done using it by calling TTF_CloseFont.

void TTF_CloseFont(TTF_Font *font);

This function takes a pointer to a TTF_Font object and destroys it. There is no return value.


Rendering

Text can be rendered one of three ways—solid, shaded, or blended. The result is almost the same no matter which way you render; solid is the fastest way, but it has the lowest quality (however, the quality is still not bad at all), rendering shaded gives you a little higher quality, but it is not quite as fast as solid, blended is the highest quality and is the slowest.

The function used to render text is:

SDL_Surface * TTF_RenderText_Solid(TTF_Font *font,const char *text, SDL_Color fg);

As usual, the first parameter is a pointer to a TTF_Font. The second parameter is a pointer to a string that you want to render. The final parameter (fg) is the color in which you would like the text or glyph rendered. The return value is a pointer to a newly created 8-bit SDL_Surface. On this surface, color index 0 is the transparent background, and color index 1 is the color specified in fg.

SDL_Surface * TTF_RenderText_Shaded(TTF_Font *font,const char *text, SDL_Color fg, SDL_Color bg);

It is quite similar to the equivalent solid rendering functions, except for the addition of another SDL_Color parameter called bg. This extra parameter specifies the background color for the
surface that will be created. (It becomes color index 0.) The rest of the colors on the surface are various shades between fg and bg, creating a more smoothly rendered, anti-aliased look for the text. (This shading is why this takes a little more time than solid rendering.) The only real
problem with shaded rendering is that there is no transparent color, so it is only suitable for rendering onto a solid-color background.

SDL_Surface * TTF_RenderText_Blended(TTF_Font *font,const char *text, SDL_Color fg);

It has the same parameters as the equivalent solid rendering function. The difference lies in
what kind of surface is created in response to the function call. Whereas solid rendering will give you an 8-bit palettized surface, blended rendering will give you a 32-bit surface with per-pixel alpha information. This makes for very high-quality font rendering, although it is a bit slower than either the solid or blended rendering.

Once you have rendered your text, thus creating a new surface, you simply use that surface as you would any other, blitting it to the frame buffer and so on.



The concepts mentioned above are made clear in the example below:


#include "SDL/SDL.h"
#include "SDL/SDL_image.h"
#include "SDL/SDL_ttf.h"

//Screen attributes
const int SCREEN_WIDTH = 640;
const int SCREEN_HEIGHT = 480;
const int SCREEN_BPP = 32;

//The surfaces
SDL_Surface *background = NULL;
SDL_Surface *message = NULL;
SDL_Surface *screen = NULL;

//The event structure
SDL_Event event;

//The font that's going to be used
TTF_Font *font = NULL;

//The color of the font
SDL_Color textColor = { 255, 255, 255 };

void apply_surface( int x, int y, SDL_Surface* source, SDL_Surface* destination, SDL_Rect* clip )
{
//Holds offsets
SDL_Rect offset;

//Get offsets
offset.x = x;
offset.y = y;

//Blit
SDL_BlitSurface( source, clip, destination, &offset );
}

int main(int argc, char* argv[])
{
//Quit flag
int quit = 0;
SDL_Init(SDL_INIT_EVERYTHING);
TTF_Init();
//Set up the screen
screen = SDL_SetVideoMode( SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_BPP, SDL_SWSURFACE );
//Set the window caption
SDL_WM_SetCaption( "TTF Test", NULL );
//Load the background image
background = IMG_Load( "background.png" );

//Open the font
font = TTF_OpenFont( "CALIBRI.ttf", 50 );

//Render the text
message = TTF_RenderText_Solid( font, "Hello, World!", textColor );
//Apply the images to the screen
apply_surface( 0, 0, background, screen,0 );
apply_surface( 200, 150, message, screen,0 );
SDL_Flip( screen );
//While the user hasn't quit
while( quit == 0 )
{
//While there's events to handle
while( SDL_PollEvent( &event ) )
{
//If the user has Xed out the window
if( event.type == SDL_QUIT )
{
//Quit the program
quit = 1;
}
}
}
//Free the surfaces
SDL_FreeSurface( background );
SDL_FreeSurface( message );

//Close the font that was used
TTF_CloseFont( font );

//Quit SDL_ttf
TTF_Quit();

//Quit SDL
SDL_Quit();
return 0;
}


The source code is available at:

http://www.mediafire.com/?no24x4b7pd3feov