History: Ogre 2.1 FAQ

Is Ogre 2.1 stable?

Yes, it is stable. It rarely crashes, rarely leaks (no more, no less than other stable software).
However being still in development there is the occasional build-breaking change that usually takes 10 to 20 minutes of your dev time to adapt your code. There aren't huge/major changes anymore.

We've found the most common problem about working with Ogre 2.1 is the lack of up to date Wiki examples and plugins (e.g. CEGUI, etc.) instead of stability of the library itself. Some community users have ported existing plugins to 2.1, but we cannot comment on their exact quality (does not mean they're bad!).

If you're not convinced that Ogre 2.1 is stable and can be used for high-quality work, here's three projects:

• Racecraft (Official Site)
• Community member xrgo's is working on a commercial non-gaming VR project (sorry, there are no public pictures yet).
• Unnamed Wild West shooter.

Is there a manual?

Yes! It's located under Docs/2.0/Ogre 2.0 Porting Manual DRAFT.odt. We recommend viewing it in OpenOffice or LibreOffice, then exporting to PDF if you want to see it in your favorite PDF reader. MS Word has a tendency to mess up the formatting.

Is there sample code / Are there examples?

Yes! You only need to enable OGRE_BUILD_SAMPLES2 in CMake (note the 2 at the end, not OGRE_BUILD_SAMPLES which is broken at the moment and will probably be removed).
If the samples aren't building, you may be missing the SDL2 dependency. Some samples use RapidJSON. If you've cloned ogredeps you should have them both:
Note: You must clone the dependency repository. Downloading a zipped version will not work, as it won't download SDL2 which is linked as a subrepo module.

The samples are under %OgreRoot%/Samples/2.0 (the label says "2.0", but they are for "2.1").

I'm getting compiler errors with the samples. Something about the "SampleBrowser".

The SampleBrowser is part of the 1.x samples. These are not the 2.1 samples. See Is there sample code / Are there examples?

Is Ogre 2.1 too different from 1.x? What changes should I expect?

Most of these changes have been covered in the manual. However here's a quick summary:

1. Old stuff has been put under the "v1" namespace. If you get compiler errors, you may just need to append the "v1". i.e. Entity *myEntity --> v1::Entity *myEntity;
2. Items replace Entity, which are faster and easier to setup. However Items don't support everything yet (e.g. Entity has pose animations useful for facial animations, Items do not...yet). Entity is still useful for porting.
3. There is a new material system: the Hlms (High Level Material System).
4. Old materials are not recommended unless it's for rendering a few Entities at most (since they're slow and clunky to support), or unless it's for post-processing (the place where they are most useful).
5. Textures remain largely unmodified at the time being.
6. The HlmsTextureManager handles textures for our new Hlms (High Level Material System), but don't let it fool you: Behind the curtains it's just cleverly managing the TextureManager for faster rendering performance. You could bypass it if you need to.
7. Rendering is now done through Compositors. It's not an optional component for post-processing any more, but rather an integral part that tells Ogre how you want to render the scene.
8. The default ParticleFX still works.
9. Math (Vector3, Matrix4, Quaternion) has largely stayed the same.

How do I setup my own Ogre application?

Tutorial01 through Tutorial06 explain how to setup a robust render loop to handle games, such as shown in Fix your Timestep, including how to handle multi-threading.
The code under "Samples/2.0/Common" is supposed to get you bootstrapped.
For example you can see that Dergo uses GraphicsSystem.cpp
There is a CMake script (you'll need all the files) that will link to Ogre's build from source, copy the necessary DLLs and generate the plugins.cfg file. Eventually we'll bundle these scripts with our source once they mature enough.

I'm confused about threading support in Ogre 2.1

There is the "old threading" code and the "new" threading code. The old threading code can be enabled from CMake, and requires a 3rd party dependency to work (Boost, POCO, TBB, etc). It's meant to support background loading, although in my opinion (I'm dark_sylinc writing!) it did a very poor job and thus I do not recommend it. However it has been left in our code because some users did have moderate success with it, and since it was not getting in our way, it stayed.

