OGRE  1.12.2
Object-Oriented Graphics Rendering Engine
Setting up an OGRE project
Note
see Guide to building OGRE for instructions how to build OGRE itself

CMake Configuration

Ogre uses CMake as its build system. It is recommended that you use it in your project as well.
Then all you need is to add the following lines to your project

# specify which version and components you need
find_package(OGRE 1.11 REQUIRED COMPONENTS Bites RTShaderSystem)
# copy resource.cfg next to our binaries where OGRE looks for it
file(COPY ${OGRE_CONFIG_DIR}/resources.cfg DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
# add the source files as usual
add_executable(0_Bootstrap Bootstrap.cpp)
# this also sets the includes and pulls third party dependencies
target_link_libraries(0_Bootstrap OgreBites OgreRTShaderSystem)

These settings already include any third party libraries the Components depends on (e.g. SDL) - nothing more to do. Alternatively use ${OGRE_LIBRARIES} to link against all available OGRE components.

If you installed OGRE in a non-standard path, you will have to set OGRE_DIR to the location of OGREConfig.cmake so find_package can figure out the rest.

For inspecting the detected OGRE installation, the following CMake variables are available

  • OGRE_STATIC - whether ogre was build as static lib
  • OGRE_${COMPONENT}_FOUND - ${COMPONENT} is available
  • OGRE_PLUGIN_DIR - The directory where the OGRE plugins are located
  • OGRE_MEDIA_DIR - The directory where the OGRE sample media is located
  • OGRE_CONFIG_DIR - The directory where the OGRE config files are located

Application skeleton

The easiest way to get started is the OgreBites Component. It handles Ogre startup/ tear down (including Ogre::Overlay, RTSS), input using SDL2 and even includes a Simple GUI System.

This is useful if all you want is to get a Scene with a FPS counter up and running (rapid prototyping). If available it also uses SDL2 for input - you now just have to implement the callbacks.

To use it, simply derive from OgreBites::ApplicationContext and if you want to get input events from OgreBites::InputListener

{
...
}

in the constructor we set our application name. The ogre configuration files will be stored in a system dependant location specific to our app.

MyTestApp::MyTestApp() : OgreBites::ApplicationContext("OgreTutorialApp")
{
}

to handle input events, we then override the according method

bool MyTestApp::keyPressed(const OgreBites::KeyboardEvent& evt)
{
{
getRoot()->queueEndRendering();
}
return true;
}

the interesting part however is the setup method

void MyTestApp::setup(void)
{
// do not forget to call the base first
// register for input events
addInputListener(this);
// get a pointer to the already created root
Ogre::Root* root = getRoot();
// register our scene with the RTSS
shadergen->addSceneManager(scnMgr);
// without light we would just get a black screen
Ogre::Light* light = scnMgr->createLight("MainLight");
lightNode->setPosition(0, 10, 15);
lightNode->attachObject(light);
// also need to tell where we are
camNode->setPosition(0, 0, 15);
// create the camera
Ogre::Camera* cam = scnMgr->createCamera("myCam");
cam->setNearClipDistance(5); // specific to this sample
cam->setAutoAspectRatio(true);
camNode->attachObject(cam);
// and tell it to render into the main window
getRenderWindow()->addViewport(cam);
// finally something to render
Ogre::Entity* ent = scnMgr->createEntity("Sinbad.mesh");
node->attachObject(ent);
}
Note
The above code is explained in detail in Your First Scene.

finally we start everything as

int main(int argc, char *argv[])
{
MyTestApp app;
app.initApp();
app.getRoot()->startRendering();
app.closeApp();
return 0;
}
Note
You can find the full code of the above example at
  • Samples/Tutorials/Bootstrap.cpp for C++
  • Samples/Python/bites_sample.py for Python
  • Samples/AndroidJNI/MainActivity.java for Java (Android)

OgreBites itself is also a good starting point if you need more control over the Camera or the Window creation. For instance to render into an existing Qt Window.

See also
Ogre::FileSystemLayer::getConfigFilePath
Ogre::Root::renderOneFrame
Ogre::RenderSystem::_createRenderWindow
Ogre::RenderSystem::preExtraThreadsStarted

Running your App

On Linux you will typically install OGRE into /usr/local/ which is automatically searched by the linker, so nothing more to do. On Windows however, you will have to either add the sdk/bin folder to PATH or copy your executable into sdk/bin.

Ogre::SceneNode::createChildSceneNode
virtual SceneNode * createChildSceneNode(const Vector3 &translate=Vector3::ZERO, const Quaternion &rotate=Quaternion::IDENTITY)
Creates an unnamed new SceneNode as a child of this node.
Ogre::SceneManager::createCamera
virtual Camera * createCamera(const String &name)
Creates a camera to be managed by this scene manager.
Ogre::Entity
Defines an instance of a discrete, movable object based on a Mesh.
Definition: OgreEntity.h:79
Ogre::SceneManager::createEntity
Entity * createEntity(const String &entityName, const String &meshName, const String &groupName=ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME)
Create an Entity (instance of a discrete mesh).
Ogre::Light
Representation of a dynamic light source in the scene.
Definition: OgreLight.h:70
OgreBites
Definition: OgreAdvancedRenderControls.h:41
Ogre::Frustum::setNearClipDistance
void setNearClipDistance(Real nearDist)
Sets the position of the near clipping plane.
Ogre::SceneManager
Manages the organisation and rendering of a 'scene' i.e.
Definition: OgreSceneManager.h:157
Ogre::Root
The root class of the Ogre system.
Definition: OgreRoot.h:65
Ogre::RTShader::ShaderGenerator::addSceneManager
void addSceneManager(SceneManager *sceneMgr)
Add a scene manager to the shader generator scene managers list.
Ogre::SceneNode::lookAt
void lookAt(const Vector3 &targetPoint, TransformSpace relativeTo, const Vector3 &localDirectionVector=Vector3::NEGATIVE_UNIT_Z)
Points the local -Z direction of this node at a point in space.
Ogre::Camera::setAutoAspectRatio
void setAutoAspectRatio(bool autoratio)
If set to true a viewport that owns this frustum will be able to recalculate the aspect ratio wheneve...
OgreBites::KeyboardEvent::keysym
Keysym keysym
Definition: OgreInput.h:52
OgreBites::SDLK_ESCAPE
Definition: OgreInput.h:91
Ogre::RTShader::ShaderGenerator
Shader generator system main interface.
Definition: OgreShaderGenerator.h:61
Ogre::Node::TS_PARENT
Transform is relative to the space of the parent node.
Definition: OgreNode.h:66
OgreBites::ApplicationContextBase
Base class responsible for setting up a common context for applications.
Definition: OgreApplicationContextBase.h:85
Ogre::SceneManager::createLight
virtual Light * createLight(const String &name)
Creates a light for use in the scene.
OgreBites::KeyboardEvent
Definition: OgreInput.h:50
Ogre::SceneNode::attachObject
virtual void attachObject(MovableObject *obj)
Adds an instance of a scene object to this node.
OgreBites::Keysym::sym
Keycode sym
Definition: OgreInput.h:46
OgreBites::ApplicationContextBase::setup
virtual void setup()
Sets up the context after configuration.
Ogre::SceneManager::getRootSceneNode
SceneNode * getRootSceneNode(void)
Gets the SceneNode at the root of the scene hierarchy.
Ogre::Node::setPosition
void setPosition(const Vector3 &pos)
Sets the position of the node relative to it's parent.
Ogre::SceneNode
Class representing a node in the scene graph.
Definition: OgreSceneNode.h:57
Ogre::Root::createSceneManager
SceneManager * createSceneManager()
create a default scene manager
Definition: OgreRoot.h:373
Ogre::RTShader::ShaderGenerator::getSingletonPtr
static ShaderGenerator * getSingletonPtr()
Get the singleton instance.
OgreBites::ApplicationContext
ApplicationContextBase ApplicationContext
Definition: OgreApplicationContext.h:99
Ogre::Vector< 3, Real >
Ogre::Camera
A viewpoint from which the scene will be rendered.
Definition: OgreCamera.h:80
OgreBites::InputListener
the return values of the callbacks are ignored by ApplicationContext however they can be used to cont...
Definition: OgreInput.h:121