Base

Description

Basic types and functionalities.

Collaboration diagram for Base:

Classes
class	CNetpbmReader
	Reader for Netpbm image files. More...
class	CTextFormat
class	CTextSet
	Typesetter for longer formatted texts. More...

Macros
#define	UI_RES_X   1024
	UI resolution in pixels (X)
#define	UI_RES_Y   600
	UI resolution in pixels (Y)

Events ...
enum	EUserEvent
void	UiIterate (bool noWait=false)
static void	UiIterateNoWait ()
	Iterate the application's main event loop; Does not sleep, but returns immediately ("yield"-functionality for longer running processes in the UI thread).
void	UiQuit ()
	Quit the application.
bool	UiIsClosed ()
	Is the application quitting?
void	UiPushUserEvent (EUserEvent code, void *data1=NULL, void *data2=NULL)
static void	MainThreadCallback (void(*func)(void *), void *data=NULL)
	Request function 'func' to be called by main thread at next occasion.

Font handling ...
enum	EFontStyle {   fntNormal = 0 , fntBold , fntItalic , fntBoldItalic ,   fntLight , fntMono , fntMonoBold , fntMonoItalic ,   fntMonoBoldItalic , fntEND }
	Supported font styles. More...
TTF_Font *	FontGet (EFontStyle style, int size)
	Get a reference to a font of a specific style and size.
SDL_Surface *	FontRenderText (TTF_Font *font, const char *text, TColor color)
	Render a text using 'blended' mode of the SDL2_ttf library. The returned surface is a new surface of minimal size and must later be free'd using SurfaceFree().
SDL_Surface *	FontRenderText (TTF_Font *font, const char *text, TColor color, TColor bgColor)
	Render a text using 'shaded' mode of the SDL2_ttf library. This mode is considered faster than 'blended' mode. The returned surface is a new surface of minimal size and must later be free'd using SurfaceFree().
static int	FontGetLineSkip (TTF_Font *font)
static int	FontGetHeight (TTF_Font *font)
int	FontGetWidth (TTF_Font *font, const char *text, int textLen=-1)

General functions ...
void	UiInit (const char *windowTitle="Home2L")
void	UiDone ()
static SDL_Renderer *	UiGetSdlRenderer ()
void	UiGetWindowSize (int *w, int *h)
void	UiSetWindowSize (int w, int h)
bool	UiGetWindowFullScreen ()
void	UiSetWindowFullScreen (bool _fullScreen)
void	UiToggleWindowFullScreen ()
bool	UiGetWindowResizable ()
void	UiSetWindowResizable (bool _resizable)
void	UiToggleWindowResizable ()

SDL audio ...
Audio playing functionality. The following functions are not thread-safe and must be called from the main thread, which is the one executing timers.
void	AudioStart (const char *fileName, int repetitions=1, TTicks repetitionGap=0)
	Start playing audio. More...
void	AudioStop ()
	Stop playing audio immediately.
bool	AudioIsPlaying ()
	Query if audio is still playing. If 'false' is returned, the audio device is surely in a stopped state.
#define	AUDIO_FOREVER   -1
	Constant to specify an infinite number of repetitions.

Color helpers ...
static TColor	ToColor (Uint8 r, Uint8 g, Uint8 b, Uint8 a=255)
static TColor	ToColor (Uint32 val)
static Uint32	ToUint32 (TColor color)
static Uint32	ToUint32 (Uint8 r, Uint8 g, Uint8 b, Uint8 a=255)
static TColor	ToColor (SDL_Color sdlCol)
static bool	operator== (const TColor &col1, const TColor &col2)
static bool	operator!= (const TColor &col1, const TColor &col2)
static SDL_Color	ToSDL_Color (TColor color)
TColor	ColorSum (TColor col1, TColor col2)
	Add two colors (with saturation).
TColor	ColorBrighter (TColor color, int d)
	Increase all color components by d with saturation; d may be negative.
static TColor	ColorDarker (TColor color, int d)
	Decreas all color components by d with saturation; d may be negative.
TColor	ColorScale (TColor color, int factor)
	Multiply all components with a factor. 'factor' is a fixed point number with 8 fractional bits (1.0 == 0x100).
TColor	ColorBlend (TColor color0, TColor color1, int weight1)
	Blend two colors; 'weight' is a fixed point number with 8 fractional bits (1.0 == 0x100) and refers to 'color1'.
