SDL_ttf 2.0.7

1. Overview

The README from the SDL_ttf distribution

2. Getting Started

Using SDL_ttf

3. Functions		Functions supported by the SDL_ttf API
4. Types		Types used with the SDL_ttf API
5. Defines		Defined values/macros in the SDL_ttf API

6. Glossary

Terms used in this document

Index

Index of selected words

1. Overview

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I've used SDL_ttf as one of the many methods of putting text on my SDL applications, and use it in my own SDL GUI code as well. While this document doesn't explain how and where to get fonts to use, it will explain how to use them with SDL_ttf.

Feel free to contact me: jcatki@jcatki.no-ip.org

The latest version of this library is available from:
SDL_ttf Homepage

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_ttf source archive.

This library is a wrapper around the excellent FreeType 1.2 library, available at: Freetype Homepage WARNING: There may be patent issues with using the FreeType library. Check the FreeType website for up-to-date details. This library allows you to use TrueType fonts to render text in SDL applications. To make the library, first install the FreeType library, then type 'make' to build the SDL truetype library and 'make all' to build the demo application. Be careful when including fonts with your application, as many of them are copyrighted. The Microsoft fonts, for example, are not freely redistributable and even the free "web" fonts they provide are only redistributable in their special executable installer form (May 1998). There are plenty of freeware and shareware fonts available on the Internet though, and may suit your purposes. Please see the file "COPYING" for license information for this library. Enjoy! -Sam Lantinga slouken@devolution.com (5/1/98)

2. Getting Started

This assumes you have gotten SDL_ttf and installed it on your system. SDL_ttf has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure make make install

SDL_ttf supports loading fonts from TrueType font files, normally ending in .ttf, though some .fon files are also valid for use. Note that most fonts are copyrighted, check the license on the font before you use and redistribute.

You may also want to look at some demonstration code which may be downloaded from:
http://jcatki.no-ip.org/SDL_ttf/

2.1 Includes		The include files to use for SDL_ttf
2.2 Compiling		Using the SDL_ttf library and header file.

2.1 Includes

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

#include "SDL_ttf.h"

2.2 Compiling

To link with SDL_ttf you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_ttf is quite easy.
Note: Some systems may not have the SDL_ttf 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 compiling an object file: cc -o myprogram mysource.o `sdl-config --libs` -lSDL_ttf

Now myprogram is ready to run.

3. Functions

These are the functions in the SDL_ttf API.

3.1 General		API activation, info, and error handling
3.2 Management		Loading fonts from files or memory
3.3 Attributes		Getting and Setting font attributes
3.4 Render		Drawing strings and glyphs with a font

3.1 General

These functions are useful, as they are the only/best ways to work with SDL_ttf.

Info

3.1.1 TTF_Linked_Version

Get version number

Activation

3.1.2 TTF_Init		Initialize API
3.1.3 TTF_WasInit		Query API initialization status
3.1.4 TTF_Quit		Cleanup API

Errors

3.1.5 TTF_SetError		Set the current error string
3.1.6 TTF_GetError		Get the current error string

3.1.1 TTF_Linked_Version

const SDL_version *TTF_Linked_Version()
void TTF_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.

SDL_version compile_version, *link_version; TTF_VERSION(&compile_version); printf("compiled with SDL_ttf version: %d.%d.%d\n", compile_version.major, compile_version.minor, compile_version.patch); link_version=TTF_Linked_Version(); printf("running with SDL_ttf version: %d.%d.%d\n", link_version->major, link_version->minor, link_version->patch);

See Also:
3.1.2 TTF_Init

3.1.2 TTF_Init

int TTF_Init()

Initialize the truetype font API.
This must be called before using other functions in this library, excepting TTF_WasInit.
SDL does not have to be initialized before this call.

Returns: 0 on success, -1 on errors

if(TTF_Init()==-1) { printf("TTF_Init: %s\n", TTF_GetError()); exit(2); }

See Also:
3.1.4 TTF_Quit, 3.1.3 TTF_WasInit

3.1.3 TTF_WasInit

int TTF_WasInit()

Query the initilization status of the truetype font API.
You may, of course, use this before TTF_Init to avoid initilizing twice in a row. Or use this to determine if you need to call TTF_Quit.

if(!TTF_WasInit() && TTF_Init()==-1) { printf("TTF_Init: %s\n", TTF_GetError()); exit(1); }

See Also:
3.1.2 TTF_Init, 3.1.4 TTF_Quit

3.1.4 TTF_Quit

void TTF_Quit()

Shutdown and cleanup the truetype font API.
After calling this the SDL_ttf functions should not be used, excepting TTF_WasInit. You may, of course, use TTF_Init to use the functionality again.

