Application Subsystem

Detailed Description

This section of the documentation covers Nebula application system and its subsystems.

What is the purpose of nApplication?

nApplication is a base Nebula Device application. It is not complete in itself and you will have to derive your own class from nApplication to write your application. nApplication shows proper set up and shut down of all the core nebula systems and operates on the idea of game states.

You can think of nApplication as the core engine loop manager

What is the purpose of nAppState?

Your game can be thought of as a large state machine, where states might be

play intro movie
show main menu
in the actual game
play exit movie
show credits

and of course anything else you can think of.

When a state is active, nApplication will give it a chance to render its own 3D environment, and 2D environment and handle any input.

nApplication lets you set up and switch to different states in your game.

like nApplication, you will have to derive your own game state classes from nAppState. There are a couple example states you can use included in the Application Subsystem

nAppState class has serveral virtual functions for its member functions and one should appropriately override these functions in one's own derived class.

The login and rendering part are separately implemented in nAppState derived class.

You should put logic part of the state to nAppState::OnFrame() overrided function and rendering part to nAppState::OnRender3D() overried function if the rendering stuffs are for 3D scene or nAppState::OnRender2D() overrided function which for 2D rendering stuffs like GUI rendering.

How do I handle States in an application?

nApplication supports several member functions for handling states like creation, finding, transition and so on.

Call nApplication::CreateState() for the creation of the state.

    nCutSceneAppState* stateCutScene = (nCutSceneAppState*)CreateState("ncutsceneappstate", "cutscene");

Note:

Be sure that pass the state name without any path for the second parameter of nApplication::CreateState(). nApplication has the pass, 'appstate' and put any created states under that path. Putting any path in front of the state name will be error.

// error! don't use the path '/myappstates/' but use only "cutscene" without slash.
CreateState("ncutsceneappstate", "/myappstates/cutscene");

Created state can be found with calling of nApplication::FindState() function.

    nAppState* stateCutScene = FindState("/game/states/cutscene");

You can change the state by calling nApplication::SetState() member function with given state name for its parameter. Once the state is specified by nApplication::SetState(), current state will be changed to the specified state when nApplication::DoStateTransition() is called in game loop.

    SetState("exit");

Note:: Be sure that pass only the state name for the parameter of nApplication:SetState() like the second parameter of nApplication::CreateState().

How to I create an nApplication derived class?

Using nApplication for you own application framework is simple. All you need to do is creating your own nApplication derived class instance then call

Open
Run
Close

as shown on below example code snipset:

    int main ()
    {
        ...   
        nKerenelServer* kernelServer = new nKernelServer;
        nMyApp* myApp = (nMyApp*)kernelServer->New("nmyapp","/app/myapp")

        // you may need some other initializations before calling Open()
        // like specifying display mode, company name, application name and 
        // startup script filename and so on.
        myApp->SetDisplayMode(disp);
        ...
        myApp->SetStartupScript(startupScript);

        if(myApp->Open())
        {
            myApp->Run();
        }

        myApp->Close();
        myApp->Release();

        return 0;
    }

You should specify your oown nApplication derived class and may need to override nApplication::Open() function for specifying your application states and some other initializations for your application.

    class nMyApp : public nApplication
    {
    public:
        virtual bool Open();
        ...

    protected:
        // user created nAppState derived
        nMenuState*     menuState;
        nGameState*     gameState;
        nCutSceneState* exitState;
        ...
    };

Application Initialization

The most important thing you should do in your own nApplication::Open() overrieded function is creating application states which you aleady created by deriving it from nAppState and specifying it to your application.

    bool nMyApp::Open()
    {
        nApplication::Open();

        // create states.
        this->menuState = (nMenuState*)this->CreateState("nmenustate", "menu");
        this->gameState = (nGameState*)this->CreateState("ngamestate", "game");
        this->exitState = (nExitState*)this->CreateState("nexitstate", "exit");

        // we specify the first state by menu state.
        this->SetState("menu");
        ...
    }

There are three nAppState derived class instances which were created on above code example. You can create states as many as you want then should specify a one of the states to the application with given name of the state, it will be the first state which is shown on screen.

When nApplication::Open() is called, it runs startup script file if that is specified by calling nApplication::SetStartupScript() and run predefined script if those are found in the script. Followings are those predefined script functions:

OnStartup
OnGraphicsStartup
OnMapInput

You can run any script you want to by putting those in the above script function.

Application Game Loop

There are three member functions those you might want to override for game loop.

Override OnFrame() and put the logic stuff of the state. OnRedner3D() and OnRender2D() is for rendering of the state as its name represents. Put any code of 3D rendering stuff on OnRender3D() and 2D rendering stuff on OnRender2D().

Rendering Loops

There are two seperated rendering phases, 'Render3D' and 'Render2D' in nApplication rendering loop. The following is description of the two rendering phases.

Render3d actually means "scene rendering" - in fact, "scene attaching", because the operation that is performed in this phase is attaching node hierarchies to the scene graph (scene server) system. These are rendered using a render path and operations are encapsulated in scene nodes, as you have done. The important thing with this rendering loop is that it happens between a pair of nSceneServer::BeginScene and nSceneServer::EndScene calls.
After the scene rendering loop (the "Render3d") phase has finished, the gfxServer is guaranteed to remain in a state that allows additional rendering, before the frame buffer contents are swapped to the screen. This phase is called Render2D in the application loop because it's common to perform 2d rendering. But if you want to perform some 3d (debug or otherwise) rendering by yourself (that is, outside the scene graph), this is the place to do it.

Shutting Down nApplication

nApplication::Close() is called when the application is shutdown. Override nApplication::Close() and drop any necessary lines on there.


Classes
class	nAppCamera
	A simple application camera object. Derive subclasses if you need more advanced camera behaviour. More...
class	nApplication
	A simple application wrapper class. Derive a subclass for a specialized application. More...
class	nAppState
	An application state. Application states completely control application behaviour and rendering when they are active. More...
class	nAudioObject
	A wrapper object for Nebula2 sounds. More...
class	nCutSceneAppState
	An application state which will playback a video and then proceed to the next configured application state. More...
class	nExitAppState
	This app state will simply ask the application to quit. More...
class	nGfxObject
	A wrapper object for loading and rendering a Nebula2 graphics object. More...

Documentation

Links