Mogre Basic Tutorial 3b         Usage of the New Terrain System (alpha version), Sky, Fog, and the Root object

Important Note

This tutorial is related to the new terrain component.

The Mogre terrain wrapper is wasn't tested much yet.
To learn the usage of the old and stable Terrain Scene Manager look to the Mogre Basic Tutorial 3 instead.

The new terrain wrapper is only available in newer Mogre builds. Either use the Mogre 1.7.3 build of user Cycon (download here). Or you build Mogre sourself. With the tool MogreBuilder it's very easy.
Currently (April 2012) the new terrain system is NOT available in the MogreSDK.

help For questions related to the new terrain component use this forum topic

The New Terrain Component

Since Ogre 1.7 there is a new component for Terrain. It will replace the old Terrain SceneManager in Ogre 1.8. So far the component was not yet wrapped in Mogre 1.7. But now maintainer mstoyke created an alpha version of the wrapper. To use it you need a version of Mogre that is compiled from the branch "TerrainAndPaging" (for example the binaries user Cygon provided here).

Introduction

The project we will make in this tutorial consists of two main components: TerrainGroup and Terrain. There are also TerrainGlobalOptions, but they are used as a supplementary component. You can imagine TerrainGroup as a moderate zone like a glade, meadow or play-field. TerrainGroup can aggregate a bunch of Terrain pieces inside. This subdivision is used for LOD rendering, which is based on the camera's distance to each of the Terrains. In turn, Terrains consist of tiles with some material strained over them. We will use a single TerrainGroup without paging; Terrain systems using paging will be described in Intermediate tutorials.

Before we render the Terrain, we must set up all the necessary parameters of the Ogre Terrain System.

Global variables

Because the code to set up the terrain is split up into multiple methods we need three global variables:

TerrainGlobalOptions mTerrainGlobals;
TerrainGroup mTerrainGroup;
bool mTerrainImported;

Dealing with the camera

First, let's modify our Camera object for our terrain. Put this code in the CreateScene() function:

// setting up the camera
mCamera.Position = new Vector3(1683, 50, 2116);
mCamera.LookAt(new Vector3(1963, 50, 1660));
mCamera.NearClipDistance = 0.1f;
mCamera.FarClipDistance = 50000;

if (mRoot.RenderSystem.Capabilities.HasCapability(Capabilities.RSC_INFINITE_FAR_PLANE))
        mCamera.FarClipDistance = 0;

What it does, besides setting the position and orientation of the camera, is adjust the near and far clip distances. A terrain is often fairly big, and we want our camera to be able to see far into the distance. If the RenderSystem supports it, make it infinite.

Setting up directional and ambient light

The Terrain component uses a directional light to compute the terrain lightmap, so let's put a directional light into our scene (in the CreateScene() method):

// setting up the light
Vector3 lightDir = new Vector3(0.55f, -0.3f, 0.75f);
lightDir.Normalise();

Light light = mSceneMgr.CreateLight("tstLight");
light.Type = Light.LightTypes.LT_DIRECTIONAL;
light.Direction = lightDir;
light.DiffuseColour = ColourValue.White;
light.SpecularColour = new ColourValue(0.4f, 0.4f, 0.4f);

mSceneMgr.AmbientLight = new ColourValue(0.2f, 0.2f, 0.2f);

We also set some ambient light to smooth out the lighting.

Configuring our terrain

First, we create a new set of global terrain options. For this task TerrainGlobalOptions class is used. It is an options class which just stores default options for all terrains we will create and provides a Properties. There are also local options to each TerrainGroup called DefaultImportSettings, which you will see later.

mTerrainGlobals = new TerrainGlobalOptions();

Then we construct our TerrainGroup object - a helper class to manage a grid of terrains but it does not do any paging (which is done by the paging component you can see in Intermediate tutorials soon).

mTerrainGroup = new TerrainGroup(mSceneMgr, Terrain.Alignment.ALIGN_X_Z, 513, 12000.0f);
mTerrainGroup.SetFilenameConvention("BasicTutorialTerrain3", "dat");
mTerrainGroup.Origin = Vector3.ZERO;

The TerrainGroup class constructor takes our SceneManager instance, Terrain alignment option, terrain size and terrain world size as parameters. Then we tell the TerrainGroup what name we would like it to use when saving our terrain, using the SetFilenameConvention function. And lastly we set the origin of the terrain group.