The "new" threading code is always enabled and uses system synchronization primitives directly. You don't need to toggle anything on CMake. This code scales much better and is used to update the scene graph in parallel, AABB calculations, frustum culling, selecting LOD, culling lights, and updating v2 skeleton animations.
You tell Ogre how many worker threads we will create, which gives you a lot of control on how many threads Ogre occupies, via Root::createSceneManager (note: you must create at least one worker thread). The worker threads are created per SceneManager (i.e. if you create 2 SceneManagers with 4 threads each, Ogre will create 8 worker threads. Note that it is very likely at the moment that while the first 4 threads work, the other 4 threads will be sleeping because we still update SceneManagers serially).

Do I need Boost?

No.
Unless you want the "old" threading support, you don't need it at all. See question above.

Is there Android Support?

See What about GLES support?

What about GLES support?

The plan is to eventually fix the now-broken GLES2 renderer, supporting both GLES2 and GLES3. However the idea for GLES2 is to support it for compatibility since it's a very ill-designed API but sadly present in millions of Android devices and isn't suited for high performance. So the focus will be more about compatibility and stability rather than performance (it should still be faster than it was in Ogre 1.x anyway). There may be other limitations we can't predict yet.
With GLES3, it should be much easier to run performance oriented mobile applications.

What about WebGL support?

Once GLES2 is ready, WebGL should be a piece of cake because it's 99% similar to GLES2.

What about D3D9 support?

There is no plan to support D3D9 going forward. It might be possible for someone to revive it by reusing whatever workarounds we'll write for GLES2 to run with Ogre 2.1. But most of the team isn't thrilled about D3D9 anymore, only Assaf still cares and maintains parts of it.
Though as long as GLES2 isn't ready, we will keep the D3D9 code, although no guarantees are given regarding its usability / stability or whether it can be compiled at all.

What about D3D11 level 9.x support?

It's not a priority. Again, it may get easier to support it using the same paths we'll write for GLES2. But D3D11 level 9.x is a special snowflake very hard to deal with: It imposes weird restrictions HW didn't have, it doesn't map well to GLES2 nor D3D9. Things would've been much easier if level 9.2 Shader Model 2.x, level 9.3 Shader Model 3.0, but unfortunately they mixed things and got the worst of all worlds.
The hope really is that by the time we reach this point, level 9.x hardware support would become irrelevant.

What about iOS support?

For older iOS devices, support is tied to GLES rendersystem. For newer iOS devices, we're currently working on a Metal RenderSystem.

What about OS X support?

Once the Metal RenderSystem is ready, OS X should in theory be supported as well. For older Macs that do not support Metal, Ogre supporting GLES3 is their last hope. We do not know how well that will work until that's done.

What about Vulkan/D3D12 support?

These APIs are in our plans. In fact we are moving to a PSO (Pipeline State Object) approach and our Compositor already knows about tracking Texture/RenderTarget/UAV dependencies and their resource transitions, which should ease greatly porting to these APIs.

However, they're not in the short term goal. Except for Async Shaders, most of these new APIs benefits reduce CPU overhead, not GPU. However, Ogre 2.1 is vastly GPU-bound.
Vulkan has greater priority than D3D12 because there is little D3D12 can do that D3D11 can't, and because Vulkan is the only way to target high performance graphics in Android (a void no version of GLES is filling). But still not a huge deal because Vulkan capable Android devices are very rare. Even in 2016 there are still devices being manufactured and sold that can only handle GLES2 and KitKat.
Short term, we're aiming at focusing in our D3D11 and OpenGL paths and extending towards mobile support (GLES & Metal). Our design decisions leverage Vulkan and D3D12 for easy adaption when that happens. But it will be some time until that happens.

I've created two (or more) RenderWindows and I'm having severe graphical glitches or I get many GL_INVALID_OPERATION errors

If you're using OpenGL, you need to reuse the OpenGL context for all of the RenderWindow you create. Otherwise bad things happen. See this post: http://www.ogre3d.org/forums/viewtopic.php?f=2&t=84711&p=522308#p522313

How do I enable Double precision? I'm getting compiler errors.

