OGRE 3D 1.7 Application Development Cookbook

1. Create a new project by clicking on File | New | Project. In the New Project dialog-box, expand Visual C++, and click on Win32 Project. Name the project OgreInWin32. For Location, browse to the Recipes folder and append \Chapter_01_Examples, then click on OK.

2. In the Win32 Application Wizard that appears, click on Next. For Application type, select Windows application, and then click on Finish to create the project. At this point, we have everything we need for a bare-bones Win32 application without Ogre.

3. Next, we need to adjust our project properties, so that the compiler and linker know where to put our executable and find the Ogre header and library files.

4. Open the Property Pages dialog-box, by selecting the Project menu and clicking on Properties.

5. Expand Configuration Properties and click on General. Set Character Set to Not Set.

6. Next, click on Debugging. Select the Local Windows Debugger as the Debugger to launch, then specify the Command for starting the application as ..\..\..\bin\debug\$(TargetName)$(TargetExt).

7. Next we'll specify our VC++ Directories, so they match our Cookbook folder structure.

8. Select VC++ Directories to bring up the property page where we'll specify general Include Directories and Library Directories. Click on Include Directories, then click on the down arrow button that appears on the right of the property value, and click on <edit>.

9. In the Include Directories dialog-box that appears, click on the first line of the text area, and enter the relative path to the Boost header files: ..\..\..\OgreSDK_vc10_v1-7-1\boost_1_42.

10. Click on the second line, and enter the relative path to the Ogre header files ..\..\..\OgreSDK_vc10_v1-7-1\include\OGRE, and click OK.

11. Edit the Library Directories property in the same way. Add the library directory ..\..\..\OgreSDK_vc10_v1-7-1\boost_1_42\lib for Boost, and ..\..\..\OgreSDK_vc10_v1-7-1\lib\debug for Ogre, then click OK.

12. Next, expand the Linker section, and select General. Change the Output File property to ..\..\..\bin\debug\$(TargetName)$(TargetExt).

13. Then, change the Additional Library Directories property to ..\..\..\Ogre\OgreSDK_vc10_v1-7-1\lib\debug.

14. Finally, provide the linker with the location of the main Ogre code library. Select the Input properties section, and prepend OgreMain_d.lib; at the beginning of the line.

Note that if we were setting properties for the release configuration, we would use OgreMain.lib instead of OgreMain_d.lib.

15. Now that the project properties are set, let's add the code necessary to integrate Ogre in our Win32 application.

Copy the Engine.cpp and Engine.h files from the Cookbook sample files to your new project folder, and add them to the project. These files contain the CEngine wrapper class that we'll be using to interface with Ogre.

16. Open the OgreInWin32.cpp file, and include Engine.h, then declare a global instance of the CEngine class, and a forward declaration of our InitEngine() function with the other globals at the top of the file.

CEngine *m_Engine = NULL;
void InitEngine(HWND hWnd);

17. Next, create a utility function to instantiate our CEngine class, called InitEngine().

void InitEngine(HWND hWnd){
  m_Engine = new CEngine(hWnd);
}

18. Then, call InitEngine() from inside the InitInstance() function, just after the window handle has been created successfully, as follows:

hWnd = CreateWindow(szWindowClass, szTitle, WS_OVERLAPPEDWINDOW,
  CW_USEDEFAULT, 0, CW_USEDEFAULT, 0, NULL, NULL, hInstance, 
  NULL);

if (!hWnd){
  return FALSE;
}

InitEngine(hWnd);

19. Our last task is to render the 3D scene and display it in the window when we receive a WM_PAINT message. Add a call to renderOneFrame() to the WndProc() function, as follows:

case WM_PAINT:
  hdc = BeginPaint(hWnd, &ps);
  m_Engine->m_Root->renderOneFrame();
  EndPaint(hWnd, &ps);
break;

1. Create a new project by clicking File | New | Project. In the New Project dialog-box, expand Visual C++, and click on MFC Application. Name the project OgreInMFC. For Location, browse to your Recipes folder, append \Chapter_01_Examples, and click on OK.

