Qaf Framework: qaf::Environment Class Reference

Before shutting down HGE, you should invoke Environment::shutdown() to ensure everything is cleaned up before the application exits.

Static Public Member Functions

static bool initialize (bool useBackBuffer, bool useDebug)

This must be called before any other method, as it prepares the Environment's internal variables.

static void update (float dt)

Call this once per frame to perform Qaf's game loop.

static void enableObjUpdate (bool flag)

This method is a quick shortcut to turn on or off the execution of all GameObjs' update() method and collision detection.

static bool isObjUpdateEnabled ()

Returns:: true if object updating is enabled.

static void enableRender (bool flag)

This method is a quick shortcut to turn on or off the execution of the render() method.

static bool isRenderEnabled ()

Returns:: true if rendering is enabled.

static void shutdown ()

Releases all resources used by the Environment.

static void enableBackBuffer (bool flag)

The back buffer is a render target used to store all rendered data before it is flushed to the screen.

static bool isBackBufferEnabled ()

Returns:: true if the back buffer has been enabled (that does not mean that is has been successfully created, however).

static unsigned long getBackBuffer ()

Returns:: The back buffer's texture handle (HTEXTURE).

static void setGameObjFactory (GameObjFactory *_gameObjFactory)

When a room is loaded, the game object factory is queried by the Environment to create its objects.

static GameObjFactory * getGameObjFactory ()

Returns:: The game object factory currently in use by the Environment.

static void setPrologueCallback (void(*cb)())

The prologue callback is called at the beginning of every frame cycle.

static void setEpilogueCallback (void(*cb)())

The epilogue callback is called at the end of every frame cycle.

static bool loadRoom (std::string filename)

Changes the game's loaded Room, unloading what was loaded before.

static Room * getLoadedRoom ()

Returns:: A pointer to the currently loaded Room, or NULL if no room has been loaded.

static void unloadRoom ()

Unloads the currently loaded room, deleting all volatile GameObjs.

static void setScrollingPoint (int x, int y)

This changes the "scrolling point," which represents the screen's displacement relative to the room's top-left corner.

static void moveScrollingPoint (int dx, int dy)

Parameters:

How many pixels the screen should be "nudged" horizontally

static void centerScrollingPoint (int x, int y)

Centers the screen at coordinates (x, y).

static int getScrollingX ()

Returns:: The scrolling point's X coordinate.

static int getScrollingY ()

Returns:: The scrolling point's Y coordinate.

static int getScreenWidth ()

Returns the current screen width.

static int getScreenHeight ()

Returns the current screen height.

static void addGameObj (GameObj *obj, int layer=-1, bool onTop=true)

Inserts an object into the Environment.

static int findGameObj (GameObj *obj, int *index=NULL)

Searches the Environment for the specified object.

static void removeGameObj (GameObj *obj, bool deleteIt, int srcLayer=-1)

Searches the Environment for the specified GameObj and removes it from its current layer.

static void moveGameObj (GameObj *obj, int destLayer, int srcLayer=-1)

Searches the Environment for the specified GameObj, removes it from its current layer and places it into the destination layer.

static void bringGameObjToFront (GameObj *obj, int srcLayer=-1)

Brings the object to the front of its layer.

static void sendGameObjToBack (GameObj *obj, int srcLayer=-1)

Sends the object to the back of its layer.

static int getNumberOfJoysticks ()

Returns:: The number of joysticks that are currently available.

static Joystick * getJoystick (int i)

Returns:: A pointer to the Joystick device available at index i, or NULL if an invalid index is specified.

static const BigTexture * loadBigTexture (const char *filename)

Loads a BigTexture from a file on the disk.

static void freeBigTexture (const BigTexture *tex)

Releases an allocated BigTexture.

static void setBigTextureCacheSize (int size)

Coordinates the BigTexture cache management.

template<typename T>

static ObjIterator< T > makeObjIterator ()

Allows clients to traverse the active object list.

template<typename T1, typename T2>

static void registerCollisionHandler (void(*pfHandler)(T1 *, T2 *))

Registers a collision handler between classes of objects.

Static Public Attributes

static float time

A "clock" used by the Environment to update the water level's undulation, current, and refraction.

static int frames

Similar to time, this will keep track of how many frames were rendered.

static DebugConsole cout

static Container< DebugVector > debugVectors

Add DebugVectors here.

Classes

class AbstractCollisionHandler

class AbstractObjDiscriminator

class CollisionHandler

class DebugConsole

The debug console is useful for outputting data to the screen. More...

class ObjDiscriminator

Member Function Documentation

static bool qaf::Environment::initialize	(	bool	useBackBuffer,
		bool	useDebug
	)			`[static]`

