Tux4Kids-Common
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
t4k_common.h File Reference
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <dirent.h>
#include <wchar.h>
#include "SDL.h"
#include "SDL_image.h"
#include "SDL_mixer.h"

Go to the source code of this file.

Data Structures

struct  sprite
 

Macros

#define DEBUGVAR(mask, Expr)
 DEBUGVAR prints out the name and value of a string variable. More...
 
#define DEBUGVARX(mask, Expr)
 DEBUGVARX prints out the name and hex value of an integral variable. More...
 
#define DEBUGVARF(mask, Expr)
 DEBUGVARF prints out the name and decimal value of a floating point variable. More...
 
#define DEBUGCODE(mask)   if((mask) & debug_status)
 DEBUGCODE is a conditional and should be followed by a code block. More...
 
#define DEBUGMSG(mask,...)
 DEBUGMSG prints out a specific message, which can be formatted like printf. More...
 
#define rmask   0xff000000
 SDL red mask. More...
 
#define gmask   0x00ff0000
 SDL green mask. More...
 
#define bmask   0x0000ff00
 SDL blue mask. More...
 
#define amask   0x000000ff
 SDL alpha mask. More...
 
#define DEBUGCODE(mask)   if((mask) & debug_status)
 DEBUGCODE is a conditional and should be followed by a code block. More...
 
#define DEBUGMSG(mask,...)
 DEBUGMSG prints out a specific message, which can be formatted like printf. More...
 
#define START_CUSTOM_DEBUG   4
 
#define MAX_SPRITE_FRAMES   15
 
#define IMG_REGULAR   0x01
 
#define IMG_COLORKEY   0x02
 
#define IMG_ALPHA   0x04
 
#define IMG_MODES   0x07
 
#define IMG_NOT_REQUIRED   0x10
 
#define IMG_NO_PNG_FALLBACK   0x20
 
#define MAX_LINES   128
 Maximum lines to wrap. More...
 
#define MAX_LINEWIDTH   256
 Maximum characters of each line. More...
 

Typedefs

typedef void(* ResSwitchCallback )(int resx, int resy)
 

Enumerations

enum  bool { false, true }
 
enum  WipeStyle {
  WIPE_BLINDS_VERT, WIPE_BLINDS_HORIZ, WIPE_BLINDS_BOX, RANDOM_WIPE,
  NUM_WIPES
}
 
enum  { RUN_MAIN_MENU = -3, QUIT = -2, STOP = -1 }
 
enum  MFStrategy { MF_UNIFORM, MF_BESTFIT, MF_EXACTLY }
 

Functions

void InitT4KCommon (int debug_flags)
 Initialize Tux4Kids-Common. More...
 
int T4K_HandleStdEvents (const SDL_Event *event)
 Handle events that should have consistent effects everywhere in the program. More...
 
void T4K_SetActivitiesList (int num, char **acts)
 Specify the set of activities the menu system should handle. More...
 
void T4K_SetMenuSounds (char *mus_path, Mix_Chunk *click, Mix_Chunk *hover)
 Set optional sound effects and music for menus. More...
 
void T4K_SetMenuSpritePrefix (char *pref)
 Set the prefix that is used whe loading menu sprites. More...
 
void T4K_SetMenuFontSize (MFStrategy strategy, int size)
 Set the font size for managed menus. More...
 
void T4K_CreateOneLevelMenu (int index, int items, char **item_names, char **sprite_names, char *title, char *trailer)
 Dynamically create a simple menu. All given strings are copied. More...
 
int T4K_RunMenu (int index, bool return_choice, void(*draw_background)(), int(*handle_event)(SDL_Event *), void(*handle_animations)(), int(*handle_activity)(int, int))
 RunMenu - main function to display the menu and run the event loop this function is a modified copy of choose_menu_item() More...
 
void T4K_PrerenderMenu (int index)
 Prerender a single menu based on the screen resolution. More...
 
void T4K_PrerenderAll (void)
 Prerender all menus, arrows and stop button. This function should be invoked after every resolution change. More...
 
void T4K_LoadMenu (int index, const char *file_name)
 Load menu from given XML file and store its tree under given index in "menus" array. More...
 
void T4K_UnloadMenus (void)
 free all loaded menu trees More...
 
SDL_Surface * T4K_GetScreen (void)
 Return a pointer to the screen we're using, as an alternative to making screen a global variable. More...
 
int T4K_GetResolutions (int *win_x, int *win_y, int *full_x, int *full_y)
 Provide current values of x and y resolutions for windowed and fullscreen modes. More...
 
