OGRE  13.0
Object-Oriented Graphics Rendering Engine
Setting up an OGRE project
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 components you need.
# The CONFIG flag makes sure you get OGRE instead of OGRE-next
find_package(OGRE REQUIRED COMPONENTS Bites RTShaderSystem CONFIG)
# 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)
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
// get a pointer to the already created root
Ogre::Root* root = getRoot();
// register our scene with the RTSS
// without light we would just get a black screen
Ogre::Light* light = scnMgr->createLight("MainLight");
lightNode->setPosition(0, 10, 15);
// 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
// and tell it to render into the main window
// finally something to render
Ogre::Entity* ent = scnMgr->createEntity("Sinbad.mesh");
The above code is explained in detail in Your First Scene.

finally we start everything as

int main(int argc, char *argv[])
MyTestApp app;
return 0;
You can find the full code of the above example at
  • Samples/Tutorials/Bootstrap.cpp for C++
  • Samples/Python/sample.py for Python
  • Samples/AndroidJNI/MainActivity.java for Java (Android)
  • Samples/Csharp/example.cs for C#

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

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.

Configuration Files

Ogre uses several configuration files (*.cfg). They control things like which plugins are loaded and where your application will search for resource files. We will briefly introduce you to each of these files. You'll slowly read more about them as you progress through the tutorials as well.

You can place these files the same directory as your executable or in any of the default lookup paths described here. Alternatively you can set the OGRE_CONFIG_DIR environment variable for the configuration file location. This overrides the step "executable path" in the default lookup order.

Ogre must find plugins.cfg and resources.cfg to function properly. Later tutorials will cover more of their use.


This file tells Ogre which plugins to load. You modify this file when you want to load a different set of plugins. It is often most useful to simply "comment out" lines instead of removing them, because you never know when a stroke of inspiration will mean you want to reload some unused plugins. Here is some sample content:

# Plugin=RenderSystem_Direct3D9
# Plugin=RenderSystem_Direct3D10
# Plugin=RenderSystem_Direct3D11

We have the three DirectX systems commented out, and an active line for OpenGL. On a windows system, you may have this reversed. You can see why it might be helpful not to delete unused lines, because then you have to try and remember whether it was RenderSystem_OpenGL or RenderSystem_GL.

You can also decide where Ogre looks for plugins by changing the PluginFolder variable. You can use both absolute and relative paths. Relative paths are resolved relative to the location of plugins.cfg. Additionally, you can use the OGRE_PLUGIN_DIR environment variable to override the value of PluginFolder.

For example, if you have built Ogre from source on a linux machine, then you will need a line like this at the beginning of your file:


By default, Ogre would have been looking in the same directory where the plugins.cfg is located, which is sufficient on Windows.

Ogre is aware whether your app is a bundle. Therefore a relative path like Contents/Frameworks/ will be correctly resolved inside the app bundle on OSX.


This file contains a list of the directories Ogre will use to search for resources. Resources include scripts, meshes, textures, GUI layouts, and others. You can also use both absolute and relative paths in this file, but you still cannot use environment variables. Relative paths are resolved relative to the location of resources.cfg. Ogre will not search subdirectories, so you have to manually enter them. Here is an example:


Here is an example of a relative path being used and the need to list subdirectories. Including the '../media' directory did not automatically include the '../media/models' directory. This is so that Ogre doesn't get greedy and waste time loading up unneeded resources.


This file is generated by the Render Settings dialog that appears when you run your application. Do not distribute this file with your application. This file will be specific to your own setup. This file will contain your choices for things like screen resolution (see Ogre::RenderSystem::setConfigOption). Do not modify this file directly. Change the settings with the dialog and it will be automatically updated.

Depending on the OS, Ogre will place this config file in the writable path described here.

virtual SceneNode * createChildSceneNode(const Vector3 &translate=Vector3::ZERO, const Quaternion &rotate=Quaternion::IDENTITY)
Creates an unnamed new SceneNode as a child of this node.
Definition: OgreInput.h:117
virtual Camera * createCamera(const String &name)
Creates a camera to be managed by this scene manager.
Defines an instance of a discrete, movable object based on a Mesh.
Definition: OgreEntity.h:79
Entity * createEntity(const String &entityName, const String &meshName, const String &groupName=ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME)
Create an Entity (instance of a discrete mesh).
Representation of a dynamic light source in the scene.
Definition: OgreLight.h:94
Definition: OgreAdvancedRenderControls.h:41
void setNearClipDistance(Real nearDist)
Sets the position of the near clipping plane.
Manages the organisation and rendering of a 'scene': a collection of objects and potentially world ge...
Definition: OgreSceneManager.h:237
The root class of the Ogre system.
Definition: OgreRoot.h:66
void addSceneManager(SceneManager *sceneMgr)
Add a scene manager to the shader generator scene managers list.
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.
void setAutoAspectRatio(bool autoratio)
If set to true a viewport that owns this frustum will be able to recalculate the aspect ratio wheneve...
Keysym keysym
Definition: OgreInput.h:59
Shader generator system main interface.
Definition: OgreShaderGenerator.h:61
Transform is relative to the space of the parent node.
Definition: OgreNode.h:67
Base class responsible for setting up a common context for applications.
Definition: OgreApplicationContextBase.h:86
ApplicationContextBase ApplicationContext
Definition: OgreApplicationContext.h:101
virtual Light * createLight(const String &name)
Creates a light for use in the scene.
Definition: OgreInput.h:57
virtual void attachObject(MovableObject *obj)
Adds an instance of a scene object to this node.
Keycode sym
Definition: OgreInput.h:53
virtual void setup()
Sets up the context after configuration.
SceneNode * getRootSceneNode(void)
Gets the SceneNode at the root of the scene hierarchy.
void setPosition(const Vector3 &pos)
Sets the position of the node relative to it's parent.
Class representing a node in the scene graph.
Definition: OgreSceneNode.h:60
SceneManager * createSceneManager()
create a default scene manager
Definition: OgreRoot.h:371
static ShaderGenerator * getSingletonPtr()
Get the singleton instance.
Ogre::Vector< 3, Real >
A viewpoint from which the scene will be rendered.
Definition: OgreCamera.h:85
the return values of the callbacks are ignored by ApplicationContext however they can be used to cont...
Definition: OgreInput.h:173