This must be called before any other method, as it prepares the Environment's internal variables.

Parameters:

	useBackBuffer	Whether the game should use a buffer before flushing to the screen. See `enableBackBuffer()` for details.
	useDebug	Passing true here will enable the `DebugConsole` and `DebugVector`s. The debug resources incur a slight overhead, so you might want to disable them for the game's final version.

Returns:: false if there was a problem during initialization. Use hge->System_GetErrorMessage() to get a description of the error.

static void qaf::Environment::update ( float dt ) [static]

Call this once per frame to perform Qaf's game loop.

This will check collisions, update the GameObjs, perform all rendering operations, and call the prologue/epilogue functions.

Usually, you will place this in HGE's frame function.

static void qaf::Environment::enableObjUpdate ( bool flag ) [static]

This method is a quick shortcut to turn on or off the execution of all GameObjs' update() method and collision detection.

See also:: GameObj::update()

static bool qaf::Environment::isObjUpdateEnabled ( ) [static]

Returns:: true if object updating is enabled.

See also:: enableObjUpdate()

static void qaf::Environment::enableRender ( bool flag ) [static]

This method is a quick shortcut to turn on or off the execution of the render() method.

In short, setting this flag to false will halt all rendering operations (both GameObj- and BGLayer-related), and the only rendering that could possibly take place would be in the prologue/epilogue callbacks.

See also:: GameObj::render()

static bool qaf::Environment::isRenderEnabled ( ) [static]

Returns:: true if rendering is enabled.

See also:: enableRender()

static void qaf::Environment::shutdown ( ) [static]

Releases all resources used by the Environment.

This method unloads textures, the loaded room, and deletes any GameObjs still active.

This method should only be invoked after stopping HGE's game loop (i.e., when System_Start() returns), and not during game execution.

See also:: initialize(), update()

static void qaf::Environment::enableBackBuffer ( bool flag ) [static]

The back buffer is a render target used to store all rendered data before it is flushed to the screen.

This buffer is necessary for the underwater distortion effect, and may be used by the developer to create sophisticated visual effects.

The back buffer's dimensions are limited by the video card's maximum texture size; also, transferring data from this buffer to the screen may incur a heavy performance penalty. Thus, it is possible to disable the back buffer if performance or compatibility issues require it.

See also:: isBackBufferEnabled(), getBackBuffer()

static bool qaf::Environment::isBackBufferEnabled ( ) [static]

Returns:: true if the back buffer has been enabled (that does not mean that is has been successfully created, however).

See also:: enableBackBuffer(), getBackBuffer()

static unsigned long qaf::Environment::getBackBuffer ( ) [static]

Returns:: The back buffer's texture handle (HTEXTURE).

This texture stores the Environment's rendered data (background layers and GameObjs). If the back buffer has been disabled or could not be created, returns NULL.

See also:: enableBackBuffer(), isBackBufferEnabled()

static void qaf::Environment::setGameObjFactory ( GameObjFactory * _gameObjFactory ) [static]

When a room is loaded, the game object factory is queried by the Environment to create its objects.

Setting this pointer to NULL will turn off object creation.

static GameObjFactory* qaf::Environment::getGameObjFactory ( ) [static]

Returns:: The game object factory currently in use by the Environment.

See also:: setGameObjFactory()

static void qaf::Environment::setPrologueCallback ( void(*)() cb ) [static]

The prologue callback is called at the beginning of every frame cycle.

Its prototype must be:

 void prologueCB ();

It will be called each frame, after rendering starts (i.e., after hge->Gfx_BeginScene()). Anything rendered here will appear beneath all BG layers and game objects. If you need to clear the screen or apply scene-wide transformations, do those in the prologue function.

See also:: setEpilogueCallback()

static void qaf::Environment::setEpilogueCallback ( void(*)() cb ) [static]

The epilogue callback is called at the end of every frame cycle.

Its prototype must be:

 void epilogueCB ();

It will be called after all rendering has been performed in each frame, but before hge->Gfx_EndScene(). Thus, it is safe to perform rendering operations here. They will appear in front of everything else; this is a good place to render on-screen status bars, menus, etc.

See also:: setPrologueCallback()

static bool qaf::Environment::loadRoom ( std::string filename ) [static]

Changes the game's loaded Room, unloading what was loaded before.

The file must be a valid encoded room file, created with Qaf's Room Editor. If an error is found, the method returns false and the environment is left unchanged.

Loading a room will automatically trigger the unloadRoom() method; thus, all volatile GameObjs will be deleted. The new room's objects are extracted from the room file, and their data is forwarded to the current GameObjFactory.

Returns:: false if the file could not be loaded or it is not a valid Qaf room file.