2. In the MFC Application Wizard, click on Next.

For the Application type, select Single document. Unselect Use Unicode libraries, and set Project style to MFC standard. Set the Visual style and colors to Office 2007 (Black Theme), unselect Enable visual style switching, and click on Next.

3. On the Compound document support page, click on Next.

4. On the Document Template Properties page, change the File extension property to scene (not necessarily for this recipe, but will be useful later), and click on Next.

5. On the Database Support page, click on Next.

6. On the User Interface Features page, select Maximized so the application will start with its window maximized. Select Use a classic menu, and click on Next.

7. On the Advanced Features page, un-select Printing and print preview, and click on Next.

8. On the Generated Classes page, click on Finish to create the project.

9. The next step is to configure the project properties just like we did for our Win32 application, so that the compiler and linker know where to find the Ogre header and library files. Examine the project properties for the sample MFC application, and you will see that the properties are the same as in our Win32 application.

10. Next, copy the Engine.cpp and Engine.h files from the Cookbook sample MFC application to our new project folder, and add them to the project.

11. Open OgreInMfc.h, and add a new member variable for our CEngine instance, and a declaration of the InitEngine() function that we'll be adding.

public:
  CEngine* m_Engine;
  void InitEngine(void);

12. Now, in OgreInMfc.cpp, modify the COgreInMfcApp constructor to give our new member variable a default value.

COgreInMfcApp::COgreInMfcApp() : m_Engine(NULL)

13. Then, add our familiar InitEngine() function.

void COgreInMfcApp::InitEngine(void){
  m_Engine = new CEngine();
}

14. Finally, call InitEngine() at the end of COgreInMfcApp::InitInstance().

InitEngine();

In our Win32 application, all of our Ogre setup code was done in the CEngine constructor. This time, we do not have a window handle in InitInstance(), so we can't set up the render window here. The CEngine constructor only creates the Ogre engine instance and initializes it.

15. Now, add a function to the OgreInMfcView class in OgreInMfcView.h called EngineSetup() that will contain the rest of our Ogre setup code.

void EngineSetup(void);

While we're here, let's add a few more member variables that we'll need.

bool m_First;
   
Ogre::Camera*m_Camera;
Ogre::RenderWindow*m_RenderWindow;

Now open OgreInMfcView.cpp, and create the EngineSetup() function.

void COgreInMfcView::EngineSetup(void)
{}

16. First, we need to get the Ogre::Root instance from CEngine, and use it to create a scene manager named MFCOgre.

Ogre::Root *Root = ((COgreInMfcApp*)AfxGetApp())->m_Engine-
  >GetRoot();

Ogre::SceneManager *SceneManager = NULL;
SceneManager = Root->createSceneManager(Ogre::ST_GENERIC, 
  "MFCOgre");

We also create a generic scene manager, and name it MFCOgre.

17. Next, we create a render window with our window handle, just as we did in the Ogre Win32 application.

Ogre::NameValuePairList parms;
parms["externalWindowHandle"] = 
  Ogre::StringConverter::toString((long)m_hWnd);
parms["vsync"] = "true";

CRect   rect;
GetClientRect(&rect);

