Thursday, January 14, 2010

Compilation and Installation of Ogre 1.7RC1 on Ubuntu 9.10 Karmic Koala







Never thought my first post would be on this topic. I guess my gaming addiction has finally overcame my sanity; and pushed me into the learning of 3D graphics. Last year, Runic game (Diablo II Legacy) released game torchlight, created with the Ogre graphic engine. The vibrant colour and impressive fps sufficiently convinced me that Ogre is not just toy for someone's weekend in the garage. Therefore to begin my path of insanity, I picked Ogre, a pure 3D rendering engine (as opposite to a game engine) written in C++.

Due to my overwhelming hatred of coding under Windows, I installed Ogre 1.7RC1 on my trusty Ubuntu 9.10. Little did I know before hand that the installation would take more than 8 hours for me. The documentation regarding to the installation/compilation is somewhat dated for the 1.7 version, even more dated for Linux platform. As the result, I have wasted much of the time figuring out what to do and what went wrong. I won't venture writing all the steps I took with my broken English. Thus the following of this post will be dedicated to describe how I get everything work. This is a memo for myself; in case I need to redo the process in the future.

Much of the information is drawn from a post on Ubuntu forum by CalderCoalson
http://ubuntuforums.org/showthread.php?t=1144592
, but again the information there is a little dated.

- Get the source
    - download the source from Ogre at: http://www.ogre3d.org/download/source
    - unzip and put it some where comfortable, it is there to stay
        - Ex: ~/app/ogre_base/ogre
    - create a separate "build" folder from where cmake is excuted
        - Ex: ~/app/ogre_base/build

- Resolve dependencies:
    - run cmake under the build folder
        => cmake ../ogre
    - have a look at the output, it will tell you what's missing (Important)
        - most of the things can be installed through synaptic package manager GUI including:
            build-essential, OIS, freeimage, Xt, Xaw, cmake
        - Cg package is better downloaded from nvidia site
            - locate it from Google, and download it
            - unzip and copy the folder structure as it is, this will need sudo
        - Freetype needs to be downloaded from Internet as well as at the time of writing
            - locate it from Google, and download it
            - ./configure => ./make => ./make install => rm
    - => sudo ldconfig to update library

- Compile
    - use cmake-gui
        - where is the source code: ~/app/ogre_base/ogre
        - where to build the binaries: ~/app/ogre_base/build
    - switch to group view
        - under OGRE
        - switch on install media
    - compile
        : cd ~/app/ogre_base/build
        : make (make -j 3 for those with duo core)
        : sudo make install
    - have a try
        - stay in the same path
        - go bin
        - run ./SampleBrowser
        - the demo should work, or you need to seek help now
      