Note:: This operation is not executed immediately. It will be kept in a buffer, and the actual loading will only take place at the end of the frame cycle.

See also:: unloadRoom(), setGameObjFactory()

static void qaf::Environment::unloadRoom ( ) [static]

Unloads the currently loaded room, deleting all volatile GameObjs.

At the end of the operation, the Environment will contain a single empty object layer.

Note:: This operation is not executed immediately. It will be kept in a buffer, and the actual unloading will only take place in the next frame.

See also:: loadRoom(), GameObj::isVolatile()

static void qaf::Environment::setScrollingPoint	(	int	x,
		int	y
	)			`[static]`

This changes the "scrolling point," which represents the screen's displacement relative to the room's top-left corner.

The method will automatically clamp the coordinates, preventing the screen from "exiting" the loaded room's area.

See also:: moveScrollingPoint(), centerScrollingPoint(), getScrollingX(), getScrollingY()

static void qaf::Environment::moveScrollingPoint	(	int	dx,
		int	dy
	)			`[static]`

Parameters:

How many pixels the screen should be "nudged" horizontally

Parameters:

How many pixels the screen should be "nudged" vertically

See also:: setScrollingPoint(), centerScrollingPoint()

static void qaf::Environment::centerScrollingPoint	(	int	x,
		int	y
	)			`[static]`

Centers the screen at coordinates (x, y).

This is the same as calling

 setScrollingPoint( x - screenWidth/2, y - screenHeight/2 );

where screenWidth and screenHeight are extracted from the currently loaded room.

This method does nothing if there is no loaded room.

See also:: setScrollingPoint(), moveScrollingPoint()

static int qaf::Environment::getScrollingX ( ) [static]

Returns:: The scrolling point's X coordinate.

See also:: setScrollingPoint(), getScrollingY()

static int qaf::Environment::getScrollingY ( ) [static]

Returns:: The scrolling point's Y coordinate.

See also:: setScrollingPoint(), getScrollingX()

static int qaf::Environment::getScreenWidth ( ) [static]

Returns the current screen width.

If there is a loaded room, the room's screen width (in pixels) is returned. Otherwise, the window's screen width is returned by consulting the HGE_SCREENWIDTH system state.

static int qaf::Environment::getScreenHeight ( ) [static]

Returns the current screen height.

If there is a loaded room, the room's screen height (in pixels) is returned. Otherwise, the window's screen height is returned by consulting the HGE_SCREENHEIGHT system state.

static void qaf::Environment::addGameObj	(	GameObj *	obj,
		int	layer = `-1`,
		bool	onTop = `true`
	)			`[static]`

Inserts an object into the Environment.

If no layer is specified, the loaded room's default layer is used.

If onTop is true, the object will be inserted at the frontmost position in the layer.

This operation is buffered, and its effects will only be visible in the next frame.

The object's initialize() method will not be called.

See also:: Room::defaultObjLayer, removeGameObj(), moveGameObj()

static int qaf::Environment::findGameObj	(	GameObj *	obj,
		int *	index = `NULL`
	)			`[static]`

Searches the Environment for the specified object.

If it is found, this method returns its layer, and stores the object's index in the index pointer. (Keep in mind that each layer is a list of objects; objects that are at the front of the layer will have lower indices, and objects that are at the back will have higher indices.)

If the object is not found, the method returns -1, and the index pointer is left unchanged.

If you don't care about the object's intra-layer position, use index = NULL.

Returns:: The layer where the object currently resides, or -1 if the object is not found.

static void qaf::Environment::removeGameObj	(	GameObj *	obj,
		bool	deleteIt,
		int	srcLayer = `-1`
	)			`[static]`

Searches the Environment for the specified GameObj and removes it from its current layer.

If the deleteIt parameter is true, the object will also be deleted.

If a valid source layer is specified, it is used to trim down the search. (If you already know which layer the object is in, you can get a performance boost by telling the Environment where to look. Rather than inspecting all the layers, only srcLayer is searched.)

