Ogrelicious

Framework and wrapper for Ogre

• License MIT
• Status 0.0.7 First Release
• Dependencies Ogre 1.4+
• Latest Version Source Demo
• Instructions This page
• Support Release Thread
• Lead Developer Betajaen (Ogre Expert User)
• Start Date 29-November-2008

What is it?

Ogrelicious is a framework or wrapper (depending on how much you use it) for Ogre. It carries much of the philosophy and syntax of the many Javascript libraries (Scriptaculous, JQuery and Prototype) and applies it to Ogre. Pieces of code that may of been written in the past that would of taken many lines of code, can now be done in just one or two.

An example

In the fairly simple example; It displays an Ogre window with a tomato background, with a larger forest green Ogre in the foreground whilst in the background smaller crimson coloured ogres in a pattern

#include "Ogrelicious.h"

class App
{

public:

App()
{

mRoot = startOgre();
_Plugins("RenderSystem: Direct3D9, Plugin_ParticleFX_d.dll").load(_Everything);
_RenderSystems("all").nominate(_First);

initialiseOgre(_NoAutoWindow);

mWindow = _Window("Ogrelicious, yummy!")

.left(_HorizontallyCenter)
.top(_VerticallyCenter)
.width(1024)
.height(768)
.depth(32)
.fullscreen(false);

mWindow.create();
mWindow.onUnload += _Callback(&::Ogrelicious::Ogrelicious::SafeShutdown);

mSceneMgr = mRoot->createSceneManager(Ogre::ST_GENERIC, "Main");
mCamera = _Camera("Camera1", mSceneMgr).farClip(5).nearClip(5000).position(10,10,10).look(0,0,0);
mViewport = mWindow.add(mCamera).background(Colours::IndianRed);

_ResourceGroup("General") += "../../../Media/packs/#?,../../../Media/materials/#?,../../../Media/models/";
_ResourceGroups("all").init(_Everything);
mViewport.background(Colours::Tomato);

_Material("ForestGreen").ambient(Colours::ForestGreen);
_Material("Crimson").ambient(Colours::Crimson);

_Node("Ogre", mSceneMgr).scale(0.2,0.2,0.2).entity("ogrehead.mesh")->setMaterialName("ForestGreen");

SmartNode root = _Node("root", mSceneMgr);
int i = 0;
for(int x=0;x < 6;x++)

for(int y=0;y < 6;y++)

root.add(i++).position(20 - x * 10, 20 - y * 10, -25).scale(0.05,0.05,0.05).entity("ogrehead.mesh")->setMaterialName("Crimson");

mRoot->startRendering();

}

~App()
{

stopOgre();

}

protected:

Ogre::Root* mRoot;
Ogre::SceneManager* mSceneMgr;
SmartWindow mWindow;
SmartCamera mCamera;
SmartViewport mViewport;

};

Download and Compile

Ogrelicious comes in two files; Ogrelicious.h and Ogrelicious.cpp, as Ogrelicious is under the MIT licence; you may copy them into your project files use it with no restrictions.

To simply access the Ogrelicious classes, just use the include pre-processor directive.

#include "Ogrelicious.h"

Ogrelicious only requires Ogre as an dependency, but does make use of the Operating Systems functions. For this some functions of Ogrelicious may not be available for certain operating systems.

You should be able to use C++ properly and familiar with most of Ogre.

Demo_Ogrelicious.exe

Demo Ogrelicious is a small application to demonstrate Ogrelicious, as well as work as a small sandbox for development and testing. It is supplied as a Visual Studio project (but can be easily converted to other IDEs and platforms). Once compiled you will find it in your Ogre debug or release samples folder named "Demo_Ogrelicious.exe"

Structure and Basics

SmartClasses

Classes in Ogrelicious that represent an Ogre class are called SmartClasses. They come in two forms; Plural and Singular. Plural classes represent a bunch of Singular SmartClasses. They can be gathered together using a comma separated string accessor, nearly all of the functions of a Singular SmartClass can be applied as a group to through a Plural Smart Class.