Now it's time to configure our terrain:

ConfigureTerrainDefaults(light);

We'll deal with the ConfigureTerrainDefaults function later. Notice that we're passing our directional light to the function. And then we define our terrains and instruct the TerrainGroup to load them all (in CreateScene()):

for (int x = 0; x <= 0; ++x)
{
       for (int y = 0; y <= 0; ++y)
       {
              DefineTerrain(x, y);
       }
}

mTerrainGroup.LoadAllTerrains(true);

Since we only have one terrain, we'll only be calling the defineTerrain function once. But if we had multiple, we would do that there. We'll deal with the DefineTerrain function later on. Now, if we just imported our terrains, we would like our blendmaps to be calculated (in CreateScene()):

if (mTerrainImported)
{
        foreach (TerrainGroup.TerrainSlot t in mTerrainGroup.GetTerrainIterator())
        {
                InitBlendMaps(t.instance);
        }
}

The code loops through the available terrains and calls InitBlendMaps() on each. The InitBlendMaps() function will be covered later.
Now, all there is left to do is clean up after the initial terrain creation:

mTerrainGroup.FreeTemporaryResources();

We specified how the terrain shall be saved and so we are save it now:

mTerrainGroup.SaveAllTerrains(true);

The CreateScene() function so far

This is what our CreateScene() function looks like so far:

protected override void CreateScene()
{
        // setting up the camera
        mCamera.Position = new Vector3(1683, 50, 2116);
        mCamera.LookAt(new Vector3(1963, 50, 1660));
        mCamera.NearClipDistance = 0.1f;
        mCamera.FarClipDistance = 50000;

        if (mRoot.RenderSystem.Capabilities.HasCapability(Capabilities.RSC_INFINITE_FAR_PLANE))
                mCamera.FarClipDistance = 0;

        // setting up the light
        Vector3 lightDir = new Vector3(0.55f, -0.3f, 0.75f);
        lightDir.Normalise();

        Light light = mSceneMgr.CreateLight("tstLight");
        light.Type = Light.LightTypes.LT_DIRECTIONAL;
        light.Direction = lightDir;
        light.DiffuseColour = ColourValue.White;
        light.SpecularColour = new ColourValue(0.4f, 0.4f, 0.4f);

        mSceneMgr.AmbientLight = new ColourValue(0.2f, 0.2f, 0.2f);

        // create the terrain
        mTerrainGlobals = new TerrainGlobalOptions();
        mTerrainGroup = new TerrainGroup(mSceneMgr, Terrain.Alignment.ALIGN_X_Z, 513, 12000.0f);
        mTerrainGroup.SetFilenameConvention("BasicTutorialTerrain3", "dat");
        mTerrainGroup.Origin = Vector3.ZERO;
        
        ConfigureTerrainDefaults(light);

        for (int x = 0; x <= 0; ++x)
        {
                for (int y = 0; y <= 0; ++y)
                {
                        DefineTerrain(x, y);
                }
        }
            
        mTerrainGroup.LoadAllTerrains(true);

        if (mTerrainImported)
        {
                foreach (TerrainGroup.TerrainSlot t in mTerrainGroup.GetTerrainIterator())
                {
                        InitBlendMaps(t.instance);
                }
        }

        mTerrainGroup.FreeTemporaryResources();
        mTerrainGroup.SaveAllTerrains(true);
}

Tip_icon.png Do not try to compile now - it won't work until we implement the terrain utility functions!

The ConfigureTerrainDefaults() method

The Ogre Terrain component is quite configurable. Create the ConfigureTerrainDefaults(Light light) function and add the following code to it:

// Configure global
mTerrainGlobals.MaxPixelError = 8;
// testing composite map
mTerrainGlobals.CompositeMapDistance = 3000;

First, we set two global options: MaxPixelError and CompositeMapDistance. MaxPixelError decides how precise our terrain is going to be. A lower number will mean a more accurate terrain, at the cost of performance (because of more vertices). CompositeMapDistance decides how far the Ogre terrain will render the lightmapped terrain.
Next, let's deal with the lightmapping, using our directional light:

// Important to set these so that the terrain knows what to use for derived (non-realtime) data
mTerrainGlobals.LightMapDirection = light.Direction;
mTerrainGlobals.CompositeMapAmbient = mSceneMgr.AmbientLight;
mTerrainGlobals.CompositeMapDiffuse = light.DiffuseColour;

