History: Basic Tutorial Introduction
Source of version: 17
Copy to clipboard
{TRANSCLUDE(page="tutbox")}This is where you should start if you are completely new to Ogre. All you need is an understanding of writing and compiling c++ programs. For this tutorial series, we will use a pre-built code base that is referred to as the ((Ogre Wiki Tutorial Framework)). This will allow us to jump right into a full scene. Don't be overwhelmed by all of the code that already exists, just focus on the topic at hand. We will slowly introduce everything step by step.
It is important that you add code as you read. The full source will be provided so that you can check your work, but you should write up every tutorial before checking it against the completed source.
{TRANSCLUDE}
!Setup
Before you can begin this series, you have to set up a basic Ogre project. If you need help with this, then you can read ((Setting Up An Application)). It has setup information for each OS and a section about building with cmake. It also has a section that covers the framework we will be using.
To start this series, you'll need four files that you can find ((Ogre Wiki Tutorial Framework|here)). Copy these files into your project (make sure to get the files that match your version/OS):
{CODE(wrap="1" colors="c++")}
BaseApplication.h
BaseApplication.cpp
TutorialApplication.h
TutorialApplication.cpp
{CODE}
Compile and run your application with these new files included. You should see the overlay displaying information about the rendering statistics. If you've got this far, then you're ready to start the series.
!Notes
When the tutorial shifts to a new method it will always be mentioned explicitly. For example, you will see: "Add the following to the beginning of {MONO()}createScene{MONO}:" If a new code section is reached and nothing has been mentioned, then you can assume the code continues exactly where the last section left off. If you spot any cases where this isn't true, then please leave a comment or make the change yourself.
During these tutorials, when a block of code (i.e. something between brackets { }) is broken up over more than one code section, a ^ will be used as a reminder that the code is continuing an unfinished block. This should __not__ be included in your project. It is soley for formatting.
An example:
{CODE(wrap="1" colors="c++")}
if (skyIsBlue)
{
sunshineOnMyFace = true;
{CODE}
Later...
{CODE(wrap="1" colors="c++")}
^ if (seeThunderCloud)
{
takeCover();
}
}
{CODE}
These should be read as one single if statement.
!Troubleshooting
If you're having problems building an application, then check ((Setting Up An Application)) to make sure your compiler is set up properly. You can also [http://www.ogre3d.org/phpBB2/search.php|search the forums]. It is likely that another user has already solved a similar problem. You can also look in the Ogre.log file in your 'dist/bin' directory for more detailed information about a failed build. This information can be very helpful when posting to the [http://www.ogre3d.org/forums/viewforum.php?f=2&sid=87b676ed9a450c1ba2b7d0c0eabadf1d|Help Forum].
__This troubleshooting will not be provided in later tutorials.__
!!MessageBox Unicode Error
If you are using Visual Studio with unicode support turned on, then you may encounter this error:
{CODE(wrap="1", colors="c++")}
error C2664: 'MessageBoxW' : cannot convert parameter 2 from 'const char *' to 'LPCWSTR'
Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
{CODE}
The problem is that the MessageBox function is expecting unicode input, and we are giving it an ANSI string. To fix this, find the following line:
{CODE(wrap="1", colors="c++")}
MessageBox(NULL, e.what(), "An exception has occurred!", MB_OK | MB_IConerror | MB_TASKMODAL);
{CODE}
And change it to this:
{CODE(wrap="1", colors="c++")}
MessageBoxA(NULL, e.what(), "An exception has occurred!", MB_OK | MB_IConerror | MB_TASKMODAL);
{CODE}
We are now calling MessageBoxA instead of MessageBox. The reason for this is that MessageBox is automatically either resolved to MessageBoxA (ANSI) or MessageBoxW (Wide/Unicode), depending on the project configuration. We fix the error by explicitly calling the ANSI function.
!!Missing DLLs or Configuration Files
If your application has missings DLLs or .cfg files, then you probably need to copy them over from the OgreSDK folder.
In Visual Studio, when you build your application in release mode, it puts the release executable in the '\bin\release' folder and the debug executable in the '\bin\debug' folder. You must copy all of the DLL and .cfg files from the OgreSDK into the appropriate folders. You would copy the files from '[[OgreSDK]\bin\release' into '\bin\release' in your project. You will also need to edit the resources.cfg file to point to the correct paths. See the next section for more information on this.
!!Problems With Resources Or Plugins
First, make sure you have 'plugins.cfg' and 'resources.cfg' in the same directory as your exectuable. The 'plugins.cfg' file tells Ogre which rendering libraries are available (Direct3D9, OpenGL, etc.). The 'resources.cfg' file is used to specify the locations of textures, meshes, scripts, and other resources. Both are simple text files. Open them up and make sure they contain the correct paths. Otherwise, you might get errors that look something like this:
{CODE(wrap="1", colors="c++")}
Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file
{CODE}
If this is the case, then open up 'resources.cfg' and correct the paths and make sure the resource actually exists. Note: You can't use environment variables such as ${OGRE_HOME} in these paths.
!!IDE Won't Launch Application
One reason this may be happening is that Ogre expects certain files to be in the same directory as the executable. If we do not set the working directory for our IDE to the location of these files, then it won't see that they exist because it expects them to be in the working directory. So we must make sure to get our working directory set up correctly.
!!!Visual Studio
The exact solution will vary based on which version of Visual Studio you are using, but the basic steps should be similar. Right click on your project in the solution explorer (not the solution itself), and go to the properties. Somewhere in the configuration properties should be options for "Debugging". Then look for a field called "Working Directory". This should be set to the location of your executable file.
If you are having trouble figuring out what to put there, try to mimic the "Command" field, which should be in the debugging options. For example, in Visual C++ 2003, the "Command" field should be something like "..\..\bin\$(ConfigurationName)\$(TargetFileName)". For the Working Directory, we need to remove the TargetFileName part. In this case, the working directory would be "..\..\bin\$(ConfigurationName)". The exact string you have to put there ''may'' vary based on your version of Visual C++ and your build environment. Be sure to check what the Command field is before doing this. Make sure to change the Working Directory for both the Release and Debug configuration.
In Visual C++ 2005 it will probably be something different entirely. I've found the "..\..\bin\$(ConfigurationName)" directory a good thing to try first, if it still does not work you may have to play with it some, or get help on the Ogre forums.
!!!Code::Blocks
Right click in your project and select "Properties...", now go to "Build Targets", then change the field "Execution working dir:" to the directory where your executable resides.
!!!Eclipse
Right click on your project and select "Run as->Run Configurations...". Then select the Run configuration for your project, and go to the "Arguments" tab. You need to change the Working Directory here. I've found the "${workspace_loc:Minemonics/dist/bin}" directory works, but otherwise just play around with it a bit. The working directory should be the location of the binary and the configuration (*.cnf) files or, if kept separately, the location of the configuration files. The binary is already selected in the "Main" tab.
!Next
((Basic Tutorial 1))