---

ZE::ZEngine Class Reference

#include <ZE_ZEngine.h>

List of all members.

---

Detailed Description

ZEngine Singleton Class, accessible from anywhere in a ZEngine-based program by nature. Controls core elements of program and does majority of SDL wrapping. Also keeps track of loaded data and helps programs avoid memory leaks and dangling pointers.

Public Methods
void	SetupDisplay (int width, int height, int bpp, bool fullscreen)
	Setup Display for SDL.
void	SetupSound (int rate, bool stereo)
	Initialize Sound for SDL.
bool	CreateDisplay (string title, string icon="")
	Create Display with predefined settings.
void	CloseDisplay ()
	Quit SDL and any Subsystems.
void	ToggleFullscreen ()
	Toggle fullscreen/windowed mode.
bool	Initialized ()
	Check state of ZEngine.
SDL_Surface *	Display ()
	Allow access to Screen Surface.
void	Update ()
	Update display contents.
void	Clear (float red=0.0f, float green=0.0f, float blue=0.0f, float alpha=1.0f)
	Clear screen to a certain color (Black by default).
void	SetGL2D ()
	Setup OpenGL ortho mode.
void	Delay (Uint32 milliseconds)
	Sleep for a certain amount of time.
Uint32	GetTime ()
	Get Global ZEngine time.
void	PauseTimer ()
	Pause ZEngine.
void	UnpauseTimer ()
	Unpause ZEngine.
double	GetFrameTime ()
	Get Seconds Per Frame.
double	GetFramerate ()
	Get Frames Per Second.
void	SetDesiredFramerate (Uint8 rate)
	Set Desired Framerate.
Uint8	GetDesiredFramerate ()
	Get Desired Framerate.
bool	IsPaused ()
	Check Engine Paused State.
bool	IsActive ()
	Find out if application is active.
void	RequestQuit ()
	Request A Quit.
bool	QuitRequested ()
	Find out if user has requested to quit.
void	SetReloadNeed (bool state)
	Set State of ImagesNeedReload.
bool	ImagesNeedReload ()
	Find out if images should be reloaded.
void	SetKeyRepeatRate (int rate)
	Set Key repeat rate.
bool	KeyIsPressed (SDLKey key)
	Find the state of a key.
bool	KeyPress (SDLKey key)
	Find if key has been pressed since last check.
void	HideCursor ()
	Hide mouse cursor.
void	ShowCursor ()
	Show mouse cursor.
int	MouseX ()
	Get X Position of Mouse.
int	MouseY ()
	Get Y Position of Mouse.
bool	LButtonPressed ()
	Get Status of Left Button.
bool	RButtonPressed ()
	Get Status of Right Button.
bool	MouseInRect (SDL_Rect *rect)
	Check if mouse is in given rectangle.
void	CheckEvents ()
	Check for Activation, Window Manager, and Quit Events.
void	SetEventFilter (SDL_EventFilter filter)
	Add a SDL Event Filter for user processing of events.
void	InitPhysFS (string argv)
	Initialize PhysicsFS.
void	AddPhysFSDir (string dir)
	Add Directory to PhysFS Search Path.
void	SetErrorLog (bool logAll, string logFile="")
	Modify Error Logging.
void	ReportError (ZErrorCode code, string desc="", string file="", unsigned int line=0)
	Report an error.
ZErrorCode	GetLastError ()
	Get the last error.
void	WriteLog (string str)
	Write to the log.
void	FlushErrors ()
	Flush Stack of Errors to file.
void	SeedRandom (unsigned long seed)
	Seed random number generator.
unsigned long	RandLong (unsigned long max)
	Obtain random integer [0,max).
long	RandLong (long min, long max)
	Obtain random integer [min,max].
double	RandDouble ()
	Obtain random double [0,1).
double	RandDouble (double min, double max)
	Obtain random double [min,max].
SDL_Surface *	LoadImage (string filename)
	Load an Image.