It uses our light to set direction and diffuse colour and sets the diffuse colour to match our scene manager's ambient light.
Next we define some ImportData values:

// Configure default import settings for if we use imported image
Terrain.ImportData defaultimp = mTerrainGroup.DefaultImportSettings;

defaultimp.terrainSize = 513;
defaultimp.worldSize = 12000.0f; // due terrain.png is 8 bpp
defaultimp.inputScale = 600;
defaultimp.minBatchSize = 33;
defaultimp.maxBatchSize = 65;

We won't cover the what and how of those values in this tutorial, but terrainSize and worldSize are set to match our global sizes (what we told our TerrainGroup), and inputScale decides how the heightmap image is scaled up. We are using a scale here because images have limited precision (Note: You can use floating point raw heightmaps to avoid inputScaling, but those maps usually need some lossy data compression. In this case you can set inputScale = 1).
A raw heightmap, for instance, doesn't normally need scaling because the values are stored as an array of unscaled floats.
The last bit is our textures:

// textures
defaultimp.layerList.Add(new Terrain.LayerInstance());
defaultimp.layerList.Add(new Terrain.LayerInstance());
defaultimp.layerList.Add(new Terrain.LayerInstance());


defaultimp.layerList[0].worldSize = 100;
defaultimp.layerList[0].textureNames.Add("dirt_grayrocky_diffusespecular.dds");
defaultimp.layerList[0].textureNames.Add("dirt_grayrocky_normalheight.dds");

defaultimp.layerList[1].worldSize = 30;
defaultimp.layerList[1].textureNames.Add("grass_green-01_diffusespecular.dds");
defaultimp.layerList[1].textureNames.Add("grass_green-01_normalheight.dds");

defaultimp.layerList[2].worldSize = 200;
defaultimp.layerList[2].textureNames.Add("growth_weirdfungus-03_diffusespecular.dds");
defaultimp.layerList[2].textureNames.Add("growth_weirdfungus-03_normalheight.dds");

Here we set the number of terrain texture layers to 3, by adding three new LayerInstances. Then we initialise each layer by setting the 'worldSize' and by specifying the texture names. 'worldSize' decides how big each splat of textures is going to be. A smaller value will increase the resolution of the rendered texture layer.
The default material generator takes two textures per layer:

  1. diffuse_specular - diffuse texture with a specular map in the alpha channel
  2. normal_height - normal map with a height map in the alpha channel

See Ogre Terrain Textures if you want to know how these textures are made. You can download these six textures from the MogreSDK or directly.
Our entire ConfigureTerrainDefaults() function looks like this:

protected void ConfigureTerrainDefaults(Light light)
{
        // Configure global
        mTerrainGlobals.MaxPixelError = 8;
        // testing composite map
        mTerrainGlobals.CompositeMapDistance = 3000;

        // Important to set these so that the terrain knows what to use for derived (non-realtime) data
        mTerrainGlobals.LightMapDirection = light.Direction;
        mTerrainGlobals.CompositeMapAmbient = mSceneMgr.AmbientLight;
        mTerrainGlobals.CompositeMapDiffuse = light.DiffuseColour;

        // Configure default import settings for if we use imported image
        Terrain.ImportData defaultimp = mTerrainGroup.DefaultImportSettings;

        defaultimp.terrainSize = 513;
        defaultimp.worldSize = 12000.0f; // due terrain.png is 8 bpp
        defaultimp.inputScale = 600;
        defaultimp.minBatchSize = 33;
        defaultimp.maxBatchSize = 65;

        // textures
        defaultimp.layerList.Add(new Terrain.LayerInstance());
        defaultimp.layerList.Add(new Terrain.LayerInstance());
        defaultimp.layerList.Add(new Terrain.LayerInstance());
        
        defaultimp.layerList[0].worldSize = 100;
        defaultimp.layerList[0].textureNames.Add("dirt_grayrocky_diffusespecular.dds");
        defaultimp.layerList[0].textureNames.Add("dirt_grayrocky_normalheight.dds");

        defaultimp.layerList[1].worldSize = 30;
        defaultimp.layerList[1].textureNames.Add("grass_green-01_diffusespecular.dds");
        defaultimp.layerList[1].textureNames.Add("grass_green-01_normalheight.dds");

        defaultimp.layerList[2].worldSize = 200;
        defaultimp.layerList[2].textureNames.Add("growth_weirdfungus-03_diffusespecular.dds");
        defaultimp.layerList[2].textureNames.Add("growth_weirdfungus-03_normalheight.dds");
}