#define	SELECTED_SDL_PIXELFORMAT   SDL_PIXELFORMAT_ARGB8888
	Selected (SDL) pixel format. More...
#define	COL_MASK_R   0x00FF0000
#define	COL_MASK_G   0x0000FF00
#define	COL_MASK_B   0x000000FF
#define	COL_MASK_A   0xFF000000
#define	COL_MASK_RGB   (COL_MASK_R | COL_MASK_G | COL_MASK_B)

Geometry helpers ...
static SDL_Rect	Rect (int x, int y, int w, int h)
static SDL_Rect	Rect (int w, int h)
static SDL_Rect	Rect (SDL_Surface *surf)
static SDL_Rect	Rect (SDL_Texture *tex)
static SDL_Rect	RectScreen ()
	Rectangle representing the whole UI screen.
static void	RectMove (SDL_Rect *rect, int dx, int dy)
static void	RectGrow (SDL_Rect *rect, int dx, int dy)
void	RectAlign (SDL_Rect *rect, SDL_Rect container, int hAlign=-1, int vAlign=-1)
	Align the rectangle 'rect' with an outer rectangle 'container'. More...
static void	RectCenter (SDL_Rect *rect, SDL_Rect container)
	Center the rectangle 'rect' with respect to an outer rectangle 'container'.
static bool	RectContains (SDL_Rect *rect, int x, int y)

Surface helpers ...
See also: CNetpbmReader
static SDL_Surface *	CreateSurface (int w, int h)
static SDL_Surface *	CreateSurface (SDL_Rect r)
static SDL_Surface *	CreateSurface (SDL_Rect *r)
static SDL_Surface *	CreateSurfaceFrom (int w, int h, void *_pixels, int _pitch)
static SDL_Surface *	SurfaceSet (SDL_Surface **pSurf, SDL_Surface *newSurf)
static void	SurfaceFree (SDL_Surface **pSurf)
static void	SurfaceFree (SDL_Surface *surf)
static SDL_Surface *	SurfaceDup (SDL_Surface *src)
void	SurfaceNormalize (SDL_Surface **pSurf)
	Normalize pixel format to SELECTED_SDL_PIXELFORMAT.
void	SurfaceRecolor (SDL_Surface *surf, TColor color)
	Replace all RGB values with the passed color while leaving alpha values untouched.
SDL_Surface *	SurfaceGetOpaqueCopy (SDL_Surface *surf, TColor backColor)
	Create an opaque copy; caller becomes owner of returned surface.
void	SurfaceMakeTransparentMono (SDL_Surface *surf, Uint8 opaqueLevel=0xff)
	Copy the R values to the A channel and make all RGB values white. More...
void	SurfaceBlit (SDL_Surface *src, SDL_Rect *srcRect, SDL_Surface *dst, SDL_Rect *dstRect=NULL, int hAlign=0, int vAlign=0, SDL_BlendMode blendMode=SDL_BLENDMODE_NONE)
	Blit a surface; It is allowed to leave 'src == NULL', in which case nothing happens. More...
static void	SurfaceFill (SDL_Surface *surf, TColor col)
static void	SurfaceFillRect (SDL_Surface *surf, SDL_Rect r, TColor col)
static void	SurfaceFillRect (SDL_Surface *surf, SDL_Rect *r, TColor col)
SDL_Surface *	SurfaceGetScaledDownCopy (SDL_Surface *surf, int factor, bool preserveThinLines=false)
	Get a copy of the surface, scaled down by a factor in both dimensions. More...
SDL_Surface *	SurfaceGetFlippedAndRotatedCopy (SDL_Surface *surf, int orient)
	Get a copy of the surface, which is eventually flipped and then rotated in 90° steps clockwise 'surf' must conform to SELECTED_SDL_PIXELFORMAT (see SurfaceNormalize() ).
SDL_Surface *	SurfaceReadBmp (const char *fileName)
	Read a .bmp file. More...
#define	ORIENT(FLIPH, ROT)   (((FLIPH) ? 4 : 0) | ((ROT) & 3))
	Get orientation identifier based on horizontal flipping and a rotation in 90 degree steps clock-wise.
#define	ORIENT_WITH_FLIPV(FLIPH, ROT)   (((FLIPH) ? 0 : 4) | (((ROT) + 2) & 3))
	Get orientation identifier with implied vertical flipping first.
