Ogrelicious         Framework or wrapper for Ogre inspired by the many Javascript libraries, such as Scriptaculous, JQuery and Prototype
Image

This is an OgreGallery featured project

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.

Image

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);

Simple Accessors, "all", and Enums

To Access Simply

Simple Accessors
  • _None Singular
  • _First Singular
  • _Last Singular
  • _Odd Plural
  • _Even Plural
  • _Everything Plural

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();

Enums

There are some other Enums in Ogrelicious. You'll find them as you go along. You'll also find that they are used with many different classes for slightly different meanings. One of the biggest enums I want to introduce is Colours.

mViewport.background(Colours::HotPink);

As it says; It will change the background colour of that Viewport to the WebColour Hot Pink. Ogrelicious carries all of the Web Colours, accessible via the Colours namespace. Any SmartClass function that requires a colourvalue will accept an Ogrelicious Colour or an Ogre ColourValue.

The Namespace

Ogrelicious::Ogrelicious

Ogrelicious::Ogrelicious is one of the main classes. It's similar to Root, but used far less. In most cases you won't even see it. It is responsible for the management of the Optional Singleton classes such as EventSystem. It is an Ogre singleton and uses "Auto Garbage Collection" to clean up on shutdown.

To Create
Ogrelicious::init(); or startOgre(); (Will also create the Root Singleton)
To Destroy
Ogrelicious::uninit(); or stopOgre(); (Will also destroy the Root Singleton)
To Fetch

Ogrelicious::Ogrelicious* ptr = Ogrelicious::getSingletonPtr()

EventSystem

The EventSystem is an OptionalSingleton class; meaning that depending on Ogrelicious's amount of use, it may never be created. It deals with the storage of functors and firing of events within Ogrelicious. It also keeps master copies of some of the event listener classes.

To Create or To Fetch
Events::instance(); or _Events();
To Destroy

Destroy Ogrelicious::Ogrelicious


The EventSystem has a few SmartEvents to handle global events; such as frame started or ended.

Frame started
_Events()->onBeginFrame += _Callback()
Frame ended

_Events()->onBeginFrame += _Callback()

Plugins

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