Ogre::RenderTarget *RenderWindow = Root->getRenderTarget("Ogre in 
  MFC");

if (RenderWindow == NULL){
  try{
    m_RenderWindow = Root->createRenderWindow("Ogre in MFC", 
      rect.Width(), rect.Height(), false, &parms);
  }
  catch(...){
    MessageBox("Cannot initialize\nCheck that graphic-card driver 
      is up-to-date", "Initialize Render System", MB_OK | 
      MB_ICONSTOP);
    exit(EXIT_SUCCESS);
  }
}

18. Then, we instruct the Ogre::ResourceGroupManager to initialize all resource groups.

// Load resources
Ogre::ResourceGroupManager::getSingleton().initialiseAllResourceGroups();

19. Next, we create and initialize our camera. We also add it to a new scene node.

// Create the camera
m_Camera = SceneManager->createCamera("Camera");
m_Camera->setNearClipDistance(0.5);
m_Camera->setFarClipDistance(5000);
m_Camera->setCastShadows(false);
m_Camera->setUseRenderingDistance(true);
m_Camera->setPosition(Ogre::Vector3(200.0, 50.0, 100.0));
Ogre::SceneNode *CameraNode = NULL;
CameraNode = SceneManager->getRootSceneNode()-
>createChildSceneNode("CameraNode");

20. After the camera is set up, we need to create a viewport that will take the contents of the camera's view, and draw it in our render window. We also need to set the camera's aspect ratio to match the aspect ratio of the render window.

Ogre::Viewport* Viewport = NULL;

if (0 == m_RenderWindow->getNumViewports()){
  Viewport = m_RenderWindow->addViewport(m_Camera);
  Viewport->setBackgroundColour(Ogre::ColourValue(0.8f, 1.0f, 
    0.8f));
}

m_Camera->setAspectRatio(Ogre::Real(rect.Width()) / 
  Ogre::Real(rect.Height()));

The last lines of code in EngineSetup() create a robot entity that uses the robot.mesh resource, and attach it to a new scene node. They also point the camera at the center of the robot's bounding box.

Ogre::Entity *RobotEntity = SceneManager->createEntity("Robot", 
  "robot.mesh");
Ogre::SceneNode *RobotNode = SceneManager->getRootSceneNode()-
  >createChildSceneNode();
RobotNode->attachObject(RobotEntity);

Ogre::AxisAlignedBox Box = RobotEntity->getBoundingBox();
Ogre::Vector3 Center = Box.getCenter();
m_Camera->lookAt(Center);

21. Next, we need to add a message handler for the WM_PAINT message, and call EngineSetup() the first time the Ogre engine instance is available.

22. To add the WM_PAINT message handler, open the Class View and expand OgreInMfc. Then right-click on COgreInMfcView, and select Properties. In the Properties window, click on the Messages icon, then scroll down till you find WM_PAINT. Click in the box next to WM_PAINT, and click on<add>OnPaint. Inside the resulting OnPaint() function, we add the following code:

CEngine *Engine = ((COgreInMfcApp*)AfxGetApp())->m_Engine;
if (Engine == NULL)
  return;

Ogre::Root *Root = Engine->GetRoot();

if (m_First && Root != NULL){
  m_First = false;
  EngineSetup();
}

23. Once the Ogre engine instance is available, we need to instruct Ogre to render by calling renderOneFrame(), so add the following code to the end of the OnPaint().

if (Root != NULL){
  Root->renderOneFrame();
}

24. Open OgreInMfcDoc.cpp, and add a call to UpdateAllViews() in COgreInMfcDoc::OnNewDocument(), so that our view's OnPaint method is called every time the user clicks on the New document button.

BOOL COgreInMfcDoc::OnNewDocument(){
  if (!CDocument::OnNewDocument())
    return FALSE;

  UpdateAllViews(NULL);
  return TRUE;
}

1. Create a new project by clicking File | New | Project. In the New Project dialog-box, expand Visual C++ under Installed Templates, select MFC and click on MFC Application, and name the project OgreInRibbon. For Location, browse to your Recipes folder, append \Chapter_01_Examples, and click on OK.

2. Click on Next on the Welcome to the MFC Application Wizard page. On the Application Type page, select Single Document under Application type. Unselect Use Unicode libraries. Under Visual style and colors, select Office 2007 (Black theme), and click on Next.

3. On the Compound Document Support page, make sure that None is selected, then click on Next.

4. On the Document Template Properties page, in the File extension box, type scene as the file name extension for documents that this application creates, and click on Next.

5. On the Database Support page, make sure that None is selected, then click Next.

6. On the User Interface Features page, select Use a ribbon. Select Maximized, then click on Next.

7. Remove Printing and print preview, and uncheck all Advanced frame panes checkboxes, then click on Next.

8. On the Generated Classes page, click on Finish to create the MFC application.

9. At this point, configure the project properties, just as we did for the Creating a Win32 Ogre application recipe.

10. Next, create a message handler for the WM_PAINT message and insert our InitEngine() and EngineSetup() functions, exactly as we did in the Creating an MFC Ogre application recipe.

1. Create a new project by clicking File | New | Project. In the Project Types pane, expand Visual C++, select CLR, then select Windows Forms Application in the Templates pane. Name the project OgreInWinForms. For Location, browse to your Recipes folder, append \Chapter_01_Examples, and click on OK.

The Windows Forms Designer will appear showing Form1 of the Windows Forms application that we just created.

2. Next, in the Solution Explorer pane, right-click Form1.h, and click View Code.

In Form1.h, add a new CEngine member instance variable.

public:
  CEngine *m_Engine;

3. In the constructor, create an instance of our CEngine class, and pass it our window handle.

OgreForm(void)
  : m_Engine(NULL){
  InitializeComponent();
  m_Engine = new CEngine((HWND)this->Handle.ToPointer());
}

4. Next, we add a PaintEventHandler function and Resize EventHandler function to the InitializeComponent() method, and set the default window state to maximized.

this->WindowState = 
  System::Windows::Forms::FormWindowState::Maximized;
this->Paint += gcnew 
  System::Windows::Forms::PaintEventHandler(this, 
  &OgreForm::Ogre_Paint);
this->Resize += gcnew System::EventHandler(this, 
  &OgreForm::OgreForm_Resize);

5. Create the functions for the event handlers we just added.

private: System::Void Ogre_Paint(System::Object^  sender, 
  System::Windows::Forms::PaintEventArgs^  e) {
  m_Engine->m_Root->renderOneFrame();
}

private: System::Void OgreForm_Resize(System::Object^  sender, 
  System::EventArgs^  e) {
  if (m_Engine != NULL) {
    m_Engine->m_Root->renderOneFrame();
  }
}

1. First, create an MFC application, and set the properties just like we did for the Creating an MFC Ogre application recipe.

2. Next, let's add a new Win32 DLL project to our solution.

Create a new project by clicking File | New | Project. In the Project Types pane, expand Visual C++ and click Win32 Project. Name the project Robot3, and then click on OK.

3. Click on OK on the Win32 Application Wizard welcome page.

4. On the Application Settings page, set the Application type to DLL, check Empty project in Additional options, and click on Finish.

5. Next, modify the project properties, just like for the Win32 application project, and be sure to set the Linker Output File property, so our DLL ends up in the same folder as our MFC application executable.

6. Next, create an empty header file named Robot.h, and add it to the Robot project. In the new header file, create a new class called Robot3Plugin that derives from Ogre::Plugin.

#include "Ogre.h"
#include "OgrePlugin.h"

class Robot3Plugin : public Ogre::Plugin{
  public:
    Ogre::String m_Name;

  Robot3Plugin(){
    m_Name = "Robot";
  }
};

7. Every subclass of Ogre::Plugin must implement the getName(), install(), initialise(), shutdown(), and uninstall() methods, so add the following code to our new Robot3Plugin class:

const Ogre::String& getName() const {
  return m_Name;
}

void install(){}

void initialise(){
  Ogre::SceneManager *SceneManager = 
    Ogre::Root::getSingleton().getSceneManager("OgrePlugin");
  Ogre::Entity *RobotEntity = SceneManager->createEntity("Robot", 
    "robot.mesh");
  Ogre::SceneNode *RobotNode = SceneManager->getRootSceneNode()-
    >createChildSceneNode();
  RobotNode->attachObject(RobotEntity);

  Ogre::AxisAlignedBox Box = RobotEntity->getBoundingBox();
  Ogre::Vector3 Center = Box.getCenter();
  Ogre::Camera *Camera = SceneManager->getCamera("Camera");
  Camera->lookAt(Center);

  Ogre::Root::getSingleton().renderOneFrame();
}

void shutdown(){}

void uninstall(){}

The getName() function simply returns the unique name of our plugin. Every other method, except for initialise(), we leave empty.

In the initialise() method, we load our robot mesh, create the robot entity, and attach it to a scene node. We also point the camera at the center of the robot's bounding box, and then call renderOneFrame(), which will result in Ogre drawing the scene to our application window.

8. Create an empty file called Robot3.cpp, and add it to the project.

At the top of the Robot3.cpp file, import the necessary headers and declare a global instance variable of our Robot3Plugin class.

#include "Robot3.h"
#include "Ogre.h"
#include "OgrePlugin.h"

Robot3Plugin *Robot;

9. Next, define two functions, dllStartPlugin() and dllStopPlugin().

extern "C" __declspec(dllexport) void dllStartPlugin(){
  Robot = OGRE_NEW Robot3Plugin();
  Ogre::Root::getSingleton().installPlugin(Robot);
}

extern "C" __declspec(dllexport) void dllStopPlugin(){
  Ogre::Root::getSingleton().uninstallPlugin(Robot); 
  OGRE_DELETE Robot;
}

The dllStartPlugin() will be called by Ogre when it loads our plugin, and dllStopPlugin() will be called when the plugin is unloaded.

10. Now we need to add a menu item, so that we can test loading the Robot plugin.

In the Resource View, expand Plugin Manager, PluginManager.rc, and then Menu. Double-click on the IDR_MAINFRAME resource item to open the menu editor.

11. Add the submenu Load to the main menu, expand it, and add a new item named Robot Mesh.

12. Next, we need to add an event handler for when the user selects the new menu item. Right-click on the RobotMesh menu item, and choose Add Event Handler.

13. In the Event Handler Wizard that appears, set the Function handler name to OnLoadRobot, select CPluginManagerView from the Class List, and then press Add and Edit.

Our event handler function looks like this:

void CPluginManagerView::OnLoadRobot(){
  Ogre::Root::getSingleton().loadPlugin("Robot3");
}

When we call loadPlugin(), Ogre will load our Robot plugin and call dllStartPlugin(), after which, Ogre will call initialize(), and our robot will appear in our application window.

1. First, create a new Ogre MFC application named ResourceManager, by following the Creating an MFC Ogre application recipe.

2. Next, we need the following three new classes.

3. Copy the StlFile, StlFileManager, StlFileSerialzer headers, and .cpp files into your projects folder, and add them to the project.

Any resource type we create that we want to add to an Ogre::ResourceManager must derive from the Ogre::Resource class. It must implement the loadImpl() and unloadImpl() functions, which will be called when a resource manager attempts to load or unload the resource. The StlFileSerializer does all the heavy lifting in terms of parsing the file data and creating Ogre 3D models. Our StlFileManager simply keeps track of existing StlFile resources, and provides an interface for creating entities from StlFile resources.

4. Let's create an instance of our new resource manager, and register it with Ogre.

Add a new StlFileManager member variable in Engine.h called m_StlFileManager, and include StlFileManager.h, then open Engine.cpp and add the following code just after we create m_Root:

m_StlFileManager = OGRE_NEW StlFileManager();

5. Next add the following code just before we call m_Root->initialize():

Ogre::ResourceGroupManager::getSingleton().
  createResourceGroup("StlFile", true);
Ogre::ResourceGroupManager::getSingleton().
  initialiseResourceGroup("StlFile");
Ogre::ResourceGroupManager::getSingleton().
  addResourceLocation(Ogre::String(ApplicationPath) + 
  Ogre::String("..\\..\\media\\stl\\Tubes\\hoses\\curvature"),
  "FileSystem","StlFile");

Here, we add a new resource group for our StlFile resources, and add a FileSystem resource location where Ogre can find StlFiles.

6. Next, we modify our MFC view's EngineSetup() function, and add code at the end, to create a new entity using the StlFileManager.

Ogre::Entity *MobiusEntity = Engine->m_StlFileManager-
  >createEntity("Mobius", "1_4.stl");
Ogre::SceneNode *MobiusNode = SceneManager->getRootSceneNode()-
  >createChildSceneNode();
MobiusNode->attachObject(MobiusEntity);

Ogre::AxisAlignedBox MobiusBox = MobiusEntity->getBoundingBox();
Ogre::Vector3 MobiusCenter = MobiusBox.getCenter();

m_Camera->lookAt(MobiusCenter);
m_Camera->setPosition(300, 100, 200);