#define	ORIENT_FLIPH(ORI)   (((ORI) & 4) ? true : false)
	Get whether horizontal flipping is included in the orientation.
#define	ORIENT_ROT(ORI)   ((ORI) & 3)
	Get the number of rotations.
#define	NETPBM_IDLE   -3
	State code "idle" for CNetpbmReader.
#define	NETPBM_ERROR   -2
	State code "error" for CNetpbmReader.
#define	NETPBM_SUCCESS   -1
	State code "success" for CNetpbmReader.

Texture helpers ...
static SDL_Texture *	CreateTexture (SDL_Surface *surf)
static void	TextureSet (SDL_Texture **pTex, SDL_Texture *newTex)
static void	TextureFree (SDL_Texture **pTex)
static void	TextureRender (SDL_Texture *tex, SDL_Rect *srcRect=NULL, SDL_Rect *dstRect=NULL)

Icon handling ...
SDL_Surface *	IconGet (const char *name, TColor color=WHITE, TColor bgColor=TRANSPARENT, int scaleDown=1, int orient=0, bool preserveThinLines=false)
	Get a reference to an icon from the application's 'etc/icons/' or 'share/icons/' folder. More...

Complex text formatting ...
See also: CTextFormat, CTextSet
SDL_Surface *	TextRender (const char *text, CTextFormat fmt, SDL_Surface *dst=NULL, SDL_Rect *dstRect=NULL, bool *retAbbreviated=NULL)
	Easy-to-use function to typeset a text with a single format.

Color palette ...
#define	WHITE   ToColor (0xff, 0xff, 0xff)
#define	LIGHT_GREY   ToColor (0xc0, 0xc0, 0xc0)
#define	GREY   ToColor (0x80, 0x80, 0x80)
#define	DARK_GREY   ToColor (0x40, 0x40, 0x40)
#define	DARK_DARK_GREY   ToColor (0x20, 0x20, 0x20)
#define	BLACK   ToColor (0x00, 0x00, 0x00)
#define	RED   ToColor (0xff, 0x00, 0x00)
#define	GREEN   ToColor (0x00, 0xff, 0x00)
#define	BLUE   ToColor (0x00, 0x00, 0xff)
#define	CYAN   ToColor (0x00, 0xff, 0xff)
#define	MAGENTA   ToColor (0xff, 0x00, 0xff)
#define	YELLOW   ToColor (0xff, 0xff, 0x00)
#define	DARK_RED   ToColor (0x80, 0x00, 0x00)
#define	DARK_GREEN   ToColor (0x00, 0x80, 0x00)
#define	DARK_BLUE   ToColor (0x00, 0x00, 0x80)
#define	DARK_CYAN   ToColor (0x00, 0x80, 0x80)
#define	DARK_MAGENTA   ToColor (0x80, 0x00, 0x80)
#define	DARK_YELLOW   ToColor (0x80, 0x80, 0x00)
#define	LIGHT_RED   ToColor (0xff, 0x80, 0x80)
#define	LIGHT_GREEN   ToColor (0x80, 0xff, 0x80)
#define	LIGHT_BLUE   ToColor (0x80, 0x80, 0xff)
#define	LIGHT_CYAN   ToColor (0x80, 0xff, 0xff)
#define	LIGHT_MAGENTA   ToColor (0xff, 0x80, 0xff)
#define	LIGHT_YELLOW   ToColor (0xff, 0xff, 0x80)
#define	BROWN   ToColor (0x80, 0x40, 0x00)
#define	LIGHT_BROWN   ToColor (0xc0, 0x80, 0x40)
#define	ORANGE   ToColor (0xc0, 0x40, 0x00)
#define	TRANSPARENT   ToColor (0x00, 0x00, 0x00, 0x00)

Macro Definition Documentation

SELECTED_SDL_PIXELFORMAT

#define SELECTED_SDL_PIXELFORMAT   SDL_PIXELFORMAT_ARGB8888

Selected (SDL) pixel format.

We define a selected pixel format, on which all higher-level routines can rely on for efficient direct pixel manipulations. All functions in this module (i.e. 'Image*' and 'Font*') always return surfaces in the correct format. Textures are always created with that format, or the texture creation fails completely.

The format must be selected carefully to match the underlying hardware architecture for performance reasons.

Definition at line 193 of file ui_base.H.

