SparrowFont is for loading truetype fonts with SDL_ttf and creating bitmap-lookup tables for them. SDL_ttf and especially blending are slow like hell. Not good for e.g. handhelds like the gp2x. So the basic idea is to render every needed sign just once in a SDL surface and then just blit it - which is pretty fast. Internal sparrowFont uses a binary tree and a cache for easy finding the right surface. Because it depends, which texts you want to draw, you have to determine first, which sign you want. Furthermore sparrowFont is able to parse button-description, which will be drawn in another way (like buttons or keys), and you can create text blocks for an easy implementation of scrolling text.
| sparrowFont | SparrowFont is for loading truetype fonts with SDL_ttf and creating bitmap-lookup tables for them. |
| Macros | |
| Defines for the look of the buttons and keys | |
| Default ranges for spFontAdd | |
| SP_FONT_DEFAULT_CACHE | Per default 16384 signs (needs 64 kilobytes) are cached. |
| SP_FONT_EXTRASPACE | Defines some extra space for the border ;-) |
| SP_FONT_NO_BORDER | Use this in spFontSetShadeColor, if you don’t want / need aliasing |
| Types | |
| spLetter | a letter in a binary tree of a font |
| spFontCache | the font cache |
| spFont | Root of a binary tree of all letters in this font |
| spTextLine | A line of a spTextBlock struct. |
| spTextBlock | A text block is used to store a block of text with a maximum width and a resultung count of lines. |
| Enumerations | |
| spTextBlockAlignment | Defines the orientation of a text block, when drawn. |
| Functions | |
| spFontLoad | Loads a ttf font |
| spFontLoad | Deletes a spFont and loads a new font in the same struct. |
| spFontAdd | Adds characters to the font. |
| spFontAddRange | Adds a range of utf8 characters to the font defined by a start and end character |
| spFontGetUnicodeFromUTF8 | Converts a utf8 sign to unicode |
| spFontGetUTF8FromUnicode | Converts a unicode character to utf8 |
| spFontAddButton | Adds a button the the font. |
| spFontAddArrowButton | Adds an arrow button the the font. |
| spFontSetButtonBoderSigns | Sets the starting and end sign for buttons, the defaults are ‘[‘ and ‘]’, which means, that “[A]” will be drawn as a button with the caption A, if you called spFontAddButton(font,’A’,”A”,fg,bg) before. |
| spFontSetSemanticButtonBoderSigns | Sets the starting and end sign for semantic buttons from sparrowMapping, the defaults are ‘{‘ and ‘}’, which means, that “{fire}” will be drawn as the button mapping to “fire”. |
| spFontSetButtonStrategy | Sets the strategy used to determine, whether buttons are round (like normal buttons on handhelds) or quadric (like keyboard buttons). |
| spFontAddBorder | For better viewing on different backgrounds, most of the time it is useful to have a border around the letters. |
| spFontReplaceColor | If you want to change the color of every letter in the font, use this function. |
| spFontMulWidth | This function changes the width, which is similar to the distance of the letters, of the whole font. |
| spFontChangeLetter | Once I had a bug in sparrowFont. |
| spFontChangeButton | Same like spFontChangeLetter, but for the Buttons. |
| spFontChangeArrowButton | Same like spFontChangeLetter, but for the arrow buttons. |
| spFontGetLetter | Returns the letter struct of a letter |
| spFontGetButton | Works like spFontGetLetter but for buttons. |
| spFontDraw | Draws a left aligned text to the render target |
| spFontDrawRight | Draws a right aligned text to the render target |
| spFontDrawMiddle | Draws a center aligned text to the render target |
| spFontWidth | Width of a text |
| spFontDelete | Deletes a font |
| spFontChangeCacheSize | Changes to size of the cache. |
| spFontChangeCacheSize | Changes to start of the cache. |
| spFontGetCacheStart | Returns the start of the cache. |
| spFontSetShadeColor | Sets the “background” color, if you want to shade smoothly. |
| spFontShadeButtons | Desides, whether the button font should be shaded or not. |
| spFontAddEveryLetterOfTextBundle | Adds every letter used in the given sparrowText Bundle of Translations. |
| spCreateTextBlock | Creates an spTextBlock out of an text. |
| spDeleteTextBlock | Deletes a text block created by spCreateTextBlock. |
| spFontDrawTextBlock | Draws a previously created text block with a maximum height. |
| spFontGetLetterString | Generates a string to use maybe for another call of spFontAdd. |
Per default 16384 signs (needs 64 kilobytes) are cached. Thats enough most of the time. In fact - because SDL_ttf is just able to use plane 0 (the first 65536 letters) of unicode, nearly everything you will need is cached, and the tree is useles... But it was fun to implement it!
a letter in a binary tree of a font
| character (Uint32) | unicode character |
| surface (SDL_Surface*) | the character’s surface |
| width (Sint32) | the character’s width in pixels |
| height (Sint32) | the character’s height in pixels |
| binary_height (Sint32) | internal value for the binary tree. Not the height in pixels |
| color (Uint16) | 16 Bit color of the character |
| left (spLetter*) | internal pointer for the tree |
| right (spLetter*) | internal pointer for the tree |
the font cache
| size (Uint32) | size of the cache |
| cache (spLetter*) | an array of pointers of spLetter |
Root of a binary tree of all letters in this font
| font (TTF_Font*) | the SDL_ttf font struct |
| maxheight (Sint32) | the height of the heighest letter in the tree |
| root (spLetter*) | the root of the binary letter tree |
| cacheOffset (Uint32) | the offset of the cache, where it “starts” |
| cache (spFontCache) | the cache |
| size (Uint32) | the size of the font |
| buttonRoot (spLetter*) | the root of the buttons of the binary letter tree |
A line of a spTextBlock struct.
| count (int) | the number of letters in this line |
| width (int) | the width in pixel of this line |
| text (char*) | the content of the line |
| font (spFontPointer> | the used font |
A text block is used to store a block of text with a maximum width and a resultung count of lines. Made to use for scrollable text.
| line_count (int) | the total number of lines in this text block |
| max_width (int) | the maximum width of the text block |
| line (spTextLine*) | array of the lines in the block. See spTextLine |
Defines the orientation of a text block, when drawn. Used by spFontDrawTextBlock.
| left | left orientation |
| middle | centered orientation |
| right | right orientation |
PREFIX void spFontAdd( spFontPointer font, char * characters, Uint16 color )
Adds characters to the font. You need to call this once after spFontLoad and before drawing, with every character you eventually want to draw
| font | the font pointer, which shall be filled with new stuff |
| characters | characters, that shall be added. It adds every utf8 character passed in this char* string. Some defines (SP_FONT_GROUP_ASCII, SP_FONT_GROUP_GERMAN, etc. ) are provided for ease of use. However: If a letter already is in the range, the later mentions will be ignored |
| color | color of the added letters |
PREFIX void spFontAddRange( spFontPointer font, char * from, char * to, Uint16 color )
Adds a range of utf8 characters to the font defined by a start and end character
| font | the font pointer, which shall be filled with new stuff |
| from | start character |
| to | end character. All characters between from and to will be added, e.g. usw from = 0 and to = 9 to add all numbers. See ASCII/utf8 tables for more usefull ranges. If to smaller than from, the values are switched |
| color | color of the added characters |
PREFIX char* spFontGetUTF8FromUnicode( Uint32 sign, char * buffer, int len )
Converts a unicode character to utf8
| sign | unicode sign |
| buffer | buffer for the resulting utf8 character, you have to alloc it! However, 5 bytes are always enough |
| len | maximal length of the buffer |
| char* | the same pointer as buffer points, too. Just for better usement. |
PREFIX void spFontAddButton( spFontPointer font, Uint32 character, char * caption, Uint16 fgColor, Uint16 bgColor )
Adds a button the the font.
| font | the font pointer, which shall be filled with new stuff |
| character | this unicode character will identify the button, e.g. ‘A’ for the Button A or ‘S’ for Select. Use whatever you want. |
| caption | the name of the button. If you use the button design, use only names of one letter, with the key design more letters are fine. |
| fgColor | a 16 bit color value identifying the foreground color of the button, that means the color of the caption and the border |
| bgColor | a 16 bit color value identifying the background color of the button |
PREFIX void spFontAddArrowButton( spFontPointer font, Uint32 character, int direction, Uint16 fgColor, Uint16 bgColor )
Adds an arrow button the the font.
| font | the font pointer, which shall be filled with new stuff |
| character | this unicode character will identify the arrow button, e.g. ‘<’ for the left arrow or ‘v’ for down. Use whatever you want. |
| direction | Possible values are 1 (left), 2 (up), 3 (right) and 4 (down), also called SP_BUTTON_ARROW_LEFT, SP_BUTTON_ARROW_UP, SP_BUTTON_ARROW_RIGHT and SP_BUTTON_ARROW_DOWN |
| fgColor | a 16 bit color value identifying the foreground color of the button, that means the color of the caption and the border |
| bgColor | a 16 bit color value identifying the background color of the button |
Sets the starting and end sign for semantic buttons from sparrowMapping, the defaults are ‘{‘ and ‘}’, which means, that “{fire}” will be drawn as the button mapping to “fire”.
| left | the start of a semantic button |
| right | the end of a semantic button |
PREFIX void spFontSetButtonStrategy( int strategy )
Sets the strategy used to determine, whether buttons are round (like normal buttons on handhelds) or quadric (like keyboard buttons).
| strategy | SP_FONT_INTELLIGENT uses rounds buttons for normal button, but quadric buttons for Start or Select and always quadric buttons for keyboard keys. With SP_FONT_BUTTON or SP_FONT_KEY you can force another design. |
PREFIX void spFontAddBorder( spFontPointer font, Uint16 bordercolor )
For better viewing on different backgrounds, most of the time it is useful to have a border around the letters. With this function you can do this. It adds a border to every currently loaded letter. (Every letter loaded afterwards will have no border by default ) Note: Works on a pixel level, therefore needs a non-transparent font to work.
| font | the font, that shall get a border |
| bordercolor | the 16 bit color of the border |
PREFIX void spFontReplaceColor( spFontPointer font, Uint16 oldcolor, Uint16 newcolor )
If you want to change the color of every letter in the font, use this function. It might be useful to draw just the border and no letter inside: First draw the letter in a color of your choice (e.g. black), than add a border (e.g. white) and than call spFontReplaceColor and replace the black with SP_ALPHA_COLOR (pink)
| font | the font, which color shall be changed |
| oldcolor | 16 Bit color to be changed |
| newcolor | 16 Bit color to be set |
PREFIX void spFontMulWidth( spFontPointer font, Sint32 factor )
This function changes the width, which is similar to the distance of the letters, of the whole font.
| font | the font, which width will be changed |
| factor | fixed point factor for the width of the output. factor = SP_ONE does nothing, greater does increase the distance and smaller ones will decrease the distance. |
PREFIX void spFontChangeLetter( spFontPointer font, spLetterPointer letter, Uint32 character, Uint16 color )
Once I had a bug in sparrowFont. The “0” just looked ugly and wrong and it seemed to be the failure of SDL_ttf. So I wrote this function to replace the surface, but not the NAME of a letter. I called spFontChangeLetter(font,spFontGetLetter(font,’0’),’O’,color); and my 0 was O. Looked a bit funny, but worked.
| font | the font to be changed |
| letter | the letter in the font to be changed, use spFontGetLetter |
| character | the character to be replaced. The character value of the letter will not be changed, this is only for the redrawing of the surface |
| color | color of the letter |
PREFIX void spFontChangeButton( spFontPointer font, spLetterPointer letter, Uint32 character, char * caption, Uint16 fgColor, Uint16 bgColor )
Same like spFontChangeLetter, but for the Buttons.
PREFIX void spFontChangeArrowButton( spFontPointer font, spLetterPointer letter, Uint32 character, int direction, Uint16 fgColor, Uint16 bgColor )
Same like spFontChangeLetter, but for the arrow buttons.
PREFIX spLetterPointer spFontGetButton( spFontPointer font, Uint32 character )
Works like spFontGetLetter but for buttons. ;-)
PREFIX int spFontDraw( Sint32 x, Sint32 y, Sint32 z, const unsigned char * text, spFontPointer font )
Draws a left aligned text to the render target
| x,y | position on the render target |
| z | z value for z-test, z-set, etc. |
| text | text to be drawn |
| font | font, that shall be used for drawing the text |
| int | the printed width in pixels |
PREFIX int spFontDrawRight( Sint32 x, Sint32 y, Sint32 z, const unsigned char * text, spFontPointer font )
Draws a right aligned text to the render target
| x,y | position on the render target |
| z | z value for z-test, z-set, etc. |
| text | text to be drawn |
| font | font, that shall be used for drawing the text |
| int | the printed width in pixels |
PREFIX int spFontDrawMiddle( Sint32 x, Sint32 y, Sint32 z, const unsigned char * text, spFontPointer font )
Draws a center aligned text to the render target
| x,y | position on the render target |
| z | z value for z-test, z-set, etc. |
| text | text to be drawn |
| font | font, that shall be used for drawing the text |
| int | the printed width in pixels |
PREFIX void spFontSetShadeColor( int value )
Sets the “background” color, if you want to shade smoothly. It is still no alpha blending, but the blended font will be look better. However the font might look ugly at least with a shitty background color. So the default is SP_FONT_NO_BORDER, which means, that no shading is done and the font looks normal pixelized.
| value | the 16 bit alpha color to which it shall be shaded |
PREFIX void spFontShadeButtons( int value )
Desides, whether the button font should be shaded or not. For compatibility (especially with transparent background color of the buttons) the default is false (0). But in most cases true (1) should look much better. :)
| value | 1 enabled, 0 disabled |
PREFIX void spFontAddEveryLetterOfTextBundle( spFontPointer font, spBundlePointer bundle, Uint16 color )
Adds every letter used in the given sparrowText Bundle of Translations. See sparrowText for more.
| font | the font to be changed |
| bundle | the bundle, to be scaned for every used character |
| color | the color of the added characters |
PREFIX spTextBlockPointer spCreateTextBlock( const unsigned char * text, int max_width, spFontPointer font )
Creates an spTextBlock out of an text. Use it in spFontDrawTextBlock to draw scrollable text.
| text | the text to convert to a text block |
| max_width | the maximal width one line should have at all. If a line consists |
| of one word, which is longer than max_width the word is splitted and | is added. Otherwise a line break always happens between words |
| font | the font (pointer to spFont) to use to determine the width of the rendered text lines |
| spTextBlockPointer | pointer to the created spTextBlock struct. |
PREFIX void spDeleteTextBlock( spTextBlockPointer block )
Deletes a text block created by spCreateTextBlock.
| block | pointer to spTextBlock to free |
PREFIX int spFontDrawTextBlock( spTextBlockAlignment alignment, Sint32 x, Sint32 y, Sint32 z, spTextBlockPointer block, Sint32 height, Sint32 position, spFontPointer font )
Draws a previously created text block with a maximum height. Also supports scrolling.
| aligment | determines, whether the text should be aligned left, centered or right. Possible values (spTextBlockAlignment) are left, middle and right |
| x,y | possion of the text on the screen |
| z | z value to set and test (if enabled) while drawing |
| block | the text block created by spCreateTextBlock to draw |
| height | the maximum height of the text to be drawn. |
| position | fixed point value between 0 and SP_ONE, which determines which part of the block shall be drawn. Use it for scrolling. If the whole block fits in the block->max_width X height block, of course this parameters doesn’t make any sense and is ignored |
| font | the font to draw the text. Should be the same as used in spCreateTextBlock or NULL, but however don’t have to. If NULL the font of spCreateTextBlock is used. |
| int | the number of lines drawn |
PREFIX char* spFontGetLetterString( spFontPointer font, unsigned char * buffer, int length )
Generates a string to use maybe for another call of spFontAdd.
| font | spFontPointer to use |
| buffer | char* buffer to fill |
| length | size of the buffer |
| char* | the pointer to buffer |
Loads a ttf font
PREFIX spFontPointer spFontLoad( const char * fontname, Uint32 size )
Adds characters to the font.
PREFIX void spFontAdd( spFontPointer font, char * characters, Uint16 color )
Adds a range of utf8 characters to the font defined by a start and end character
PREFIX void spFontAddRange( spFontPointer font, char * from, char * to, Uint16 color )
Converts a utf8 sign to unicode
PREFIX Uint32 spFontGetUnicodeFromUTF8( const char * sign )
Converts a unicode character to utf8
PREFIX char* spFontGetUTF8FromUnicode( Uint32 sign, char * buffer, int len )
Adds a button the the font.
PREFIX void spFontAddButton( spFontPointer font, Uint32 character, char * caption, Uint16 fgColor, Uint16 bgColor )
Adds an arrow button the the font.
PREFIX void spFontAddArrowButton( spFontPointer font, Uint32 character, int direction, Uint16 fgColor, Uint16 bgColor )
Sets the strategy used to determine, whether buttons are round (like normal buttons on handhelds) or quadric (like keyboard buttons).
PREFIX void spFontSetButtonStrategy( int strategy )
For better viewing on different backgrounds, most of the time it is useful to have a border around the letters.
PREFIX void spFontAddBorder( spFontPointer font, Uint16 bordercolor )
If you want to change the color of every letter in the font, use this function.
PREFIX void spFontReplaceColor( spFontPointer font, Uint16 oldcolor, Uint16 newcolor )
This function changes the width, which is similar to the distance of the letters, of the whole font.
PREFIX void spFontMulWidth( spFontPointer font, Sint32 factor )
Once I had a bug in sparrowFont.
PREFIX void spFontChangeLetter( spFontPointer font, spLetterPointer letter, Uint32 character, Uint16 color )
Same like spFontChangeLetter, but for the Buttons.
PREFIX void spFontChangeButton( spFontPointer font, spLetterPointer letter, Uint32 character, char * caption, Uint16 fgColor, Uint16 bgColor )
Same like spFontChangeLetter, but for the arrow buttons.
PREFIX void spFontChangeArrowButton( spFontPointer font, spLetterPointer letter, Uint32 character, int direction, Uint16 fgColor, Uint16 bgColor )
Returns the letter struct of a letter
PREFIX spLetterPointer spFontGetLetter( spFontPointer font, Uint32 character )
Works like spFontGetLetter but for buttons.
PREFIX spLetterPointer spFontGetButton( spFontPointer font, Uint32 character )
Draws a left aligned text to the render target
PREFIX int spFontDraw( Sint32 x, Sint32 y, Sint32 z, const unsigned char * text, spFontPointer font )
Draws a right aligned text to the render target
PREFIX int spFontDrawRight( Sint32 x, Sint32 y, Sint32 z, const unsigned char * text, spFontPointer font )
Draws a center aligned text to the render target
PREFIX int spFontDrawMiddle( Sint32 x, Sint32 y, Sint32 z, const unsigned char * text, spFontPointer font )
Width of a text
PREFIX int spFontWidth( const unsigned char * text, spFontPointer font )
Deletes a font
PREFIX void spFontDelete( spFontPointer font )
Changes to size of the cache.
PREFIX void spFontChangeCacheSize( spFontPointer font, Sint32 size )
Returns the start of the cache.
PREFIX Sint32 spFontGetCacheStart( spFontPointer font )
Sets the “background” color, if you want to shade smoothly.
PREFIX void spFontSetShadeColor( int value )
Desides, whether the button font should be shaded or not.
PREFIX void spFontShadeButtons( int value )
Adds every letter used in the given sparrowText Bundle of Translations.
PREFIX void spFontAddEveryLetterOfTextBundle( spFontPointer font, spBundlePointer bundle, Uint16 color )
Creates an spTextBlock out of an text.
PREFIX spTextBlockPointer spCreateTextBlock( const unsigned char * text, int max_width, spFontPointer font )
Deletes a text block created by spCreateTextBlock.
PREFIX void spDeleteTextBlock( spTextBlockPointer block )
Draws a previously created text block with a maximum height.
PREFIX int spFontDrawTextBlock( spTextBlockAlignment alignment, Sint32 x, Sint32 y, Sint32 z, spTextBlockPointer block, Sint32 height, Sint32 position, spFontPointer font )
Generates a string to use maybe for another call of spFontAdd.
PREFIX char* spFontGetLetterString( spFontPointer font, unsigned char * buffer, int length )