Setting Up An Application - Mac OSX - Shoggoth         How to setup your own project for use with Ogre - Mac OS X
Page actions
Print

%prevogre%

XCode

  • In XCode, select menu File > New project > Carbon Application.
  • Place your project wherever you want and name it, then click finish
  • Remove main.nib and *_Prefix.pch (note: if you wish to use a precompiled prefix header, you may, just adapt the instructions as needed)
  • rename main.c to main.cpp. Remove its content and replace it with Ogre code (for instance http://www.ogre3d.org/wiki/index.php/BasicTutorial2Source).

  • Add Ogre.framework and Cg.framework to your project by right-clicking on your project name in the tree and selecting Add > Existing frameworks. Add the IOKit framework from system directories the same way.
  • Add static library libois.a the same way (libFreeImage.a, libfreetype.a libzzip.a were also previously required but apparently are no more).


(These libraries are all provided in the Ogre dependencies download except Ogre.framework that you either got from the mac SDK or built from source.)
(As of Ogre 1.4.5, I had better success with the CVS version of OIS on mac. OIS versions greater than 1.0 should be all okay though.)

Now you must add the required config files to your project. You can find these files in Ogre/Mac/Samples/config Just drag and drop them to the file tree and they should automatically be copied to the Resources directory of your app. Whenever you add data or source files to the project, make sure you check the copy items checkbox in the dialog that pops-up before confirming file addition because you don't want to modify the original files. There is no need to do that with libraries though.

  • plugins.cfg
  • media.cfg
  • resources.cfg : you will need to edit this one to point inside your application. here is an example of resources.cfg file to work with the samples and tutorials 

# Resource locations to be added to the 'boostrap' path
# This also contains the minimum you need to use the Ogre example framework
[Bootstrap]
Zip=Contents/Resources/Media/packs/OgreCore.zip

# Resource locations to be added to the default path
[General]
FileSystem=Contents/Resources/Media
FileSystem=Contents/Resources/Media/fonts
FileSystem=Contents/Resources/Media/materials/programs
FileSystem=Contents/Resources/Media/materials/scripts
FileSystem=Contents/Resources/Media/materials/textures
FileSystem=Contents/Resources/Media/models
FileSystem=Contents/Resources/Media/overlays
FileSystem=Contents/Resources/Media/particle
FileSystem=Contents/Resources/Media/gui
FileSystem=Contents/Resources/Media/DeferredShadingMedia
Zip=Contents/Resources/Media/packs/cubemap.zip
Zip=Contents/Resources/Media/packs/cubemapsJS.zip
Zip=Contents/Resources/Media/packs/dragon.zip
Zip=Contents/Resources/Media/packs/fresneldemo.zip
Zip=Contents/Resources/Media/packs/ogretestmap.zip
Zip=Contents/Resources/Media/packs/skybox.zip
  • Media : found in Ogre/Samples (if you want to run the samples or tutorials. make sure you create folder references and not group references - you can choose that in the dialog that pops-up just after you dragged and dropped the folder onto the tree)

  • Open targets in the file tree
  • Right-click on your target, select get info, go in tab build
  • In configuration, make sure to select all configurations when you make changes that should apply to both debug and release
  • In collection architectures, double-click on element Architectures in the list and select the architectures you wish to build (and have built Ogre for). If you build Universal binary, make sure the SDK path in build locations is a universal one (for instance /Developer/SDKs/MacOSX10.4u.sdk. This template should set it to universal by default.).
  • In linking, disable ZeroLink
  • In language, remove the file in Prefix Header and uncheck Precompile prefix header
  • In search paths, add the path to includes provided in Ogre dependencies (double-click on header search paths, drag and drop the OgreDependencies-1.4.5/include folder there)


Existing projects will try to include Ogre.h and not <Ogre/Ogre.h> like frameworks usually require, so you may want to set up an additional header search path pointing inside your Ogre framework headers directory.

If you want to use the samples or tutorials you will also need to copy example application header files from /ogre-1.4.5/Samples/Common/include/

You will now need a copy files build step in your target:

  • Right-click on your target
  • select Add > New Build Phase > New Copy File Build Phase
  • In the window that pops up, select Frameworks in the destination field, don't change any other settings.
  • Now expand your target in the tree view and you should see the new step you just added as a child of your target, by befault named something like Copy Files.
  • Drag and drop all Ogre-related frameworks (including those from Ogre dependencies) inside the new build step you just created.
  • Warning, files you add to the project from now on will tend to add themselves to the copy files build step, make sure only frameworks find their way there.


You are now ready to build and run!

Once you're done, put a copy of your project in ~/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application/, so next time you can just select New project and choose this one from the template list (in older versions of OSX/Xcode, the templates directoy was at ~/Library/Application Support/Apple/Developer Tools/Project Templates)

Getting Help

Probably the top two problems people have with Ogre are not being able to compile or a missing dependency. For the first, you are going to need to learn how to use your compiler. If you barely know C++ then expect a challenge, but don't give up! Thousands of people have successfully gotten Ogre to work with both the GCC and MSVC compilers, so look in the wiki and forums for what they have done that you haven't. For missing dependencies, these are libraries that aren't installed, that aren't linked against your program, or that aren't in your runtime path. Other dependencies are incorrect rendering plugins in your plugins.cfg file or incorrect paths in your resources.cfg file, or missing one of the files all together.

If you have problems reread this page as well as Installing An SDK - Shoggoth and Building From Source - Shoggoth and look in the Ogre.log file. You may also find your problem answered in the Build FAQ. If you need further help, search the forums. It is likely your problem has happened to others many times. If this is a new issue, read the forum rules then ask away. Make sure to provide relevant details from your Ogre.log, exceptions, error messages, and/or debugger back traces. Be specific and people will be more able to help you.

Your First Application

Now we will create a basic source file for starting an OGRE application. This program, like the included samples, uses the example framework.

Copy the following code and include it as a new file in your project settings. Following our conventions, you'd put it in work_dir/src and name it SampleApp.cpp. Since this is dependent upon ExampleApplication.h and ExampleFrameListener.h make sure these files are accessible by your project. Our convention would have you put them in work_dir/include. You can copy them from the Samples directory. 

#include "ExampleApplication.h"
 
 ''// Declare a subclass of the ExampleFrameListener class''
 '''class''' MyListener : '''public''' ExampleFrameListener
 {
 '''public''':
     MyListener(RenderWindow* win, Camera* cam) : ExampleFrameListener(win, cam)
     {
     }
 
     '''bool''' frameStarted('''const''' FrameEvent& evt)
     {
         '''return''' ExampleFrameListener::frameStarted(evt);        
     }
 
     '''bool''' frameEnded(const FrameEvent& evt)
     {
         '''return''' ExampleFrameListener::frameEnded(evt);        
     }
 };
 
 ''// Declare a subclass of the ExampleApplication class''
 '''class''' SampleApp : '''public''' ExampleApplication 
 {
 '''public''':
    SampleApp() 
    {
    }
 
 '''protected''':
    ''// Define what is in the scene
    '''void''' createScene('''void''')
    {
        // put your scene creation in here
    }
   
    ''// Create new frame listener''
    '''void''' createFrameListener('''void''')
    {
        mFrameListener = '''new''' MyListener(mWindow, mCamera);
        mRoot->addFrameListener(mFrameListener);
    }
 };
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 
 #define WIN32_LEAN_AND_MEAN 
 #include "windows.h" 
 '''INT''' WINAPI WinMain(HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, '''INT''') 
 #else 
 '''int''' main('''int''' argc, '''char''' **argv) 
 #endif 
 {
     ''// Instantiate our subclass''
     SampleApp myApp;
 
     '''try''' {
         ''// ExampleApplication provides a go method, which starts the rendering.''
         myApp.go();
     }
     '''catch''' (Ogre::Exception& e) {
 #if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 
         MessageBoxA(NULL, e.getFullDescription().c_str(), "An exception has occured!", MB_OK | MB_ICONERROR | MB_TASKMODAL);
 #else
         std::cerr << "Exception:\n";
         std::cerr << e.getFullDescription().c_str() << "\n";
 #endif
         '''return''' 1;
     }
 
 '''return''' 0;
 }
 
 #ifdef __cplusplus
 }
 #endif