Enumeration Type Documentation

EFontStyle

enum EFontStyle

Supported font styles.

Enumerator
fntNormal	Normal.
fntBold	Bold.
fntItalic	Italic.
fntBoldItalic	Bold and italic.
fntLight	Light.
fntMono	Monotype.
fntMonoBold	Monotype, bold.
fntMonoItalic	Monotype, italic.
fntMonoBoldItalic	Monotype, bold and italic.

Definition at line 590 of file ui_base.H.

Function Documentation

UiIterate()

void UiIterate

(

bool

noWait = false

)

Iterate the application's main event loop:

• Check for SDL events and call 'HandleEvent' for the active screen on new events
• Check timers and execute their callbacks
• Redraw UI if changes are pending
• Do some housekeeping related to window mapping, pause/resume in Android, ...
• On a long push, generate an SDL_MOUSEBUTTONDOWN event with 'clicks == 2'

Execution may take a longer period of time if a) no events occur (sleep mode) and 'noWait == false' or b) some event handler calls 'CScreen::Run' for a new screen.

AudioStart()

void AudioStart	(	const char *	fileName,
		int	repetitions = 1,
		TTicks	repetitionGap = 0
	)

Start playing audio.

The contents of the audio file are enqueued in a non-blocking way for the given number of repetitions and a playback gap of the given time (if applicable). If 'repetitions == AUDIO_FOREVER', the audio is repeated forever or until stopped.

RectAlign()

void RectAlign	(	SDL_Rect *	rect,
		SDL_Rect	container,
		int	hAlign = -1,
		int	vAlign = -1
	)

Align the rectangle 'rect' with an outer rectangle 'container'.

Parameters

rect	Rectangle to align.
container	Outer rectangle serving as a reference.
hAlign	Horizontal alignmnent: -1 = left, 0 = center, +1 = right.
vAlign	Vertical alignmnent: -1 = upper, 0 = center, +1 = lower.

SurfaceMakeTransparentMono()

void SurfaceMakeTransparentMono	(	SDL_Surface *	surf,
		Uint8	opaqueLevel = 0xff
	)

Copy the R values to the A channel and make all RGB values white.

'opaqueLevel' determines what is "white" here. This will be the final color, and all pixels originally brighter than this will be fully opaque.

SurfaceBlit()

void SurfaceBlit	(	SDL_Surface *	src,
		SDL_Rect *	srcRect,
		SDL_Surface *	dst,
		SDL_Rect *	dstRect = NULL,
		int	hAlign = 0,
		int	vAlign = 0,
		SDL_BlendMode	blendMode = SDL_BLENDMODE_NONE
	)

Blit a surface; It is allowed to leave 'src == NULL', in which case nothing happens.

Parameters

src	is the source surface.
srcRect	is the part of the source surface to be blit (default = complete surface).
dst	is the destination surface.
dstRect	is the part of the destination surface to be rendered into (default = complete surface).
hAlign	is the horizontal alignment, if the destination rectangle has a different size (typically larger) than the source rectangle.
vAlign	is the vertical alignment, if the destination rectangle has a different size (typically larger) than the source rectangle.
blendMode	is the SDL blend mode.

SurfaceGetScaledDownCopy()

SDL_Surface * SurfaceGetScaledDownCopy	(	SDL_Surface *	surf,
		int	factor,
		bool	preserveThinLines = false
	)

Get a copy of the surface, scaled down by a factor in both dimensions.

The dimensions of the original surface should be multiples of 'factor'. 'preserveThinLines == true' performs a gamma-correction on the alpha channel to increase small alpha values and may be used to avoid that thin lines get averaged out when scaling down.

SurfaceReadBmp()

SDL_Surface * SurfaceReadBmp

(

const char *

fileName

)

Read a .bmp file.

Parameters

fileName

may either be an absolute path name or relative to HOME2L_ROOT.

On error, a warning is emitted and NULL is returned.

IconGet()

SDL_Surface * IconGet	(	const char *	name,
		TColor	color = WHITE,
		TColor	bgColor = TRANSPARENT,
		int	scaleDown = 1,
		int	orient = 0,
		bool	preserveThinLines = false
	)

Get a reference to an icon from the application's 'etc/icons/' or 'share/icons/' folder.

The name is passed without a file name suffix. The returned reference remains owned by the library, which may perform some caching if icons are used muliple times.