DefineTerrain() method

This is our DefineTerrain() function:

protected void DefineTerrain(int x, int y)
{
        string filename = mTerrainGroup.GenerateFilename(x, y);

        if (ResourceGroupManager.Singleton.ResourceExists(mTerrainGroup.ResourceGroup, filename))
                mTerrainGroup.DefineTerrain(x, y);
        else
        {
                Image img = new Image();
                GetTerrainImage(x % 2 != 0, y % 2 != 0, img);
                mTerrainGroup.DefineTerrain(x, y, img);
                mTerrainImported = true;
        }
}

This function is simple, but clever: First, it asks our TerrainGroup what file name it would use to generate the terrain. Then it checks if there is a file by that name in our resource group. If there is, it means that we generated a binary terrain data file already, and thus there is no need to import it from an image. If there isn't a data file present, it means we have to generate our terrain, so we load the image and use that to define it.

The function uses a small utility function called GetTerrainImage().

GetTerrainImage() method

protected void GetTerrainImage(bool flipX, bool flipY, Image img)
{
        img.Load("terrain.png", ResourceGroupManager.DEFAULT_RESOURCE_GROUP_NAME);
            
        if (flipX)
                img.FlipAroundX();

        if (flipY)
                img.FlipAroundY();
}

It loads 'terrain.png' from our resource locations, flipping it if necessary. Note: Flipping is done to imitate seamless terrain so you can make unlimited big terrain using single 513x513 heightmap, this is just a trick. If your terrain's heightmap is already seamless you don't have to do fliping, you just define individual heightmap for each Terrain. In this tutorial we use only 1x1 sized TerrainGroup (look at CreateScene() function) so this code is not actually used.

InitBlendMaps() method

Remember our three types of terrain layers, defined in ConfigureTerrainDefaults()? Now, we are going to blend these layers based on the HEIGHT of the tile. In a real project, you can use alpha-based splatting stored in RGBA channels in a file or files that are separate from the heightmap. This is the initBlendMaps function in its entirety:

protected unsafe void InitBlendMaps(Terrain terrain)
{
        TerrainLayerBlendMap blendMap0 = terrain.GetLayerBlendMap(1);
        TerrainLayerBlendMap blendMap1 = terrain.GetLayerBlendMap(2);

        float minHeight0 = 70, minHeight1 = 70;
        float fadeDist0 = 40, fadeDist1 = 15;

        float* pBlend1 = blendMap1.BlendPointer;

        for (int y = 0; y < terrain.LayerBlendMapSize; ++y)
                for (int x = 0; x < terrain.LayerBlendMapSize; ++x)
                {
                        float tx, ty;

                        blendMap0.ConvertImageToTerrainSpace((uint)x, (uint)y, out tx, out ty);
                    
                        float height = terrain.GetHeightAtTerrainPosition(tx, ty);
                        float val = (height - minHeight0) / fadeDist0;
                        val = Clamp(val, 0, 1);

                        val = (height - minHeight1) / fadeDist1;
                        val = Clamp(val, 0, 1);
                        *pBlend1++ = val;
                }

        blendMap0.Dirty();
        blendMap0.Update();
        blendMap1.Dirty();
        blendMap1.Update();
}

We won't go into the gritty details of how it works in this tutorial. Let's just say that it uses the terrain height to splat the three layers on the terrain. Note: Since Mogre.Math does for some reason not implement a Clamp() method we have to write our own. Don't worry, it's just a small couple of lines:

protected float Clamp(float value, float min, float max)
{
        if (value <= min)
                return min;
        else if (value >= max)
                return max;

        return value;
}

Cleaning up

Since it is good practise not to leave stuff behind when we are finished with it and our terrain is pretty big we want to delete the terrain when the application terminates. So simply add this method:

protected override void DestroyScene()
{
       mTerrainGroup.Dispose();
       mTerrainGlobals.Dispose();
}

Compile and run

Now you can compile and run your application. After some time you should get a nicely rendered terrain. If you run it a second time the program will execute faster (still some time). This is because we told the application to save the terrain after it is finished. The second time it only has to be loaded not generated.

Go ahead and look in your media folder. You should see a BasicTuorial3Terrain_00000000.dat file there...