void T4K_DrawButton (SDL_Rect *target_rect, int radius, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
 Creates a translucent button with rounded ends and draws it on the screen. All colors and alpha values are supported. This is equivalent to T4K_DrawButtonOn(T4K_GetScreen()); More...
 
void T4K_DrawButtonOn (SDL_Surface *target, SDL_Rect *target_rect, int radius, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
 Creates a translucent button with rounded ends and draws it on the given surface. All colors and alpha values are supported. More...
 
SDL_Surface * T4K_CreateButton (int w, int h, int radius, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
 Creates a translucent button with rounded ends All colors and alpha values are supported. More...
 
void T4K_RoundCorners (SDL_Surface *s, Uint16 radius)
 Round the corners of a surface by erasing edge pixels. More...
 
SDL_Surface * T4K_Flip (SDL_Surface *in, int x, int y)
 Flip a surface vertically or horizontally. More...
 
SDL_Surface * T4K_Blend (SDL_Surface *S1, SDL_Surface *S2, float gamma)
 Blend two surfaces together. The third argument is between 0.0 and 1.0, and represents the weight assigned to the first surface. If the pointer to the second surface is NULL, this performs fading. More...
 
void T4K_FreeSurfaceArray (SDL_Surface **surfs, int length)
 Free every surface in the array together with the array itself. More...
 
int T4K_inRect (SDL_Rect r, int x, int y)
 Tells whether the point (x, y) is inside the SDL_Rect r. More...
 
void T4K_SetRect (SDL_Rect *rect, const float *pos)
 This function will write an SDL_Rect with dimensions based on screen dimensions. More...
 
void T4K_UpdateRect (SDL_Surface *surf, SDL_Rect *rect)
 Wrap a call to SDL_UpdateRect. More...
 
void T4K_DarkenScreen (Uint8 bits)
 Darkens the screen by a factor of 2^bits. More...
 
void T4K_ChangeWindowSize (int new_res_x, int new_res_y)
 This function will change window size (unstable, works only in windowed mode). More...
 
void T4K_SwitchScreenMode (void)
 Switch between fullscreen and windowed mode. Resolution switching callbacks are invoked. More...
 
void T4K_OnResolutionSwitch (ResSwitchCallback callback)
 Register a callback to reposition and redraw screen elements when the resolution is changed. More...
 
SDL_EventType T4K_WaitForEvent (SDL_EventMask events)
 Block application until SDL receives an appropriate event. Use sparingly. More...
 
SDL_Surface * T4K_zoom (SDL_Surface *src, int new_w, int new_h)
 This function will scale an existing surface. More...
 
int T4K_TransWipe (const SDL_Surface *newbkg, WipeStyle type, int segments, int duration)
 Perform a wipe from the current screen image to a new one. More...
 
void T4K_InitBlitQueue (void)
 Initialize the blit queue system. This must be called before T4K_ResetBlitQueue, T4K_AddRect, T4K_DrawSprite, T4K_DrawObject, T4K_EraseObject, T4K_EraseSprite or T4K_UpdateScreen. More...
 
void T4K_ResetBlitQueue (void)
 Just set the number of pending updates to zero. More...
 
int T4K_AddRect (SDL_Rect *src, SDL_Rect *dst)
 Don't actually blit a surface, but add a rect to be updated next update. More...
 
int T4K_DrawSprite (sprite *gfx, int x, int y)
 This function will draw the sprite in the screen. More...
 
int T4K_DrawObject (SDL_Surface *surf, int x, int y)
 Draw an object at the specified location. No respect to clipping. More...
 
void T4K_UpdateScreen (int *frame)
 Update the screen and increment the frame counter. More...
 
int T4K_EraseSprite (sprite *img, SDL_Surface *curr_bkgd, int x, int y)
 Basically puts in an order to overdraw sprite with corresponding rect of bkgd img. More...
 
int T4K_EraseObject (SDL_Surface *surf, SDL_Surface *curr_bkgd, int x, int y)
 Erase an object from the screen. More...
 
void T4K_SetFontName (const char *name)
 Set the "global" font name. More...
 
const char * T4K_AskFontName (void)
 Get the "global" font name. More...
 
int T4K_Setup_SDL_Text (void)
 Initialize the backend (Pango or TTF) used for text-drawing functions. More...
 
void T4K_Cleanup_SDL_Text (void)
 Shut down the backend used for text-drawing functions. More...
 
SDL_Surface * T4K_BlackOutline (const char *t, int size, SDL_Color *c)
 T4K_BlackOutline() creates a surface containing text of the designated foreground color, surrounded by a black shadow, on a transparent background. The appearance can be tuned by adjusting the number of background copies and the offset where the foreground text is finally written (see below). More...
 
SDL_Surface * T4K_SimpleText (const char *t, int size, SDL_Color *col)
 Returns a non-outlined surface using either SDL_Pango or SDL_ttf. More...
 
SDL_Surface * T4K_SimpleTextWithOffset (const char *t, int size, SDL_Color *col, int *glyph_offset)
 Same as T4K_SimpleText, but the text offset is also stored. More...
 
int T4K_CharsForWidth (int fontsize, int pixel_width)
 Calculate how long a string for a given fontsize will fit within a given pixel width. The estimate is based on strings of 'x'. More...
 
void T4K_AddDataPrefix (const char *path)
 Add a directory that should be searched when loading assets. More...
 
int T4K_CheckFile (const char *file)
 Check whether a file exists. More...
 
char * T4K_RemoveSlash (char *path)
 Remove a trailing slash from a file path. More...
 
SDL_Surface * T4K_LoadImage (const char *file_name, int mode)
 Load an image without resizing it. More...
 
SDL_Surface * T4K_LoadScaledImage (const char *file_name, int mode, int width, int height)
 Load an image and resize it to given dimensions. If width or height is negative no resizing is applied. More...
 
SDL_Surface * T4K_LoadImageOfBoundingBox (const char *file_name, int mode, int max_width, int max_height)
 Same as LoadScaledImage but preserve image proportions and fit it into max_width x max_height rectangle. More...
 
SDL_Surface * T4K_LoadBkgd (const char *file_name, int width, int height)
 A wrapper for LoadImage() that optimizes the format of background image. More...
 
int T4K_LoadBothBkgds (const char *file_name, SDL_Surface **fs_bkgd, SDL_Surface **win_bkgd)
 Load backgrounds for both fullscreen and windowed resolution. More...
 
spriteT4K_LoadSprite (const char *name, int mode)
 Load a multiple-frame sprite from disk. This function loads an SVG sprite or multiple PNGs as needed. More...
 
spriteT4K_LoadScaledSprite (const char *name, int mode, int width, int height)
 Load a multiple-frame sprite from disk and scale it to the given dimensions. This function loads an SVG sprite or multiple PNGs as needed. More...
 
spriteT4K_LoadSpriteOfBoundingBox (const char *name, int mode, int max_width, int max_height)
 Same as LoadScaledSprite but preserve image proportions and fit it into max_width x max_height rectangle. NOTE: Returned surface is not necessarily max_width x max_height ! More...
 
spriteT4K_FlipSprite (sprite *in, int X, int Y)
 Flip (reflect) a sprite over one or both axes. More...
 
void T4K_FreeSprite (sprite *gfx)
 Free memory allocated for a loaded sprite. More...
 
void T4K_NextFrame (sprite *s)
 Advance a sprite's frame. More...
 
Mix_Chunk * T4K_LoadSound (char *datafile)
 Load a sound/music patch from a file. More...
 
Mix_Music * T4K_LoadMusic (char *datafile)
 Load music from a datafile. More...
 
void T4K_PlaySound (Mix_Chunk *sound)
 Play sound once and then exit. More...
 
void T4K_PlaySoundLoop (Mix_Chunk *sound, int loops)
 Play sound "loops" times, -1 for infinite. More...
 
void T4K_AudioHaltChannel (int channel)
 Will stop the channel specified in channel. If -1 is passed as the parameter to channel, all channels will be stopped. More...
 
void T4K_AudioMusicLoad (char *music_path, int loops)
 Attempts to load and play the music file. More...
 
void T4K_AudioMusicUnload (void)
 Attempts to unload any music data that was loaded using the audioMusicLoad function. More...
 
bool T4K_IsPlayingMusic (void)
 This function will check if a music is currently playing. More...
 
void T4K_AudioMusicPlay (Mix_Music *musicData, int loops)
 attempts to play the passed music data, stopping current music if necessary More...
 
void T4K_AudioEnable (bool enabled)
 Enable/disable sound. More...
 
void T4K_AudioToggle (void)
 Toggle sound enablement. More...
 
int T4K_LineWrap (const char *input, char str_list[MAX_LINES][MAX_LINEWIDTH], int width, int max_lines, int max_width)
 This function takes an input string (can be in essentially arbitrary encoding) and loads it into an array of strings, each corresponding to one line of output text. More...
 
int T4K_LineWrapInsBreaks (const char *input, char *output, int width, int max_lines, int max_width)
 This function takes an input string and inserts newline characters at places determined by the linebreak library, returning a single string. More...
 
void T4K_LineWrapList (const char input[MAX_LINES][MAX_LINEWIDTH], char str_list[MAX_LINES][MAX_LINEWIDTH], int width, int max_lines, int max_width)
 
void T4K_Throttle (int loop_msec, Uint32 *last_t)
 
int T4K_ConvertFromUTF8 (wchar_t *wide_word, const char *UTF8_word, int max_length)
 
int T4K_ConvertToUTF8 (const wchar_t *wide_word, char *UTF8_word, int max_length)
 

Variables

int debug_status
 
SDL_Surface * screen
 
SDL_Rect menu_rect
 
SDL_Rect stop_rect
 
SDL_Rect prev_rect
 
SDL_Rect next_rect
 
SDL_Surface * stop_button
 
SDL_Surface * prev_arrow
 
SDL_Surface * next_arrow
 
SDL_Surface * prev_gray
 
SDL_Surface * next_gray
 
char wrapped_lines [MAX_LINES][MAX_LINEWIDTH]
 Global buffer for wrapped lines. More...
 

Detailed Description

t4k_common.h

Macro Definition Documentation

#define amask   0x000000ff

SDL alpha mask.

#define bmask   0x0000ff00

SDL blue mask.

#define DEBUGCODE (   mask)    if((mask) & debug_status)

DEBUGCODE is a conditional and should be followed by a code block.

#define DEBUGCODE (   mask)    if((mask) & debug_status)

DEBUGCODE is a conditional and should be followed by a code block.

#define DEBUGMSG (   mask,
  ... 
)
Value:
if((mask) & debug_status) \
{ \
fprintf(stderr, __VA_ARGS__); fflush(stderr); \
}

DEBUGMSG prints out a specific message, which can be formatted like printf.

#define DEBUGMSG (   mask,
  ... 
)
Value:
if((mask) & debug_status) \
{ \
fprintf(stderr, __VA_ARGS__); fflush(stderr); \
}

DEBUGMSG prints out a specific message, which can be formatted like printf.

#define DEBUGVAR (   mask,
  Expr 
)
Value:
if((mask) & (debug_status)) \
{ \
fprintf(stderr, #Expr ": %s\n", (Expr)); fflush(stderr); \
}

DEBUGVAR prints out the name and value of a string variable.

#define DEBUGVARF (   mask,
  Expr 
)
Value:
if((mask) & (debug_status)) \
{ \
fprintf(stderr, #Expr ": %f\n", (Expr)); fflush(stderr); \
}

DEBUGVARF prints out the name and decimal value of a floating point variable.

#define DEBUGVARX (   mask,
  Expr 
)
Value:
if((mask) & (debug_status)) \
{ \
fprintf(stderr, #Expr ": %x\n", (Expr)); fflush(stderr); \
}

DEBUGVARX prints out the name and hex value of an integral variable.

#define gmask   0x00ff0000

SDL green mask.

#define IMG_ALPHA   0x04
#define IMG_COLORKEY   0x02
#define IMG_MODES   0x07
#define IMG_NO_PNG_FALLBACK   0x20
#define IMG_NOT_REQUIRED   0x10
#define IMG_REGULAR   0x01
#define MAX_LINES   128

Maximum lines to wrap.

#define MAX_LINEWIDTH   256

Maximum characters of each line.

#define MAX_SPRITE_FRAMES   15

The max number of images a single sprite can use

#define rmask   0xff000000

SDL red mask.

#define START_CUSTOM_DEBUG   4

Games defining custom debug flags should use this constant to ensure consistency with t4k_common values.

For example:

const int debug_something_of_mine = 1 << START_CUSTOM_DEBUG;
const int debug_something_else    = 2 << START_CUSTOM_DEBUG;
const int debug_some_more_stuff   = 4 << START_CUSTOM_DEBUG;

Typedef Documentation

typedef void(* ResSwitchCallback)(int resx, int resy)

A function to handle a resolution switch, which should take parameters for the new horizontal and vertical screen dimensions.

Enumeration Type Documentation

anonymous enum

Special values used by RunMenu.

Enumerator
RUN_MAIN_MENU 

can be used in .xml menu structures but should not be declared in activities' lists.

QUIT 

user decided to quit application

STOP 

user pressed the stop button

enum bool
Enumerator
false 
true 
enum MFStrategy

Strategies for determining menu font sizes.

Enumerator
MF_UNIFORM 

All menus are searched and the largest size that will fit on all menus is used.

MF_BESTFIT 

Menus are searched separately for the largest fonts they can accommodate.

MF_EXACTLY 

The font size given is used directly; text may run off the screen.

enum WipeStyle
Enumerator
WIPE_BLINDS_VERT 
WIPE_BLINDS_HORIZ 
WIPE_BLINDS_BOX 
RANDOM_WIPE 
NUM_WIPES 

Function Documentation

void InitT4KCommon ( int  debug_flags)

Initialize Tux4Kids-Common.

Parameters
debug_flags- The flags used for debugging output.

Games may define their own debug flags, but several are available by default:

  • debug_loaders
  • debug_menu
  • debug_menu_parser
  • debug_sdl
  • debug_all
Returns
None
void T4K_AddDataPrefix ( const char *  path)

Add a directory that should be searched when loading assets.

Parameters
path- Directory path to set as prefix of the data.
Returns
None
int T4K_AddRect ( SDL_Rect *  src,
SDL_Rect *  dst 
)

Don't actually blit a surface, but add a rect to be updated next update.

Parameters
src- The source dimension of the screen.
dst- The destination dimension of the screen.
Returns
1 - Add SDL_Rect successful.
0 - If invalid parameter and add SDL_Rect failed.
const char* T4K_AskFontName ( void  )

Get the "global" font name.

Parameters
None
Returns
Returns the "global" font name.
void T4K_AudioEnable ( bool  enabled)

Enable/disable sound.

Parameters
enabled- Set true if Audio is enabled or false to disable the audition.
Returns
None
void T4K_AudioHaltChannel ( int  channel)

Will stop the channel specified in channel. If -1 is passed as the parameter to channel, all channels will be stopped.

Parameters
channel- Parameter to stop.
Returns
None
void T4K_AudioMusicLoad ( char *  music_path,
int  loops 
)

Attempts to load and play the music file.

Parameters
music_path- Path of the music file.
loops- Number of loops.
Returns
None
void T4K_AudioMusicPlay ( Mix_Music *  musicData,
int  loops 
)

attempts to play the passed music data, stopping current music if necessary

Parameters
musicData- Data of music.
loops- The number of times to loop, or -1 forever
Returns
None
void T4K_AudioMusicUnload ( void  )

Attempts to unload any music data that was loaded using the audioMusicLoad function.

Parameters
None
Returns
None
void T4K_AudioToggle ( void  )

Toggle sound enablement.

Parameters
None
Returns
None
SDL_Surface* T4K_BlackOutline ( const char *  t,
int  size,
SDL_Color *  c 
)

T4K_BlackOutline() creates a surface containing text of the designated foreground color, surrounded by a black shadow, on a transparent background. The appearance can be tuned by adjusting the number of background copies and the offset where the foreground text is finally written (see below).

Parameters
t- The text to draw
size- the font size to use
c- the fill color to use
Returns
Returns newly created surface.
SDL_Surface* T4K_Blend ( SDL_Surface *  S1,
SDL_Surface *  S2,
float  gamma 
)

Blend two surfaces together. The third argument is between 0.0 and 1.0, and represents the weight assigned to the first surface. If the pointer to the second surface is NULL, this performs fading.

Currently this works only with RGBA images, but this is largely to
make the (fast) pointer arithmetic work out; it could be easily
generalized to other image types.
Parameters
S1- The first surface
S2- The second surface
gamma- A value between 0.0 and 1.0, representing the weight assigned to the first surface.
Returns
If successfull, it will returns the new blended surface otherwise it will return a NULL value.
void T4K_ChangeWindowSize ( int  new_res_x,
int  new_res_y 
)

This function will change window size (unstable, works only in windowed mode).

Parameters
new_res_x- The new width of the window.
new_res_y- The new height of the window.
Returns
None
int T4K_CharsForWidth ( int  fontsize,
int  pixel_width 
)

Calculate how long a string for a given fontsize will fit within a given pixel width. The estimate is based on strings of 'x'.

Parameters
fontsize- Font size
pixel_width- Width in pixels of the desired text box
Returns
strlen() of the longest string of 'x' that fits
int T4K_CheckFile ( const char *  file)

Check whether a file exists.

Parameters
file- File to check.
Returns
1 - The file is valid.
0 - The file is not valid.
void T4K_Cleanup_SDL_Text ( void  )

Shut down the backend used for text-drawing functions.

Parameters
None
Returns
None
int T4K_ConvertFromUTF8 ( wchar_t *  wide_word,
const char *  UTF8_word,
int  max_length 
)

/brief A simple wrapper for using GNU iconv() to convert UTF-8 text to wchar_t ("Unicode") text. /param wide_word - ptr to wchar_t buffer to contain converted text. /param UTF8_word - ptr to UTF-8 string to be converted. /param max_length - generally the length of the output buffer to avoid overflow. It also must be no greater than the buffer length used internally in this function (i.e. UTF_BUF_LENGTH, currently 1024).

/return Returns the length of the wchar_t string generated, 0 on errors.

int T4K_ConvertToUTF8 ( const wchar_t *  wide_word,
char *  UTF8_word,
int  max_length 
)

/brief A simple wrapper for using GNU iconv() to convert wchar_t ("Unicode") text to UTF-8 text. /param wide_word - ptr to wchar_t string to be converted. /param UTF8_word - ptr to buffer to hold UTF-8 string after conversion. /param max_length - generally the length of the output buffer to avoid overflow. It also must be no greater than the buffer length used internally in this function (i.e. UTF_BUF_LENGTH, currently 1024).

/return Returns the length of the UTF-8 string generated, 0 on errors.

SDL_Surface* T4K_CreateButton ( int  w,
int  h,
int  radius,
Uint8  r,
Uint8  g,
Uint8  b,
Uint8  a 
)

Creates a translucent button with rounded ends All colors and alpha values are supported.

Parameters
w- The width of the button
h- The height of the button
radius- The radius of the arcs on each corner. A smaller radius results in sharper edges.
r- R component of the button's color
g- G component of the button's color
b- B component of the button's color
a- The opacity of the button
Returns
Surface of the translucent button with no text
void T4K_CreateOneLevelMenu ( int  index,
int  items,
char **  item_names,
char **  sprite_names,
char *  title,
char *  trailer 
)

Dynamically create a simple menu. All given strings are copied.

Parameters
index- The unique index of the menu.
items- The number of items in the menu.
item_names- The name of the items
sprite_names- The name of sprite or icon.
title- The title of the menu.
trailer- An optional item appended to the end of item_names.
Returns
None
void T4K_DarkenScreen ( Uint8  bits)

Darkens the screen by a factor of 2^bits.

Parameters
bits- An exponent between 1 and 8. Realistically, 1 and 2 are the only useful values.
Returns
None
void T4K_DrawButton ( SDL_Rect *  target_rect,
int  radius,
Uint8  r,
Uint8  g,
Uint8  b,
Uint8  a 
)

Creates a translucent button with rounded ends and draws it on the screen. All colors and alpha values are supported. This is equivalent to T4K_DrawButtonOn(T4K_GetScreen());

Parameters
target_rect- The bounding rectangle for the button.
radius- The radius of the arcs on each corner. A smaller radius results in sharper edges.
r- R component of the button's color.
g- G component of the button's color.
b- B component of the button's color.
a- The opacity of the button.
Returns
None
void T4K_DrawButtonOn ( SDL_Surface *  target,
SDL_Rect *  target_rect,
int  radius,
Uint8  r,
Uint8  g,
Uint8  b,
Uint8  a 
)

Creates a translucent button with rounded ends and draws it on the given surface. All colors and alpha values are supported.

This function creates a temporary surface to blit onto target.
If performance is an issue, consider using T4K_CreateButton 
to save the surface.
Parameters
target- The SDL_Surface to draw on
target_rect- the bounding rectangle for the button
radius- The radius of the arcs on each corner. A smaller radius results in sharper edges.
r- R component of the button's color
g- G component of the button's color
b- B component of the button's color
a- The opacity of the button
Returns
None
int T4K_DrawObject ( SDL_Surface *  surf,
int  x,
int  y 
)

Draw an object at the specified location. No respect to clipping.

Parameters
surf- Holds the surface to draw.
x- The x position to draw the object.
y- The y position to draw the object.
Returns
1 - Successful draw of the object.
0 - Failed to draw the object.
int T4K_DrawSprite ( sprite gfx,
int  x,
int  y 
)

This function will draw the sprite in the screen.

Parameters
gfx- Holds the sprite object.
x- The x position to draw the sprite.
y- The y position to draw the sprite.
Returns
1 - Successful draw of the sprite.
0 - Failed to draw the sprite.
int T4K_EraseObject ( SDL_Surface *  surf,
SDL_Surface *  curr_bkgd,
int  x,
int  y 
)

Erase an object from the screen.

Parameters
surf- Surface to delete
curr_bkgd- Current background
x- x coordinate
y- y coordinate
Returns
1 - Successful operation
0 - Failed operation
int T4K_EraseSprite ( sprite img,
SDL_Surface *  curr_bkgd,
int  x,
int  y 
)

Basically puts in an order to overdraw sprite with corresponding rect of bkgd img.

Parameters
img- Sprite to delete.
curr_bkgd- Surface of the background.
x- x coordinate
y- y coordinate
Returns
1 - Successful erase of the spriate.
0 - Failed to erase the sprite.
SDL_Surface* T4K_Flip ( SDL_Surface *  in,
int  x,
int  y 
)

Flip a surface vertically or horizontally.

Parameters
in- The source surface
x- if nonzero, the image will be flipped horizontally
y- if nonzero, the image will be flipped vertically
Returns
Returns flipped surface.
sprite* T4K_FlipSprite ( sprite in,
int  X,
int  Y 
)

Flip (reflect) a sprite over one or both axes.

Parameters
in- The original image
X- If nonzero, the image is flipped horizontally.
Y- If nonzero, the image is flipped vertically.
Returns
A newly allocated transformed sprite.
See Also
T4K_Flip
void T4K_FreeSprite ( sprite gfx)

Free memory allocated for a loaded sprite.

Parameters
gfx- The sprite to free.
Returns
None
void T4K_FreeSurfaceArray ( SDL_Surface **  surfs,
int  length 
)

Free every surface in the array together with the array itself.

Parameters
surfs- An array of SDL_Surface pointers to free.
length- The size of the array.
Returns
None
int T4K_GetResolutions ( int *  win_x,
int *  win_y,
int *  full_x,
int *  full_y 
)

Provide current values of x and y resolutions for windowed and fullscreen modes.

Parameters
win_x- Will hold the width of windowed resolution.
win_y- Will hold the height of windowed resolution.
full_x- Will hold the width of fullscreen resolution.
full_y- Will hold the height of fullscreen resolution.
Returns
1 - Successfull call of the function.
0 - Failed operation.
SDL_Surface* T4K_GetScreen ( void  )

Return a pointer to the screen we're using, as an alternative to making screen a global variable.

Parameters
None
Returns
The surface of the screen.
int T4K_HandleStdEvents ( const SDL_Event *  event)

Handle events that should have consistent effects everywhere in the program.

Parameters
event- the event to check
Returns
0 - if no action is necessary
1 - if the screen should be redrawn
void T4K_InitBlitQueue ( void  )

Initialize the blit queue system. This must be called before T4K_ResetBlitQueue, T4K_AddRect, T4K_DrawSprite, T4K_DrawObject, T4K_EraseObject, T4K_EraseSprite or T4K_UpdateScreen.

Parameters
None
Returns
None
int T4K_inRect ( SDL_Rect  r,
int  x,
int  y 
)

Tells whether the point (x, y) is inside the SDL_Rect r.

Parameters
r- The bounding rect.
x- The x coordinate to test.
y- The y coordinate to test.
Returns
1 - The x and y are inside of the SDL_Rect r.
0 - The x and y are outside of the SDL_Rect r.
bool T4K_IsPlayingMusic ( void  )

This function will check if a music is currently playing.

Parameters
None
Returns
true - If a music is currently playing.
false - If a music is not playing.
int T4K_LineWrap ( const char *  input,
char  str_list[MAX_LINES][MAX_LINEWIDTH],
int  width,
int  max_lines,
int  max_width 
)

This function takes an input string (can be in essentially arbitrary encoding) and loads it into an array of strings, each corresponding to one line of output text.

Parameters
input- A null-terminated input string.
str_list- A PRE_ALLOCATED array of characters pointers. This must be at least of size str_list[max_lines][max_width]
width- The desired number of characters per line. Note that words with more characters than "width" are not hypenated, so it's possible to get a line that is longer than "width".
max_lines- Memory-safety parameters for str_list.
max_width- Memory-safety parameters for str_list.
Returns
Linewrap returns the number of lines used to format the strings.
int T4K_LineWrapInsBreaks ( const char *  input,
char *  output,
int  width,
int  max_lines,
int  max_width 
)

This function takes an input string and inserts newline characters at places determined by the linebreak library, returning a single string.

Parameters
input- A null-terminated input string. output - Pre-allocated location to contain string with breaks inserted.
width- The desired number of characters per line. Note that words with more characters than "width" are not hypenated, so it's possible to get a line that is longer than "width".
max_lines- Memory-safety parameters for str_list.
max_width- Memory-safety parameters for str_list.
Returns
Linewrap returns the number of lines used to format the strings.
void T4K_LineWrapList ( const char  input[MAX_LINES][MAX_LINEWIDTH],
char  str_list[MAX_LINES][MAX_LINEWIDTH],
int  width,
int  max_lines,
int  max_width 
)

/brief This function takes a NULL_terminated array of strings and performs translations and linewrapping, outputting another NULL-terminated array.

/param input - A null-terminated input string. /param str_list - A PRE_ALLOCATED array of characters pointers. This must be at least of size str_list[max_lines][max_width] /param width - The desired number of characters per line. Note that words with more characters than "width" are not hypenated, so it's possible to get a line that is longer than "width". /param max_lines - Memory-safety parameters for str_list. /param max_width - Memory-safety parameters for str_list.

/return None

SDL_Surface* T4K_LoadBkgd ( const char *  file_name,
int  width,
int  height 
)

A wrapper for LoadImage() that optimizes the format of background image.

Parameters
file_name- File name of background image.
width- Width of the image.
height- Height of the image.
Returns
If successful it will return the newly created surface otherwise it will return a NULL value.
int T4K_LoadBothBkgds ( const char *  file_name,
SDL_Surface **  fs_bkgd,
SDL_Surface **  win_bkgd 
)

Load backgrounds for both fullscreen and windowed resolution.

Parameters
file_name- File name of background image.
fs_bkgd- Fullscreen surface.
win_bkgd- Windowed surface
Returns
1 - Successful loading of background.
0 - Failed loading of background.
SDL_Surface* T4K_LoadImage ( const char *  file_name,
int  mode 
)

Load an image without resizing it.

Parameters
file_name- File name of the image.
mode- Image mode.
Returns
If successful it will return the newly created surface otherwise it will return a NULL value.
SDL_Surface* T4K_LoadImageOfBoundingBox ( const char *  file_name,
int  mode,
int  max_width,
int  max_height 
)

Same as LoadScaledImage but preserve image proportions and fit it into max_width x max_height rectangle.

NOTE: Returned surface is not necessarily max_width x max_height!
Parameters
file_name- File name of the image.
mode- Image modes.
max_width- Max size of width of image.
max_height- Max size of height of image.
Returns
If successful it will return the newly created surface otherwise it will return a NULL value.
void T4K_LoadMenu ( int  index,
const char *  file_name 
)

Load menu from given XML file and store its tree under given index in "menus" array.

Parameters
index- The unique index of the menu.
file_name- The file name of the xml menu file.
Returns
None
Mix_Music* T4K_LoadMusic ( char *  datafile)

Load music from a datafile.

Parameters
datafile- File name of the music date.
Returns
Returns new created music.
SDL_Surface* T4K_LoadScaledImage ( const char *  file_name,
int  mode,
int  width,
int  height 
)

Load an image and resize it to given dimensions. If width or height is negative no resizing is applied.

The loader backend is chosen depending on file extension,
If an SVG file is not found, try to load its PNG equivalent
(unless IMG_NO_PNG_FALLBACK is set in mode)
Parameters
file_name- File name of the image.
mode- Image Mode
width- Width size of the image.
height- Height size of the image.
Returns
If successful it will return the newly created surface otherwise it will return a NULL value.
sprite* T4K_LoadScaledSprite ( const char *  name,
int  mode,
int  width,
int  height 
)

Load a multiple-frame sprite from disk and scale it to the given dimensions. This function loads an SVG sprite or multiple PNGs as needed.

Parameters
name- The filename of the sprite to load, without an extension.
mode- Loader flags to use, semantics the same as LoadImage.
width- Width of sprite.
height- Height of sprite.
Returns
If successful it will return the loaded sprite, otherwise it will return a NULL value.
Mix_Chunk* T4K_LoadSound ( char *  datafile)

Load a sound/music patch from a file.

Parameters
datafile- File name of the sound data.
Returns
Returns new created sound effect.
sprite* T4K_LoadSprite ( const char *  name,
int  mode 
)

Load a multiple-frame sprite from disk. This function loads an SVG sprite or multiple PNGs as needed.

Parameters
name- The filename of the sprite to load, without an extension.
mode- Loader flags to use, semantics the same as LoadImage.
Returns
If successful it will return the loaded sprite, otherwise it will return a NULL value.
sprite* T4K_LoadSpriteOfBoundingBox ( const char *  name,
int  mode,
int  max_width,
int  max_height 
)

Same as LoadScaledSprite but preserve image proportions and fit it into max_width x max_height rectangle. NOTE: Returned surface is not necessarily max_width x max_height !

Parameters
name- The filename of the sprite to load, without an extension.
mode- Loader flags to use, semantics the same as LoadImage.
max_width- Max width of sprite.
max_height- Max height of sprite.
Returns
If successful it will return the loaded sprite, otherwise it will return a NULL value.
void T4K_NextFrame ( sprite s)

Advance a sprite's frame.

Parameters
s- The sprite to advance.
Returns
None
void T4K_OnResolutionSwitch ( ResSwitchCallback  callback)

Register a callback to reposition and redraw screen elements when the resolution is changed.

Parameters
callback- A function to be called when resolution changes.
Returns
None
void T4K_PlaySound ( Mix_Chunk *  sound)

Play sound once and then exit.

Parameters
sound- Sound effect to play.
Returns
None
void T4K_PlaySoundLoop ( Mix_Chunk *  sound,
int  loops 
)

Play sound "loops" times, -1 for infinite.

Parameters
sound- Sound effect to play.
loops- Number of repeats to play the sound.
Returns
None
void T4K_PrerenderAll ( void  )

Prerender all menus, arrows and stop button. This function should be invoked after every resolution change.

Parameters
None
Returns
None
void T4K_PrerenderMenu ( int  index)

Prerender a single menu based on the screen resolution.

Parameters
index- The unique index of the menu.
Returns
None
char* T4K_RemoveSlash ( char *  path)

Remove a trailing slash from a file path.

Parameters
path- A path that may or may not end in a slash.
Returns
A path that does not end in a slash.
void T4K_ResetBlitQueue ( void  )

Just set the number of pending updates to zero.

Parameters
None
Returns
None
void T4K_RoundCorners ( SDL_Surface *  s,
Uint16  radius 
)

Round the corners of a surface by erasing edge pixels.

Parameters
s- The surface to process.
radius- The radius of the arcs on each corner. A smaller radius results in sharper edges.
Returns
None
int T4K_RunMenu ( int  index,
bool  return_choice,
void(*)()  draw_background,
int(*)(SDL_Event *)  handle_event,
void(*)()  handle_animations,
int(*)(int, int)  handle_activity 
)

RunMenu - main function to display the menu and run the event loop this function is a modified copy of choose_menu_item()

Parameters
index- The unique index of the menu.
return_choice- If true, then return chosen value instead of running handle_activity().
draw_background- A function that draws game-specific items, called once per frame.
handle_event- A function to process game-specific events.
handle_animations- A function to animate game-specific items.
handle_activity- A function to start an activity when the user selects it.
Returns
Returns a value operation of the user in the menu.
void T4K_SetActivitiesList ( int  num,
char **  acts 
)

Specify the set of activities the menu system should handle.

Parameters
num- The number of activities. acts should have num elements.
acts- An array of strings, each an activity provided by the game.
Returns
None
void T4K_SetFontName ( const char *  name)

Set the "global" font name.

Parameters
name- Name of the font to set.
Returns
None
void T4K_SetMenuFontSize ( MFStrategy  strategy,
int  size 
)

Set the font size for managed menus.

Parameters
strategy- How to determine menus' font size
size- A literal size to use. This will be ignored unless strategy is MF_EXACTLY.
Returns
None
void T4K_SetMenuSounds ( char *  mus_path,
Mix_Chunk *  click,
Mix_Chunk *  hover 
)

Set optional sound effects and music for menus.

Parameters
mus_path- The path to background music. NOT used!
click- The sound effect to play when an item is clicked
hover- The sound effect to play when an item is highlighted
Returns
None
void T4K_SetMenuSpritePrefix ( char *  pref)

Set the prefix that is used whe loading menu sprites.

Parameters
pref- The prefix that is used whe loading menu sprites.
Returns
None
void T4K_SetRect ( SDL_Rect *  rect,
const float *  pos 
)

This function will write an SDL_Rect with dimensions based on screen dimensions.

Parameters
rect- A pointer to the rect to fill.
pos- Four floats between 0.0 and 1.0 which specify the desired x, y, w and h as a percentage of screen dimensions.
Returns
None
int T4K_Setup_SDL_Text ( void  )

Initialize the backend (Pango or TTF) used for text-drawing functions.

Parameters
None
Returns
1 - Successful initialization fo the text-drawing backend.
0 - Failed initialization.
SDL_Surface* T4K_SimpleText ( const char *  t,
int  size,
SDL_Color *  col 
)

Returns a non-outlined surface using either SDL_Pango or SDL_ttf.

Parameters
t- String to draw.
size- Font size
col- Color
Returns
A non-outlined surface using either SDL_Pango or SDL_ttf.
SDL_Surface* T4K_SimpleTextWithOffset ( const char *  t,
int  size,
SDL_Color *  col,
int *  glyph_offset 
)

Same as T4K_SimpleText, but the text offset is also stored.

Parameters
t- String to draw.
size- Font size
col- Color
glyph_off- Set the var in which to store the offset.
Returns
A non-outlined surface using either SDL_Pango or SDL_ttf.
void T4K_SwitchScreenMode ( void  )

Switch between fullscreen and windowed mode. Resolution switching callbacks are invoked.

Parameters
None
Returns
None
void T4K_Throttle ( int  loop_msec,
Uint32 *  last_t 
)

/brief Use this simple function to keep a loop from eating all CPU. Here we use SDL_Delay() to wait to return until 'loop_msec' milliseconds after it returned the last time. Per SDL docs, the granularity is likely no better than 10 msec

/param loop_msec - The desired loop duration, in msec /param last_t - The valid location of a Uint32 where timing can be stored between invocations of this function.

/return None

int T4K_TransWipe ( const SDL_Surface *  newbkg,
WipeStyle  type,
int  segments,
int  duration 
)

Perform a wipe from the current screen image to a new one.

Parameters
newbkg- The new image to wipe.
type- The WipeStyle to use.
segments- The number of division of the screen.
duration- The length of the animation in milliseconds.
Returns
Return 0 if newbkg is NULL and new background surface width and height is not equal to screen width and height otherwise returns 1.
void T4K_UnloadMenus ( void  )

free all loaded menu trees

Parameters
None
Returns
None
void T4K_UpdateRect ( SDL_Surface *  surf,
SDL_Rect *  rect 
)

Wrap a call to SDL_UpdateRect.

Parameters
surf- The surface to update.
rect- The dimension of the surface to update.
Returns
None
void T4K_UpdateScreen ( int *  frame)

Update the screen and increment the frame counter.

Parameters
frame- Increments every update of the screen.
Returns
None
SDL_EventType T4K_WaitForEvent ( SDL_EventMask  events)

Block application until SDL receives an appropriate event. Use sparingly.

Parameters
events- A single or OR'd combination of event masks.
Returns
The event type received.
SDL_Surface* T4K_zoom ( SDL_Surface *  src,
int  new_w,
int  new_h 
)

This function will scale an existing surface.

Parameters
src- The original surface, which is left unscathed.
new_w- The width of the new surface.
new_h- The height of the new surface.
Returns
Will return a newly allocated SDL_Surface.

Variable Documentation

int debug_status
SDL_Rect menu_rect
SDL_Surface * next_arrow
SDL_Surface * next_gray
SDL_Rect next_rect
SDL_Surface * prev_arrow
SDL_Surface * prev_gray
SDL_Rect prev_rect
SDL_Surface* screen
SDL_Surface* stop_button
SDL_Rect stop_rect
char wrapped_lines[MAX_LINES][MAX_LINEWIDTH]

Global buffer for wrapped lines.