Mix_Chunk *	LoadSound (string filename)
	Load a Sound.
Mix_Music *	LoadMusic (string filename)
	Load a Music File.
TTF_Font *	LoadFont (string filename, int size)
	Load a Font.
int	Width ()
	Get Current Display Width.
int	Height ()
	Get Current Display Height.
int	BPP ()
	Get Current Display BPP.
bool	IsFullscreen ()
	Get Fullscreen setting.
Static Public Methods
ZEngine *	GetInstance ()
	Get Instance.
void	ReleaseInstance ()
	Release Instance.
string	GetVersion ()
	Get Current Version.
Private Methods
	ZEngine ()
	Constructor for ZEngine.
void	LogError (ZError error)
	Writes an error to file.
Private Attributes
int	mWidth
	Width of Display.
int	mHeight
	Height of Display.
int	mBPP
	BPP Setting of Display.
bool	mFullscreen
	Fullscreen setting of Display.
bool	mInitialized
	If ZEngine display has been setup.
SDL_Surface *	mScreen
	Pointer to Display.
bool	mPaused
	Keep track of paused state of game.
bool	mUnpauseOnActive
	Keep track of if ZEngine should unpause on active event.
Uint8	mDesiredFramerate
	Value framerate strives to be at, set by SetDesiredFramerate.
Uint32	mNextUpdate
	Time scheduled for next update (used for framerate locked movement).
Uint32	mLastPause
	Keep track of time game was last paused.
Uint32	mPausedTime
	Keep track of total globally paused time.
Uint32	mLastTime
	Keep track of last screen update time.
double	mSecPerFrame
	Seconds per frame.
bool	mNeedReload
	bool which is only set to true if the engine thinks the images need to be reloaded (loss of focus in fullscreen).
bool	mActive
	bool describing Active or Inactive State of Game
bool	mQuit
	bool for checking if a Quit event has been detected
Uint8 *	mKeyIsPressed
	Pointer to array of Keys.
bool	mKeyPress [SDLK_LAST]
	Array of keys, used by KeyPress.
int	mMouseX
	X Position of Mouse.
int	mMouseY
	Y Position of Mouse.
Uint8	mMouseB
	Mouse Button Information.
queue< ZError >	mErrorQueue
	Stack of Errors which have occured.
ZError	mCurError
	Current error.
bool	mLogAllErrors
	Option controlling how logfile is used.
FILE *	mErrlog
	C-style FILE* for error logging.
int	mRate
	Sound Bitrate.
bool	mStereo
	Stereo setting of Sound Subsystem.
Static Private Attributes
ZEngine *	sInstance = NULL
	Static Pointer to Instance of ZEngine for Singleton.

---

Constructor & Destructor Documentation

ZE::ZEngine::ZEngine (    )  [private]

Initialize ZEngine values to defaults. (Private so that only one instance may be created.)

---

Member Function Documentation

ZEngine * ZE::ZEngine::GetInstance (    )  [static]

Static function, returns pointer to instance of ZEngine, creating an instance if none exist. Returns: Instance to the ZEngine.

void ZE::ZEngine::ReleaseInstance (    )  [static]

Release memory held by instance of engine and closes window.

string ZE::ZEngine::GetVersion (    )  [static]