TTF_Quit(); // you could SDL_Quit(); here...or not.

See Also:
3.1.2 TTF_Init, 3.1.3 TTF_WasInit

3.1.5 TTF_SetError

void TTF_SetError(const char *fmt, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with TTF_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

int myunimplementedfunc(int i) { TTF_SetError("myunimplementedfunc is not implemented! %d was passed in.",i); return(-1); }

See Also:
3.1.6 TTF_GetError

3.1.6 TTF_GetError

char *TTF_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_ttf function call.

Returns: a char pointer (string) containing a human readable version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", TTF_GetError());

See Also:
3.1.5 TTF_SetError

3.2 Management

These functions deal with loading and freeing a TTF_Font.

Loading

3.2.1 TTF_OpenFont		From a file
3.2.2 TTF_OpenFontRW		Using RWops
3.2.3 TTF_OpenFontIndex		From a file, with an index
3.2.4 TTF_OpenFontIndexRW		From memory, with an index

Freeing

3.2.5 TTF_CloseFont

Free a loaded font

3.2.1 TTF_OpenFont

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

file

File name to load font from.

ptsize

Point size (based on 72DPI) to load font as. This basically translates to pixel height.

Load file for use as a font, at ptsize size. This is actually TTF_OpenFontIndex(file, ptsize, 0). This can load TTF and FON files.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf at size 16 into font TTF_Font *font; sample=TTF_OpenFont("font.ttf", 16); if(!sample) { printf("TTF_OpenFont: %s\n", TTF_GetError()); // handle error }

See Also:
3.2.3 TTF_OpenFontIndex, 3.2.2 TTF_OpenFontRW, 3.2.5 TTF_CloseFont

3.2.2 TTF_OpenFontRW

TTF_Font *TTF_OpenFontRW(SDL_RWops *src, int freesrc, int ptsize)

src

The source SDL_RWops as a pointer. The font is loaded from this.

freesrc

A non-zero value mean is will automatically close/free the src for you.

ptsize

Point size (based on 72DPI) to load font as. This basically translates to pixel height.

Load src for use as a font, at ptsize size. This is actually TTF_OpenFontIndexRW(src, freesrc, ptsize, 0) This can load TTF and FON formats. Using SDL_RWops is not covered here, but they enable you to load from almost any source.
NOTE: src is not checked for NULL, so be careful.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf at size 16 into font TTF_Font *font; sample=TTF_OpenFontRW(SDL_RWFromFile("font.ttf"), 1, 16); if(!sample) { printf("TTF_OpenFontRW: %s\n", TTF_GetError()); // handle error }

Note that this is unsafe because we don't check the validity of the SDL_RWFromFile's returned pointer.

See Also:
3.2.4 TTF_OpenFontIndexRW, 3.2.1 TTF_OpenFont, 3.2.5 TTF_CloseFont

3.2.3 TTF_OpenFontIndex

TTF_Font *TTF_OpenFontIndex(const char *file, int ptsize, long index)

file

File name to load font from.

ptsize

Point size (based on 72DPI) to load font as. This basically translates to pixel height.

index

choose a font face from a multiple font face containing file. The first face is always index 0.

Load file, face index, for use as a font, at ptsize size. This is actually TTF_OpenFontIndexRW(SDL_RWFromFile(file), ptsize, index), but checks that the RWops it creates is not NULL. This can load TTF and FON files.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf, face 0, at size 16 into font TTF_Font *font; sample=TTF_OpenFontIndex("font.ttf", 16, 0); if(!sample) { printf("TTF_OpenFontIndex: %s\n", TTF_GetError()); // handle error }

See Also:
3.2.4 TTF_OpenFontIndexRW, 3.2.1 TTF_OpenFont, 3.2.5 TTF_CloseFont

3.2.4 TTF_OpenFontIndexRW

TTF_Font *TTF_OpenFontIndexRW(SDL_RWops *src, int freesrc, int ptsize, long index)

src

The source SDL_RWops as a pointer. The font is loaded from this.

freesrc

A non-zero value mean is will automatically close/free the src for you.

ptsize

Point size (based on 72DPI) to load font as. This basically translates to pixel height.

index

choose a font face from a multiple font face containing file. The first face is always index 0.

Load src, face index, for use as a font, at ptsize size. This can load TTF and FON formats.
Using SDL_RWops is not covered here, but they enable you to load from almost any source.
NOTE: src is not checked for NULL, so be careful.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf, face 0, at size 16 into font TTF_Font *font; sample=TTF_OpenFontRW(SDL_RWFromFile("font.ttf"), 1, 16, 0); if(!sample) { printf("TTF_OpenFontIndexRW: %s\n", TTF_GetError()); // handle error }

Note that this is unsafe because we don't check the validity of the SDL_RWFromFile's returned pointer.

See Also:
3.2.3 TTF_OpenFontIndex, 3.2.2 TTF_OpenFontRW, 3.2.5 TTF_CloseFont

3.2.5 TTF_CloseFont

void TTF_CloseFont(TTF_Font *font)

font

Pointer to the TTF_Font to free.

Free the memory used by font, and free font itself as well. Do not use font after this without loading a new font to it.

// free the font // TTF_Font *font; TTF_CloseFont(font); font=NULL; // to be safe...

See Also:
3.2.1 TTF_OpenFont, 3.2.2 TTF_OpenFontRW, 3.2.3 TTF_OpenFontIndex, 3.2.4 TTF_OpenFontIndexRW

3.3 Attributes

These functions deal with TTF_Font, and global, attributes.

Global

3.3.1 TTF_ByteSwappedUNICODE

Set default UNICODE byte swapping mode

Font Style

 TTF_GetFontStyle::          Get font render style

 TTF_SetFontStyle::          Set font render style
Font

 TTF_FontHeight::            Get font max height

 TTF_FontAscent::            Get font max ascent

 TTF_FontDescent::           Get font min descent

 TTF_FontLineSkip::          Get font recommended line spacing
Face

 TTF_FontFaces::             Get the number of faces in a font

 TTF_FontFaceIsFixedWidth::  Get whether font is monospaced or not

 TTF_FontFaceFamilyName::    Get current font face family name string

 TTF_FontFaceStyleName::     Get current font face style name string
Glyph

 TTF_GlyphMetrics::          Get individual font glyph metrics
Text

 TTF_SizeText::              Get size of LATIN1 text string as would be rendered

 TTF_SizeUTF8::              Get size of UTF8 text string as would be rendered

 TTF_SizeUNICODE::           Get size of UNICODE text string as would be rendered

3.3.1 TTF_ByteSwappedUNICODE

void TTF_ByteSwappedUNICODE(int swapped)

swapped

if non-zero then UNICODE data is byte swapped relative to the CPU's native endianess.
if zero, then do not swap UNICODE data, use the CPU's native endianess.

This function tells SDL_ttf whether UNICODE (Uint16 per character) text is generally byteswapped. A UNICODE_BOM_NATIVE or UNICODE_BOM_SWAPPED character in a string will temporarily override this setting for the remainder of that string, however this setting will be restored for the next one. The default mode is non-swapped, native endianess of the CPU.

// Turn on byte swapping for UNICODE text TTF_ByteSwappedUNICODE(1);

See Also:
5. Defines

3.4 Render

These functions render text using a TTF_Font.
There are three modes of rendering:

Solid

Quick and Dirty
Create an 8-bit palettized surface and render the given text at fast quality with the given font and color. The 0 pixel value is the colorkey, giving a transparent background, and the 1 pixel value is set to the text color. The colormap is set to have the desired foreground color at index 1, this allows you to change the color without having to render the text again. Colormap index 0 is of course not drawn, since it is the colorkey, and thus transparent, though it's actual color is 255 minus each RGB component of the foreground. This is the fastest rendering speed of all the rendering modes. This results in no box around the text, but the text is not as smooth. The resulting surface should blit faster than the Blended one. Use this mode for FPS and other fast changing updating text displays.

Shaded

Slow and Nice, but with a Solid Box
Create an 8-bit palettized surface and render the given text at high quality with the given font and colors. The 0 pixel value is background, while other pixels have varying degrees of the foreground color from the background color. This results in a box of the background color around the text in the foreground color. The text is antialiased. This will render slower than Solid, but in about the same time as Blended mode. The resulting surface should blit as fast as Solid, once it is made. Use this when you need nice text, and can live with a box...

Blended

Slow Slow Slow, but Ultra Nice over another image
Create a 32-bit ARGB surface and render the given text at high quality, using alpha blending to dither the font with the given color. This results in a surface with alpha transparency, so you don't have a solid colored box around the text. The text is antialiased. This will render slower than Solid, but in about the same time as Shaded mode. The resulting surface will blit slower than if you had used Solid or Shaded. Use this when you want high quality, and the text isn't changing too fast.

Solid

3.4.1 TTF_RenderText_Solid

Draw

 TTF_RenderUTF8_Solid::       Draw

 TTF_RenderUNICODE_Solid::    Draw

 TTF_RenderGlyph_Solid::      Draw
Shaded

 TTF_RenderText_Shaded::      Draw

 TTF_RenderUTF8_Shaded::      Draw

 TTF_RenderUNICODE_Shaded::   Draw

 TTF_RenderGlyph_Shaded::     Draw
Blended

 TTF_RenderText_Blended::     Draw

 TTF_RenderUTF8_Blended::     Draw

 TTF_RenderUNICODE_Blended::  Draw

 TTF_RenderGlyph_Blended::    Draw

3.4.1 TTF_RenderText_Solid

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

font

Font to render the text with. A NULL pointer is not checked.

text

The LATIN1 null terminated string to render.

fg

The color to render the text in. This becomes colormap index 1.

Render the text using font with fg color onto a new surface, using the Solid mode (see section Solid).

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Turn on byte swapping for UNICODE text SDL_Surface *text_surface; if(!(text_surface=TTF_RenderText_Solid(font,"Hello World!", &color))) { //handle error here, perhaps print TTF_GetError at least }

See Also:
TTF_SizeText, TTF_RenderUTF8_Solid, TTF_RenderUNICODE_Solid, TTF_RenderGlyph_Solid, TTF_RenderText_Shaded, TTF_RenderText_Blended

4. Types

These types are defined and used by the SDL_ttf API.

4.1 TTF_Font

The opaque holder of a loaded font

4.1 TTF_Font

typedef struct _TTF_Font TTF_Font;

The opaque holder of a loaded font. You should always be using a pointer of this type, as in TTF_Font*, and not just plain TTF_Font. This stores the font data in a struct that is exposed only by using the API functions to get information. You should not try to access the struct data directly, since the struct may change in different versions of the API, and thus your program would be unreliable.

See Also:
3.2 Management

5. Defines

TTF_MAJOR_VERSION

2
SDL_ttf library major number at compilation time

TTF_MINOR_VERSION

0
SDL_ttf library minor number at compilation time

TTF_PATCHLEVEL

7
SDL_ttf library patch level at compilation time

UNICODE_BOM_NATIVE

0xFEFF
This allows you to switch byte-order of UNICODE text data to native order, meaning the mode of your CPU. This is meant to be used in a UNICODE string that you are using with the SDL_ttf API.

UNICODE_BOM_SWAPPED

0xFFFE
This allows you to switch byte-order of UNICODE text data to swapped order, meaning the reversed mode of your CPU. So if your CPU is LSB, then the data will be interpretted as MSB. This is meant to be used in a UNICODE string that you are using with the SDL_ttf API.

TTF_STYLE_NORMAL

0x00
Used to indicate regular, normal, plain rendering style.

TTF_STYLE_BOLD

0x01
Used to indicate bold rendering style. This is used a bitmask along with other styles.

TTF_STYLE_ITALIC

0x02
Used to indicate italicized rendering style. This is used a bitmask along with other styles.

TTF_STYLE_UNDERLINE

0x04
Used to indicate underlined rendering style. This is used a bitmask along with other styles.

See Also:
6. Glossary,

6. Glossary

Byte Order

This all has to do with how data larger than a byte is actually stored in memory. The CPU expects 16bit and 32bit, and larger, data to be ordered in one of the two ways listed below. SDL has macros which you can use to detemine which endian your program will be using. Big-Endian(MSB) means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered. (SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN) Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines. (SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

LATIN1

Latin-1 is an extension of ASCII, where ASCII only defines characters 0 through 127. Latin-1 continues and adds more common international symbols to define through character 255.

Index

Jump to:	A   B   L   M   R   S   T   U

Table of Contents

1. Overview
2. Getting Started

2.1 Includes
2.2 Compiling

3. Functions

3.1 General

3.1.1 TTF_Linked_Version
3.1.2 TTF_Init
3.1.3 TTF_WasInit
3.1.4 TTF_Quit
3.1.5 TTF_SetError
3.1.6 TTF_GetError

3.2 Management

3.2.1 TTF_OpenFont
3.2.2 TTF_OpenFontRW
3.2.3 TTF_OpenFontIndex
3.2.4 TTF_OpenFontIndexRW
3.2.5 TTF_CloseFont

3.3 Attributes

3.3.1 TTF_ByteSwappedUNICODE

3.4 Render

3.4.1 TTF_RenderText_Solid

4. Types

4.1 TTF_Font

5. Defines
6. Glossary
Index

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Types
5. Defines
6. Glossary
Index

About this document

• 1. Section One
• 1.1 Subsection One-One
• ...
• 1.2 Subsection One-Two
• 1.2.1 Subsubsection One-Two-One
• 1.2.2 Subsubsection One-Two-Two
• 1.2.3 Subsubsection One-Two-Three     <== Current Position
• 1.2.4 Subsubsection One-Two-Four
• 1.3 Subsection One-Three
• ...
• 1.4 Subsection One-Four