Compile this code now. However before running the program, make sure you have a plugins.cfg and a resources.cfg in the same directory as the executable. Review the Prerequisites section for the purpose of these files. Edit them and make sure the paths are correct. Otherwise your OGRE setup dialog box may not have any rendering libraries in it, or you may recieve an error on your screen or in Ogre.log that looks something like this: 

Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file

When the program starts it will display the OGRE setup dialog and start the application with a blank, black screen containing little more than the OGRE logo and an FPS (frame per second) display. We haven't added anything to this scene yet, as evidenced by the empty createScene method. Press ESC to quit the application.

If you didn't get this, something is not right in your setup. See the Prerequisites and the Getting Help sections to review your installation.

The ExampleApplication framework will boot the OGRE system, displaying a configuration dialog, create a window, setup a camera and respond to the standard mouselook & WSAD controls. All you have to do is to fill in the 'createScene' implementation. If you want to do more advanced things like adding extra controls, choosing a different scene manager, setting up different resource locations, etc, you will need to override more methods of ExampleApplication and maybe introduce a subclass of ExampleFrameListener.

As mentioned before, you don't have to use the ExampleApplication and ExampleFrameListener base classes. Use them to work through the tutorials and to test things out. For larger projects you'll want to write your own framework, or use one of the frameworks or engines available on Projects using OGRE.

Note for American readers
:


Sinbad the lead developer and creator of OGRE, is British. Naturally he uses British spellings such as "Colour", "Initialise" and "Normalise". Watch out for these spellings in the API.

See below to learn about your resources for getting help. Then your next step is to work through the Ogre Tutorials.

History Source