- Hello World using cmake
    - use cmake to find all the dependencies and generate make file worked for me the best.
        - references: (http://www.ogre3d.org/wiki/index.php/Building_Your_Projects_With_CMake)
    - Create a project like so
        .
        |-- CMakeLists.txt
        |-- build
        |   |-- plugins.cfg
        |   `-- resources.cfg
        |-- include
        |   |-- ExampleApplication.h
        |   |-- ExampleFrameListener.h
        |   |-- ExampleLoadingBar.h
        |   |-- OgreStaticPluginLoader.h
        |   |-- Sample.h
        |   |-- SampleContext.h
        |   |-- SamplePlugin.h
        |   |-- SdkCameraMan.h
        |   |-- SdkSample.h
        |   `-- SdkTrays.h
        `-- src
            `-- hello.cpp
    - copy headers
        - in the previous step all the .h files are copied from
            ~/app/ogre_base/ogre/Samples/Common/include
    - source code: hello.cpp
        --------------------------------------
            #include "ExampleApplication.h"

            class TutorialApplication : public ExampleApplication
            {
            protected:
            public:
                TutorialApplication()
                {
                }

                ~TutorialApplication()
                {
                }
            protected:
                void createScene(void)
                {
                   mSceneMgr->setAmbientLight( ColourValue( 1.5, 1.5, 2 ) );

                   Entity *ent1 = mSceneMgr->createEntity( "Robot", "robot.mesh" );

                   SceneNode *node1 = mSceneMgr->getRootSceneNode()->createChildSceneNode( "RobotNode" );

                   node1->attachObject( ent1 );

                }
            };

            #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
            {
                // Create application object
                TutorialApplication app;

                try {
                    app.go();
                } catch( Exception& e ) {
            #if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
                    MessageBox( NULL, e.what(), "An exception has occurred!", MB_OK | MB_ICONERROR | MB_TASKMODAL);
            #else
                    fprintf(stderr, "An exception has occurred: %s\n", e.what());
            #endif
                }

                return 0;
            }
        --------------------------------------
    - CMakeLists.txt contains the following (adjust paths to match your installation):
        --------------------------------------
            cmake_minimum_required(VERSION 2.6)
            PROJECT(helloOGRE)
          
            set(CMAKE_MODULE_PATH
             /usr/local/lib/OGRE/cmake
            )
          
            FIND_PACKAGE(OpenGL)
            FIND_PACKAGE(OGRE)
            FIND_PACKAGE(OIS)
          
            INCLUDE_DIRECTORIES(
             ${OpenGL_INCLUDE_DIR}
             ${OGRE_INCLUDE_DIRS}
             ${OIS_INCLUDE_DIRS}
             ${PROJECT_SOURCE_DIR}/include
            )

            FILE(GLOB SRCS src/*.cpp)
            FILE(GLOB HDRS include/*.h)
          
            ADD_EXECUTABLE(helloOGRE
             ${SRCS}
             ${HDRS}
            )
          
            TARGET_LINK_LIBRARIES(helloOGRE
             ${OpenGL_LIBRARIES}
             ${OIS_LIBRARIES}
             ${OGRE_LIBRARIES}
            )
        --------------------------------------
    - compile and link
        : cd build
        : cmake ..
        : make
    - copy plugins.cfg and resources.cfg from (usr/local/bin - adjust for your installation path) to the build folder
        - change all the relative paths to absolute
        - Example as the following:
        -----------plugins.cfg starts---------------------------
            # Defines plugins to load

            # Define plugin folder
            PluginFolder=/usr/local/lib/OGRE

            # Define plugins
            # Plugin=RenderSystem_Direct3D9
            # Plugin=RenderSystem_Direct3D10
            # Plugin=RenderSystem_Direct3D11
             Plugin=RenderSystem_GL
            # Plugin=RenderSystem_GLES
             Plugin=Plugin_ParticleFX
             Plugin=Plugin_BSPSceneManager
             Plugin=Plugin_CgProgramManager
             Plugin=Plugin_PCZSceneManager
             Plugin=Plugin_OctreeZone
             Plugin=Plugin_OctreeSceneManager
         -----------plugins.cfg ends-----------------------------
      
         -----------resources.cfg starts---------------------------
            # Resources required by the sample browser and most samples.
            [Essential]
            Zip=/usr/local/share/OGRE/media/packs/SdkTrays.zip
            FileSystem=/usr/local/share/OGRE/media/thumbnails

            # Common sample resources needed by many of the samples.
            # Rarely used resources should be separately loaded by the
            # samples which require them.
            [Popular]
            FileSystem=/usr/local/share/OGRE/media/fonts
            FileSystem=/usr/local/share/OGRE/media/materials/programs
            FileSystem=/usr/local/share/OGRE/media/materials/scripts
            FileSystem=/usr/local/share/OGRE/media/materials/textures
            FileSystem=/usr/local/share/OGRE/media/materials/textures/nvidia
            FileSystem=/usr/local/share/OGRE/media/models
            FileSystem=/usr/local/share/OGRE/media/particle
            FileSystem=/usr/local/share/OGRE/media/DeferredShadingMedia
            FileSystem=/usr/local/share/OGRE/media/PCZAppMedia
            FileSystem=/usr/local/share/OGRE/media/RTShaderLib
            Zip=/usr/local/share/OGRE/media/packs/cubemap.zip
            Zip=/usr/local/share/OGRE/media/packs/cubemapsJS.zip
            Zip=/usr/local/share/OGRE/media/packs/dragon.zip
            Zip=/usr/local/share/OGRE/media/packs/fresneldemo.zip
            Zip=/usr/local/share/OGRE/media/packs/ogretestmap.zip
            Zip=/usr/local/share/OGRE/media/packs/ogredance.zip
            Zip=/usr/local/share/OGRE/media/packs/skybox.zip

            [General]
            FileSystem=/usr/local/share/OGRE/media
         -----------resources.cfg ends-----------------------------
     - run!!
            :./helloOGRE
            - should see a robot in the scene and WASD to move camera
            - there might be some error showing up in the log, namely:
                10:14:05: OGRE EXCEPTION(5:ItemIdentityException): OverlayElement with name Core/AverageFps not found. in OverlayManager::getOverlayElementImpl at /home/shen/app/ogre_base/ogre/OgreMain/src/OgreOverlayManager.cpp (line 635)
                - This is due to in 1.7RC1, OgreCore.zip is replaced by SdkTrays.zip and the Sample codes are dated. Don't worry. This should not be a problem
              
So now, I should be able to proceed with the rest of the tutorials on Ogre wiki~ Done.

Disclaimer: As the burning of time has no flame, the information on this page will be dated and become inaccurate for certain some point in the future.