We're not yet officially maintaining double precision, but it works (mostly?). Before you continue, it's very likely the problem you want to solve doesn't need double precision at all, and you just need to learn how to use Camera-relative rendering / Relative Origin via SceneManager::setRelativeOrigin. A matter of precision by Tom Forsyth and Don't store that in a float by Bruce Dawson are very good reads as well.

But if you insist or you really need double precision floats. Here's how:

1. Enable OGRE_CONFIG_DOUBLE
2. Disable OGRE_SIMD_NEON
3. Disable OGRE_SIMD_SSE2

NEON support in Android is optional. But Ogre is either compiled with or without NEON. How can I switch dynamically at runtime?

Ogre cannot switch between these implementations at runtime. This is on purpose. Supporting runtime switching would require either conditionals everywhere, or function pointers (or something similar, like virtual functions). The overhead from this would completely negate the benefits of using SIMD in the first place. Runtime switching is only useful when the amount of SIMD work is very large, and the number of times function pointers would be called is low (for example video codecs).

On Desktop the recommended approach to tackle this problem is via two builds and a third build that detects SSE2 support and then launches the correct exe. You can do the same on Android.

In Android you don't build a process. You build a library and a Java process. The Java process loads the library and then executes an entry point defined in the library. This process is not automatic. Your Java code first must load the library with your NDK code. Somewhere in your Java code there must be a snippet similar to this one:

System.loadLibrary("hello-jni");

Before you load your main NDK library, you would select, in Java, which build to load:

if( supportsNeon )
    System.loadLibrary("hello-jni-neon");
else
    System.loadLibrary("hello-jni");

Of course it adds some hassle into your build system since now you need to build your code twice (including Ogre) and your binary size (excluding assets) would double, but this is basically the same hassle desktop applications face. Of course to speed up iteration times, only build one of them for your device and build both versions when you need to deploy.

I get errors while compiling RTSS / Run Time Shader System.

The RTSS is deprecated in 2.1 and will probably be removed unless Assaf picks up the maintenance. The Hlms (High Level Material System) replaces the RTSS and is part of OgreMain. It's much faster, more stable, and easier to use.

Is it essential to have at least one HLMS C++ implementation in your project (e.g. OgreHlmsPbs, OgreHlmsPbsMobile, OgreHlmsUnlit, OgreHlmsUnlitMobile) if you're going to render something that is visible on the screen (like a Cube)?

To get PBS materials working you need to:

• Link or include in your project the C++ source code of OgreHlmsPbs.
• Have the template files under the folders "Samples/Media/Hlms/Common Samples/Media/Hlms/Pbs" bundled with your project for PBS. When you instantiate the HlmsPbs class you have to explicitly tell it the location of these files (see the samples). Important: Don't put the Common and Pbs template files in the same folder.

To get Unlit materials working you need to:

• Link or include in your project the C++ source code of OgreHlmsUnlit to get Unlit materials.
• Have the template files under the folders "Samples/Media/Hlms/Common Samples/Media/Hlms/Unlit" bundled with your project for Unlit. When you instantiate the HlmsUnlit class you have to explicitly tell it the location of these files (see the samples). Important: Don't put the Common and Unlit template files in the same folder.

You could write your own Hlms implementations but we provide our own for you that work out of the box.
At the time of writing the PbsMobile and UnlitMobile projects are not currently 100% working and were intended for GLES2 only.

I've added a Point/Spot light but it won't show up.

1. First, make sure it's using a PBS material. Unlit materials are obviously not lit.
2. Second, when a point and spot lights isn't casting shadows during that frame, PBS won't use it by default as it assumes it will be handled by a more advanced technique. You need to enable Forward3D for them to work. See the Forward3D sample.

I'm creating custom geometry but it shows black/white with PBS.

• Make sure the material is valid.
• Make sure your mesh has normals and that they are correct. Without normals, using PBS makes no sense as there can't be lighting.

How do I generate a Mesh programmatically?

• If it's a v1 object, same as before.
• If it's a v2 object see the DynamicGeometry and CustomRenderable samples.