This operation is buffered, and its effects will only be "visible" in the next frame. (This includes the object's deletion.)

See also:: addGameObj(), moveGameObj()

static void qaf::Environment::moveGameObj	(	GameObj *	obj,
		int	destLayer,
		int	srcLayer = `-1`
	)			`[static]`

Searches the Environment for the specified GameObj, removes it from its current layer and places it into the destination layer.

The object will be at the frontmost position in that layer.

If destLayer is not a valid layer index, the object will be inserted in the loaded room's default object layer.

This operation is buffered, and its effects will only be "visible" in the next frame.

See also:: addGameObj(), removeGameObj()

static void qaf::Environment::bringGameObjToFront	(	GameObj *	obj,
		int	srcLayer = `-1`
	)			`[static]`

Brings the object to the front of its layer.

The object will be updated and rendered after all others in its layer. Thus, it will appear "on top" of everything.

This does not move the object to another layer. It simply changes its position in-layer.

This operation is buffered, and its effects are not immediately visible.

See also:: sendGameObjToBack(), moveGameObj()

static void qaf::Environment::sendGameObjToBack	(	GameObj *	obj,
		int	srcLayer = `-1`
	)			`[static]`

Sends the object to the back of its layer.

The object will be updated and rendered before all others in its layer. Thus, it will appear "below" everything.

This does not move the object to another layer. It simply changes its position in-layer.

This operation is buffered, and its effects are not immediately visible.

See also:: bringGameObjToFront(), moveGameObj()

static int qaf::Environment::getNumberOfJoysticks ( ) [static]

Returns:: The number of joysticks that are currently available.

See also:: getJoystick()

static Joystick* qaf::Environment::getJoystick ( int i ) [static]

Returns:: A pointer to the Joystick device available at index i, or NULL if an invalid index is specified.

See also:: getNumberOfJoysticks()

static const BigTexture* qaf::Environment::loadBigTexture ( const char * filename ) [static]

Loads a BigTexture from a file on the disk.

The Environment maintains a cache of loaded textures, so as to avoid the duplication of these objects. If the texture has already been loaded, a pointer to it will be returned instead of creating a new texture.

Do not delete this pointer. When you no longer need the texture, release it by calling Environment::freeBigTexture().

See also:: Environment::freeBigTexture(), Environment::setBigTextureCacheSize()

static void qaf::Environment::freeBigTexture ( const BigTexture * tex ) [static]

Releases an allocated BigTexture.

The texture must have been loaded with the Environment::loadBigTexture() method. The texture's reference counter will be decremented, but it will not be removed immediately.

See also:: Environment::loadBigTexture(), Environment::setBigTextureCacheSize()

static void qaf::Environment::setBigTextureCacheSize ( int size ) [static]

Coordinates the BigTexture cache management.

When a BigTexture's reference counter reaches zero, it is not deleted immediately, but is kept in the cache until all slots have been filled.

When a new texture is requested with loadBigTexture(), the least-recently-freed texture will be deleted to make room for the new object.

You can control how many slots are available in the cache with this method. The default initial value is 7.

If size is less or equal to zero, the method does nothing.

template<typename T>

static ObjIterator<T> qaf::Environment::makeObjIterator ( ) [inline, static]

Allows clients to traverse the active object list.

Warning:: If you need to iterate over the object list, get a new iterator every frame.

See also:: ObjIterator

template<typename T1, typename T2>

static void qaf::Environment::registerCollisionHandler ( void(*)(T1 *, T2 *) pfHandler ) [inline, static]

Registers a collision handler between classes of objects.

In the template's two typenames, you specify two subclasses of GameObj to test for collisions. Every frame, all active instances of these two classes will be tested against each other for collisions, and the handler function will be invoked.

For instance, let's say you have created the classes PlayerObj and EnemyObj, both subclasses of GameObj:

    // This is the collision handler. It will be called every time the
    // player touches an enemy.
    void handler_PlayerEnemy ( PlayerObj * p, EnemyObj * e ) {
        // Get the enemy's damage strength:
        int enemyDamage = e->getDamageStrength();
        
        // "Hurt" the player:
        p->decreaseHP( enemyDamage );
    };

    // Now, somewhere in main()...
    // Tell the environment that collisions between PlayerObj and
    // EnemyObj are handled by the handler_PlayerEnemy function:
    Environment::registerCollisionHandler<PlayerObj, EnemyObj> ( handler_PlayerEnemy );

Parameters:

pfHandler

The handler function to be invoked when a collision occurs. It will receive the two colliding objects as its two parameters.

Member Data Documentation

float qaf::Environment::time [static]

A "clock" used by the Environment to update the water level's undulation, current, and refraction.

This value is kept consistent with the dt parameter supplied to update().

This field may be modified at will; for instance, you could reset the Environment time by setting time = 0.

Container<DebugVector> qaf::Environment::debugVectors [static]

Add DebugVectors here.

This container will be checked at the end of every frame, and its contents will be rendered as described in the DebugVector class.

Once that's done, the container will be automatically emptied in preparation for the next frame.

See also:: DebugVector

Note:: DebugVectors are only available if you initialize the Environment with useDebug set to true.

qaf::Environment Class Reference

Detailed Description

Static Public Member Functions

Static Public Attributes

Classes

Member Function Documentation

Member Data Documentation