Get Version Number of ZEngine. (Major.Minor.Extension#) Returns: string containing version number

void ZE::ZEngine::SetupDisplay (  int    width, int    height, int    bpp, bool    fullscreen )

Sets display parameters to specified parameters. (called before CreateDisplay) Parameters: width  Desired width of screen or window. height  Desired height of screen or window. bpp  Desired BPP for screen, generally use 8,16 or 32, pass -1 if you want ZEngine to guess the best choice. fullscreen  A bool for fullscreen setting.

void ZE::ZEngine::SetupSound (  int    rate, bool    stereo )

Set sound settings to specified parameters. (If not called before CreateDisplay rate will default to 22050+mono) Parameters: rate  Desired sound bitrate. stereo  A bool for stereo setting.

bool ZE::ZEngine::CreateDisplay (  string    title, string    icon = "" )

SetupDisplay and SetupSound should be called prior to this to change settings, settings from those do not go into effect until this function is called. Specify no icon file to use default icon for OS. Returns result of setting up ZEngine, and logs error if false is returned (Trys not to fail + returns bool in versions >= 0.8.2). Parameters: title  Window Title. icon  Path to Icon File. Returns: result of setting up the display, true if everything went ok, false if any setup failed (check GetLastError).

void ZE::ZEngine::CloseDisplay (    )

Shut down SDL (and SDL_ttf,SDL_mixer if necessary) You shouldn't ever have to call this, ReleaseInstance calls this for you.

void ZE::ZEngine::ToggleFullscreen (    )

Safely toggles fullscreen/windowed mode, generally toggling modes will bring the need to reload images so it will set the ImagesNeedReload state to true. Since: 0.8.2

bool ZE::ZEngine::Initialized (    )

Checks if ZEngine display has been properly setup. Since: 0.8.2 Returns: Boolean status of ZEngine, true if CreateDisplay has been successfully called, false if ZEngine has no display.

SDL_Surface * ZE::ZEngine::Display (    )

Get pointer to screen SDL_Surface, allowing direct screen manipulation using SDL. Returns: Pointer to Display Surface.

void ZE::ZEngine::Update (    )

Swap OpenGL buffers, and update screen, if a desired framerate is set it will delay to stay under that rate. Must be called every frame.

void ZE::ZEngine::Clear (  float    red = 0.0f, float    green = 0.0f, float    blue = 0.0f, float    alpha = 1.0f )

Clears a rectangle on screen to a color, defaults to solid black. Parameters: red  Red component (0.0-1.0) of new color. green  Green component (0.0-1.0) of new color. blue  Blue component (0.0-1.0) of new color. alpha  Alpha component (0.0-1.0) of new color.

void ZE::ZEngine::SetGL2D (    )

Sets the OpenGL scaled orthographic mode, called once at beginning, no need to call unless you change the OpenGL mode manually.

void ZE::ZEngine::Delay (  Uint32    milliseconds )

Freeze everything for given number of milliseconds. Parameters: milliseconds  Number of milliseconds to freeze.

Uint32 ZE::ZEngine::GetTime (    )

Get active time since ZEngine initialization in milliseconds, paused time doesn't count. Returns: Number of active milliseconds since initialization.

void ZE::ZEngine::PauseTimer (    )

Pause ZEngine timer and all ZTimer objects that rely on ZEngine.

void ZE::ZEngine::UnpauseTimer (    )

Unpause ZEngine timer and all ZTimer objects that rely on ZEngine.

double ZE::ZEngine::GetFrameTime (    )

Get double that describes the time passed between screen updates. (should be used for Framerate Independant Movement) Returns: Time between screen updates.

double ZE::ZEngine::GetFramerate (    )

Get double representing current (approximate) FPS. This value is always the same as 1/GetFrameTime(). Since: 0.8.2 Returns: Current Framerate.

void ZE::ZEngine::SetDesiredFramerate (  Uint8    rate )

Sets desired framerate, if engine gets ahead of desired rate during a frame it will stall in Update until current framerate is closer to that desired. Acceptable values are 1-255, setting this value to 0 will disable this feature. (Desired framerate is disabled upon initialization of ZEngine.) Since: 0.8.2 Parameters: rate  Desired framerate 1-255, or 0 to disable.

Uint8 ZE::ZEngine::GetDesiredFramerate (    )

Get desired framerate set by SetDesiredFramerate. Since: 0.8.2 Returns: Current setting for desired framerate.

bool ZE::ZEngine::IsPaused (    )

Find out if engine timer is paused. Returns: Paused State of engine.

bool ZE::ZEngine::IsActive (    )

Function to find out if application currently has focus. Returns: bool telling active/inactive state of application.

void ZE::ZEngine::RequestQuit (    )

Tell the engine that it should behave as if a Quit was requested, does not call any shutdown functions.

bool ZE::ZEngine::QuitRequested (    )

Function to find out if user or operating system has requested program cease execution, can be set by Alt-F4, SDL_Quit event or ZEngine::RequestQuit(). Returns: bool telling if quit has been requested.

void ZE::ZEngine::SetReloadNeed (  bool    state )

Parameters: state  False if images need to be reloaded, True if images have been reloaded.

bool ZE::ZEngine::ImagesNeedReload (    )

Function that is good to call every frame to check if images should be reloaded, usually only caused by loss of focus in fullscreen. Returns: bool, True if images should be reloaded, false otherwise.

void ZE::ZEngine::SetKeyRepeatRate (  int    rate )

Calls SDL_EnableKeyRepeat(rate,rate) because usually this is the desired movement style for games. 0 to disable. If 2 different values are needed SDL_EnableKeyRepeat can be called separately: http://sdldoc.csn.ul.ie/sdlenablekeyrepeat.php. Parameters: rate  Desired key repeat rate.

bool ZE::ZEngine::KeyIsPressed (  SDLKey    key )

Function returns true/false based on if key is currently pressed or not. Parameters: key  Code of key to find status of. Returns: State of requested key.

bool ZE::ZEngine::KeyPress (  SDLKey    key )

Function returns true/false based on if key has been pressed since last check. Parameters: key  Code of key to find status of. Returns: State of requested key.

void ZE::ZEngine::HideCursor (    )

Hide the system mouse cursor.

void ZE::ZEngine::ShowCursor (    )

Show the system mouse cursor.

int ZE::ZEngine::MouseX (    )

Find X Position of Mouse on screen. Returns: X Position of Mouse.

int ZE::ZEngine::MouseY (    )

Find Y Position of Mouse on screen. Returns: Y Position of Mouse.

bool ZE::ZEngine::LButtonPressed (    )

Get pressed status of left button of mouse. Returns: true if left button is pressed, false otherwise.

bool ZE::ZEngine::RButtonPressed (    )

Get pressed status of right button of mouse. Returns: true if right button is pressed, false otherwise.

bool ZE::ZEngine::MouseInRect (  SDL_Rect *    rect )

Return status of mouse in current rectangle (used for buttons) Parameters: rect  Rectangle to check if mouse is in. Returns: true if mouse is in rectangle, false otherwise

void ZE::ZEngine::CheckEvents (    )

Cycle through event queue, processing events, updating all Event Related variables, should be called once per frame.

void ZE::ZEngine::SetEventFilter (  SDL_EventFilter    filter )

This is only needed when you need tight control with ZEngine. The parameter is simply passed to SDL_SetEventFilter, generally only those with a good amount of SDL experience should use this function or ZEngine's internal message state could be corrupted. For more information on SDL_SetEventFilter see http://sdldoc.csn.ul.ie/sdlseteventfilter.php. Since: 0.8.2 Parameters: filter  An SDL_EventFilter (A function that takes a const SDL_Event* and returns 0 if the event should be removed from the event queue and 1 otherwise.)

void ZE::ZEngine::InitPhysFS (  string    argv )

Sets up PhysicsFS, must be called when application is started. Parameters: argv  argv[0] from application's main.

void ZE::ZEngine::AddPhysFSDir (  string    dir )

Add Directory to PhysicsFS search path, the path it looks in for files when attempting to load. Parameters: dir  Directory to add to search path.

void ZE::ZEngine::LogError (  ZError    error )  [private]

Writes error to current error file. Since: 0.8.2 Parameters: error  ZError to write to file.

void ZE::ZEngine::SetErrorLog (  bool    logAll, string    logFile = "" )

Change the way errors are logged and the file they are logged to, before calling this errors are logged to stderr. (SDL may define stderr.txt on some platforms.) Since: 0.8.2 Parameters: logAll  If set to true every error will be written to file instead of stored in the logfile. logFile  Name of file to use as log, passing in stderr or stdio will set the log to the C streams. Passing in nothing will not change the current error log file, which defaults to stderr.

void ZE::ZEngine::ReportError (  ZErrorCode    code, string    desc = "", string    file = "", unsigned int    line = 0 )

Adds the error to the the error queue, and sets the current error to this error. Since: 0.8.2 Parameters: code  ZErrorCode of error. desc  Optional string describing error. file  Optional argument specifying the file the error occured in. line  Optional argument specifying the line the error occured on.

ZErrorCode ZE::ZEngine::GetLastError (    )

Get the last error reported. Since: 0.8.2 Returns: ZErrorCode of last error reported.

void ZE::ZEngine::WriteLog (  string    str )

Write a string to the log, allowing special usage of the error log. Since: 0.8.2 Parameters: str  String to write to log file.

void ZE::ZEngine::FlushErrors (    )

Write the error stack to the error log. Since: 0.8.2

void ZE::ZEngine::SeedRandom (  unsigned long    seed )

Reseed Mersenne Twister (MT19937) random number generator. NOTE: Generator is initialized upon creation of ZEngine using time. (Faster and more random than rand(), see src/external/mt19937ar.c) Since: 0.8.3 Parameters: seed  Seed for random sequence.

unsigned long ZE::ZEngine::RandLong (  unsigned long    max )

Obtain random long l where 0 <= l < max. Since: 0.8.3 Parameters: max  Limit for random number. Returns: Random unsigned long.

long ZE::ZEngine::RandLong (  long    min, long    max )

Obtain random long l where min <= l <= max. Since: 0.8.3 Parameters: min  Lower limit for random number. max  Upper limit for random number. Returns: Random long.

double ZE::ZEngine::RandDouble (    )

Obtain random double d where 0 <= d < 1. Since: 0.8.3 Returns: Random double [0,1).

double ZE::ZEngine::RandDouble (  double    min, double    max )

Obtain random double d where min <= d <= max. Since: 0.8.3 Parameters: min  Lower limit for random number. max  Upper limit for random number. Returns: Random double [min,max].

SDL_Surface * ZE::ZEngine::LoadImage (  string    filename )

Loads an Image to an ImageData class which keeps vital information on the Image. Parameters: filename  path to file to load. Returns: A SDL_Surface pointer to data.

Mix_Chunk* ZE::ZEngine::LoadSound (  string    filename )

Loads a Sound to a SoundData class which keeps vital information on the Sound Parameters: filename  path to file to load. Returns: A Mix_Chunk pointer to data.

Mix_Music* ZE::ZEngine::LoadMusic (  string    filename )

Loads a Music Clip to a MusicData class which keeps vital information on the Music Data Parameters: filename  path to file to load. Returns: A Mix_Music pointer to data.

TTF_Font* ZE::ZEngine::LoadFont (  string    filename, int    size )

Loads a Font to a FontData class which keeps vital information on the Font Parameters: filename  path to file to load. size  point size of font Returns: A TTF_Font pointer to data.

int ZE::ZEngine::Width (    )

Get Width of Window or Fullscreen mode. Returns: Width of Display.

int ZE::ZEngine::Height (    )

Get Height of Window or Fullscreen mode. Returns: Height of Display.

int ZE::ZEngine::BPP (    )

Get BPP of Window or Fullscreen mode. Returns: BPP of Display.

bool ZE::ZEngine::IsFullscreen (    )

Get Fullscreen setting of Display. Returns: True if Fullscreen, False if Windowed

---

The documentation for this class was generated from the following files:

• /include/ZE_ZEngine.h
• /src/ZE_ZEngine.cpp

---