SmartWindows windows("Window1, Window2, Window3").left(50);

SmartClasses support chaining of functions, and nearly all are both a set and get type functions.

SmartWindow("Window3").left(100).top(80);
int top = SmartWindow("Window03").top();

SmartClasses are not pointers, they can be passed around as you like. They operate like SharedPointers, and can come back in your deepest function you have.

SmartWindow w1("Window1");
SmartWindow w2("Window1");
(*w1) == (*w2); // True!

SmartClasses use names to get things and use names to create things.

SmartWindow("Window1");// Old!
SmartWindow w5("Window5");// New!

SmartClasses can be used temporarily; without variables or names. They are temporarily because they have underscore, no longer smart and don't be expected to be used more than once.

_Plugins("RenderSystem: Direct3D9, RenderSystem_GL.dll, Plugin_PCZSceneManager.dll, Plugin: ParticleFX").load();

SmartClasses are your Ogre classes in disguise.

SmartWindow w5("Window5");
w5->getName();
(*w5)->getName();

Smart Events

Everything is smart in Ogrelicious including Events. If you want something watched or need to be carried out, you use a SmartEvent.

_Events().onFrameBegin += _Callback(myClass, &MyClass::NewFramePeopleLetsGetBusy);

Of course, Events are Smart so they can be more focused.

SmartWindow MrTiddles("Mr Tiddles").onLoad += _Callback(myClass, &MyClass::AwwwMrTiddlesHasLoadedAwww);

Of course, Focused Events aren't really that smart. You still need to keep a copy of Mr Tiddles handy.

class MyClass
{
 public:
  void LoadingMrTiddles()
  {
    mMrTiddles("Mr Tiddles").onLoad += _Callback(myClass, &MyClass::AwwwMrTiddlesHasLoadedAwww);
  }
  SmartWindow mMrTiddles;
};

Functions

Although Ogrelicious can be used as much or as little as possible. Most of the time all the singletons and support classes start up in the background as you use them. But there are some cases when you need them early.

mRoot = new Root("","","ogre.log");
Ogrelicious::Ogrelicious::init();

Or if you want it a bit neater

mRoot = startOgre()

Ogrelicious will close down and try and clean up all of it's support classes. It is known as "Auto Garbage Collection", you will not have to do anything about that. However; you can trigger it early.

delete mRoot;
Ogrelicious::Ogrelicious::uninit();

Which is the same as

stopOgre()

When you want to initialise Ogre; to create an Window or start up the RenderSystem, normally you would do.

mRoot->initialise(false);

But you can do this instead; if you wanted.

initialiseOgre(_NoAutoWindow);

To Access Simply

To access things normally or in many in SmartClasses and throughout Ogrelicious we have SimpleAccessors, not SmartAccessors - SimpleAccessors. Basically; it's an enum with lots of support functions. You've already seen _Everything and _First, those are two SimpleAccessors shown here:

_Plugins("RenderSystem: Direct3D9, Plugin_ParticleFX_d.dll").load(_Everything);
_RenderSystems("all").nominate(_First);

The function SmartPlugins::load(_Everything) means "for every plugin I have load them" and the function SmartRenderSystem::nominate(_First) means "for every RenderSystem I have, nominate the first one only".
As you can see; SmartClasses like SmartPlugins or SmartRenderSystems use SimpleAccessors to apply a filter to it's copy of SmartPlugin and SmartRenderSystem classes functions. This is true for most plural SmartClasses.

All

You've already seen "all" but probably never thought anything about it. All is only used in Plural SmartClasses when you need to look up for something in Ogre. Normally this would be the case of a single item "myWindow" or many items "myWindow, myWindow1". All is used when you want all of them.

_RenderSystems("all").describe();

The Namespace

Ogrelicious::Ogrelicious

EventSystem

Plugins

SmartPlugin(s) represent the Ogre::Plugin class and abstractly the RenderSystem and Plugin shared libraries.