Wartbed:Manual/Booting and shutting down WARTBED

From Dark Omen Wiki

Jump to: navigation, search


Contents

Prerequisites

Required 3rd party middleware for development
Note that if you are compiling OGRE from source on Windows, you will need the DirectX 9.0c or later SDK rather than just the DX runtimes installed.

  • The OGRE 3D v1.6 "Shoggoth" API
    • OpenGL
    • DirectX 9.0c or later
  • OIS 1.2 or later
  • CEGUI 0.6

Paths and libraries
WARTBED is currently intended to be distributed as headers and static libraries, to be released as FOSS later on in development. To develop an application using the WARTBED framework, in a new project you need to:

  • Add the WARTBED headers path to your include directories
  • Add the WARTBED dependencies path to your include directories
  • Add the bin or bin_d path to your library directories
  • Link to the Wartbed.lib or Wartbed_d.lib static library 
// A MSVC compiler (non-portable) way of linking to the WARTBED library
#ifdef _DEBUG
    #pragma comment(lib, "Wartbed_d.lib")
#else
    #pragma comment(lib, "Wartbed.lib")
#endif

Booting the system

To initialise WARTBED you call the static createInstance method of the Wartbed singleton class. The parameter is the name of the application, and will among other places be written in the caption of the application window. If you do not provide a caption parameter, a default string will be used. 

#include <Wartbed.h>
 
int main()
{
    Wartbed &rWB = Wartbed::createInstance( "My WARTBED App Name" );
}

You can store the returned object reference for quick access, or you can obtain a reference to the Warbed object at any time after initialisation from the singleton's getSingelton method. For consistency of nomenclature, WARTBED follows OGRE 3D's naming convention of calling the singleton access method "getSingleton". WARTBED does however not provide the getSingletonPtr method. 

Wartbed &wartbed = Wartbed::getSingleton();

Listeners, Input Bindings and Event Managers

OGRE and WARTBED uses listener objects to capture and respond to user input. The raw input is then promulgated to event managers and/or the GUI system for handling. Gnererally, WARTBED creates the appropriate or sufficient listener objects by default.

There are three principal listener objects that governs application execution. Two are input listeners, MouseListener and KeyboardListener, and the final, FrameListener, monitors OGRE's update cycle. When WARTBED is booted, default input and frame listeners are provided. If WARTBED's input event system is initialised, input listeners integrated with the input event system replace the defaults. Likewise, if the GUI system is initialised, composite input listeners for both input and gui events are set - the GUI system requires the input event system.

Input events are triggered when a key or mouse combination specified in the key bindings section of the configuration file is performed. This event is sent to the event manager function. If no event manager is provided the WARTBED default one is used. Specialised event managers should forward to the default event manager function if it hasn't handled the event. Event though facilities for manually changing input listeners are provided, there should seldom, if ever, be any reason to replace those provided automatically.

Listeners are created by kernel calls:
  • When OGRE is initialised through ogre::BootSystem() basic inert listeners are created. These are unresponsive and cause no events. A user of the WARTBED framework would rarely directly call this kernel function.
  • When CEGUI is initialised through ogre::InitialiseCEGUI() wb::gui::KeyListener and wb::gui::MouseListener objects are created. These objects forward raw input into the GUI system. A user of the WARTBED framework would rarely directly call this kernel function.
Listeners are created by user calls:
  • When the Wartbed object is created (first time Wartbed::createInstance() is called) basic wb::KeyListener and wb::MouseListener (which are aliases for wb::input::KeyListener and wb::input::MouseListener) are created. These listeners cause WARTBED input events but are unconcerned with the GUI.
  • When the GUI is initialised through Wartbed::initialiseGUI() (or when the Wartbed::GUI singleton is first created) default listeners inheriting from both input::{Keyboard,Mouse}Listener and gui::{Keyboard,Mouse}Listener are created.

If the default listeners are insufficient, specialisations must be defined and provided by the client application. 

namespace myapp
{
    // Forward definitions
    void ExecuteEvent( wb::input::MAPPING const &event, long data );
    struct FrameListener;
}
 
void someFunc()
{
    wartbed.setEventManager( myapp::ExecuteEvent );
    wartbed.setFrameListener( FRAMELISTENER_PTR(new myapp::FrameListener) );
    wartbed.readInputBindings( "../cfg/application.config" );
}

GUI and the Tableau

Stub 

void SomeFunc()
{
    wartbed.initialiseGUI();
}

Resources

Stub. Currently using OGRE's resource management system. These low-level details will be hidden from sight. Currently all folders and archives to be used must be provided and initialised. 

void SomeFunc()
{
    ADD_RESOURCE_LOCATION( "./ogre example skybox.zip", "Zip" );
    ADD_RESOURCE_LOCATION( "./Fonts", "FileSystem" );
 
    // This will be moved into the Wartbed class
    Ogre::ResourceGroupManager::getSingleton().initialiseAllResourceGroups();
}

Running the App

An WARTBED application is a loop, preferably updated from a provided frame listener. If so, when resources are loaded, running is merely a question of engaging the auto pilot by invoking the mainLoop method: 

wartbed.mainLoop();

The application will run until an event named "quit" event is encountered.

Shutting down

Send the message "quit" to the event manager. By default, a "quit" event is mapped to the ESCAPE button. Deallocation of all resources allocated within the framework or by using framework methods is taken care of automatically.

Retrieved from "http://wiki.dark-omen.org/do/Wartbed:Manual/Booting_and_shutting_down_WARTBED"
Personal tools
communication