Beginner Tutorial 3: Terrain, Sky, Fog, and the Root object
Original version by Clay Culver
Ported to VB.NET by Aeauseth
Any problems you encounter while working with this tutorial should be posted to the Mogre Forums.
Table of contents
This tutorial assumes you have knowledge of VB.NET programming and are able to setup and compile an Ogre application (if you have trouble setting up your application, see this guide for help). This tutorial builds on the previous tutorials, so be sure that you have already worked through them.
In this tutorial we will be exploring how to manipulate terrain, sky, and fog in your Ogre applications. After this tutorial you should understand the differences between Skyboxes, Skyplanes, and Skydomes and be able to use them. You will also know the difference between the different types of fog, and how to use it.
As you go through the tutorial you should be slowly adding code to your own project and watching the results as we build it.
As with the previous tutorials, we will be using a pre-constructed code:
Imports Mogre Module Module1 Public myKeyboard As MOIS.Keyboard Public myMouse As MOIS.Mouse Public myCamera As Camera Public MyWindow As RenderWindow Public myTranslation As Vector3 = Vector3.ZERO Public Quitting As Boolean = False Public myRotating As Boolean = False Sub Main() Try 'Initialization of Ogre Root and RenderWindow Dim myRoot As Root = New Root("Plugins.cfg", "ogre.cfg", "ogre.log") 'Show Ogre Rendering Subsystem setup dialog box If Not myRoot.RestoreConfig Then If Not myRoot.ShowConfigDialog Then Exit Sub End If End If 'Create an Ogre render window MyWindow = myRoot.Initialise(True, "OGRE Render Window") AddHandler myRoot.FrameStarted, AddressOf FrameStarted 'Create Ogre SceneManager Dim mySceneManager As SceneManager = myRoot.CreateSceneManager(SceneType.ST_EXTERIOR_CLOSE) 'Read Resources Dim cf As New ConfigFile cf.Load("resources.cfg", vbTab + ":=", True) Dim seci As ConfigFile.SectionIterator = cf.GetSectionIterator Dim secName As String, typeName As String, archName As String While (seci.MoveNext()) secName = seci.CurrentKey Dim settings As ConfigFile.SettingsMultiMap = seci.Current For Each pair As KeyValuePair(Of String, String) In settings typeName = pair.Key archName = pair.Value ResourceGroupManager.Singleton.AddResourceLocation(archName, typeName, secName) Next End While ResourceGroupManager.Singleton.InitialiseAllResourceGroups() 'Create Camera myCamera = mySceneManager.CreateCamera("Camera") myCamera.SetPosition(500, 100, 500) myCamera.LookAt(New Vector3(1000, 0, 1000)) myCamera.NearClipDistance = 5 'Viewport Dim myViewport As Viewport = MyWindow.AddViewport(myCamera) myViewport.BackgroundColour = ColourValue.Black myCamera.AspectRatio = myViewport.ActualWidth / myViewport.ActualHeight 'Keyboard Dim windowHnd As Integer MyWindow.GetCustomAttribute("WINDOW", windowHnd) Dim myInputManager As MOIS.InputManager = MOIS.InputManager.CreateInputSystem(windowHnd) myKeyboard = myInputManager.CreateInputObject(MOIS.Type.OISKeyboard, True) AddHandler myKeyboard.KeyPressed, AddressOf InputClass.KeyPressed AddHandler myKeyboard.KeyReleased, AddressOf InputClass.KeyReleased 'Mouse myMouse = myInputManager.CreateInputObject(MOIS.Type.OISMouse, True) AddHandler myMouse.MouseMoved, AddressOf InputClass.MouseMovedListener AddHandler myMouse.MousePressed, AddressOf InputClass.MousePressedListener AddHandler myMouse.MouseReleased, AddressOf InputClass.MouseReleasedListener 'Load Terrain mySceneManager.SetWorldGeometry("terrain.cfg") 'Sky 'Fog 'Start rendering myRoot.StartRendering() Catch ex As System.Runtime.InteropServices.SEHException If OgreException.IsThrown Then MsgBox(OgreException.LastException.FullDescription, MsgBoxStyle.Critical, _ "An Ogre exception has occured!") Else MsgBox(ex.ToString, "An error has occured") End If End Try End Sub Public Function FrameStarted(ByVal e As FrameEvent) As Boolean 'Capture buffered input myKeyboard.Capture() myMouse.Capture() 'Handle player/camera movement InputClass.ProcessKeyboard() myCamera.Position += myCamera.Orientation * myTranslation * e.timeSinceLastFrame Return Not Quitting End Function Public Class InputClass Const TRANSLATE As Single = 200 Const ROTATE As Single = 0.003 Shared Function KeyPressed(ByVal e As MOIS.KeyEvent) As Boolean Select Case e.key Case MOIS.KeyCode.KC_ESCAPE Quitting = True End Select Return Nothing End Function Shared Function KeyReleased(ByVal e As MOIS.KeyEvent) As Boolean 'This function is just a placeholder 'It is unlikely you will ever use this 'Tyipcally you either process unbuffered keyboard input (as in ProcessKeyboard) 'or you process buffered Keypress Return Nothing End Function Shared Sub ProcessKeyboard() 'Clear previous translation myTranslation.z = 0 myTranslation.x = 0 myTranslation.y = 0 If myKeyboard.IsKeyDown(MOIS.KeyCode.KC_UP) Or _ myKeyboard.IsKeyDown(MOIS.KeyCode.KC_W) Then myTranslation.z += -TRANSLATE End If If myKeyboard.IsKeyDown(MOIS.KeyCode.KC_S) Or _ myKeyboard.IsKeyDown(MOIS.KeyCode.KC_DOWN) Then myTranslation.z += TRANSLATE End If If myKeyboard.IsKeyDown(MOIS.KeyCode.KC_A) Or _ myKeyboard.IsKeyDown(MOIS.KeyCode.KC_LEFT) Then myTranslation.x += -TRANSLATE End If If myKeyboard.IsKeyDown(MOIS.KeyCode.KC_D) Or _ myKeyboard.IsKeyDown(MOIS.KeyCode.KC_RIGHT) Then myTranslation.x += TRANSLATE End If If myKeyboard.IsKeyDown(MOIS.KeyCode.KC_Q) Or _ myKeyboard.IsKeyDown(MOIS.KeyCode.KC_PGUP) Or _ myKeyboard.IsKeyDown(MOIS.KeyCode.KC_SPACE) Then myTranslation.y += TRANSLATE End If If myKeyboard.IsKeyDown(MOIS.KeyCode.KC_Z) Or _ myKeyboard.IsKeyDown(MOIS.KeyCode.KC_PGDOWN) Then myTranslation.y += -TRANSLATE End If End Sub Shared Function MouseMovedListener(ByVal e As MOIS.MouseEvent) As Boolean Static myLastX As Integer = e.state.X.abs Static myLastY As Integer = e.state.Y.abs If myRotating Then myCamera.Yaw(e.state.X.rel * -ROTATE) myCamera.Pitch(e.state.Y.rel * -ROTATE) End If End Function Shared Function MousePressedListener(ByVal e As MOIS.MouseEvent, ByVal id As MOIS.MouseButtonID) As Boolean If e.state.ButtonDown(MOIS.MouseButtonID.MB_Right) Then myRotating = True End If End Function Shared Function MouseReleasedListener(ByVal e As MOIS.MouseEvent, ByVal id As MOIS.MouseButtonID) As Boolean If Not e.state.ButtonDown(MOIS.MouseButtonID.MB_Right) Then myRotating = False End If End Function End Class End Module
In this demo we will be rendering Terrain in Ogre. To do this we need to use the TerrainSceneManager instead of the default one. Notice the change from ST_GENERIC to ST_EXTERIOR_CLOSE:
'Create Ogre SceneManager Dim mySceneManager As SceneManager = myRoot.CreateSceneManager(SceneType.ST_EXTERIOR_CLOSE)
The Root object (mRoot is an instance of Root) is the "core" Ogre object. You can see a UML diagram of the relationships between Ogre objects here. You have now seen almost all of these objects in practice, with the exception of the RenderSystem. In this chunk of code, we are telling the Root node that we want a SceneManager of the ST_EXTERIOR_CLOSE type. The Root object then queries the SceneManagerEnumerator to find the SceneManager of the type you requested and returns it.
After your application is set up, you rarely ever have deal with Ogre's Root object, and you don't ever interact with the SceneManagerEnumerator directly.
I would like to go ahead and talk to you about SceneManager creation and storage to save you the confusion in the future. SceneManagers are not Singletons. You can create as many of them as you want, and unlike SceneNodes/Lights/etc you can create them directly with a "new SceneManager()" statement (you do not have to use Root's getSceneManager method). You can have multiple SceneManagers populated with multiple separate geometries and entities at the same time. You can swap between any of these at any time by recreating the Viewport (this is covered in Mogre Intermediate Tutorial 4) or display multiple SceneManagers at the same time using multiple Viewports.
Why do we use the CreateSceneManager function instead of creating our SceneManager object manually? Well, the plugin system in Ogre gives us a great deal of flexibility when working with single SceneManagers. There are only a few scene types defined in the SceneType enum. Until now, the MogreFramework has been choosing ST_GENERIC as our SceneManager. You might think that this is the base SceneManager class, but as long as you did not fiddle with the plugins.cfg file, then that's not what you have been using! The OctreeSceneManager registers itself as ST_GENERIC and overrides the base SceneManager class if you are using the OctreeSceneManager plugin. The OctreeSceneManager uses a system of culling items that are not actually on the Scene (and thus it's generally faster than the regular SceneManager). If you removed the OctreeSceneManager plugin from your plugins.cfg you would *probably* be using the basic SceneManager when you request ST_GENERIC.
This is pretty neat, but you can run into some problems. Especially considering the fact that you aren't guaranteed to get the SceneManager you ask for (some plugins conflict and try to overwrite the same ST_* type), but this rarely happens in practice. Normally if you need to do advanced things with SceneManagers then you should create them yourself.
Now that we have that cleared up, time to actually create Terrain. The base SceneManager defines the SetWorldGeometry method, which subclasses use for most scene creation purposes. With the TerrainSceneManager class, it expects a filename from which to load a terrain configuration.
'Load Terrain mySceneManager.SetWorldGeometry("terrain.cfg")
Compile and run your program. It's that easy.
There are many options in the terrain.cfg file, and I am only going to cover the most basic for changing the images used to generate the terrain. A more detailed explanation of the terrain config file can be found here. One major thing to note about the TerrainSceneManager is that it has been designed with paging functionality in mind, but it has not been implemented yet. Paging terrain is a system where the terrain is broken into chunks, and only displayed when the user would be able to see it. This allows you define a huge world and be able to use it without dropping the framerate by a significant amount. There is an Ogre plugin that does this: Paging Scene Manager.
The TerrainSceneManager uses Heightmaps to generate terrain. You can specify the heightmap you want to use by setting the "Heightmap.image" property. You can set the texture that is used for the terrain by setting the WorldTexture property. The terrain scene manager also allows you to specify a "DetailTexture" property, which is interlaced with the WorldTexture to make the terrain look more realistic. You should find each of the images currently specified by terrain.cfg and take a look at them (they should be in the Media/materials/textures folder).
Details on how to create heightmaps have been discussed ad nauseum on the forums. Search for heightmap and you are sure to find something that you are looking for.
We just spent the entire previous tutorial going over lights and shadows, but the bad news is it's not easy to get this to work in the TerrainSceneManager. At a later date I may devote a full tutorial to getting this working with the TerrainSceneManager. For now, just know that it's much easier to take the detail texture and add lighting effects to it than it is to get standard lighting working. We will also go over a way to do "Fake Darkness" in the Fog section. If you are looking to use lighting with the terrain, you should look into using the Paging Scene Manager, since it has better support for these features.
A SkyBox is basically a giant cube that surrounds all of the objects in the scene. The best way to describe it is to just show it to you. Add this line of code:
'Sky mySceneManager.SetSkyBox(True, "Examples/SpaceSkyBox")
Compile and run the program. Neat huh? (Note the SkyBox is grainy because the actual texture is low resolution; a higher resolution SkyBox would look much better.) There are several useful parameters for SkyBoxes that we can set when calling SetSkyBox. The first option is whether or not to enable the SkyBox. If you want to later disable the SkyBox simply call 'mySceneManager.setSkyBox( False, "" )'. The second parameter is the material script to use for the SkyBox.
The third parameter and fourth parameters to setSkyBox are fairly important to understand. The third parameter sets the distance that the SkyBox is away from the Camera, and the fourth parameter sets whether or not the SkyBox is drawn before the rest of the scene or afterwards. So, lets see what happens when you change the distance parameter for the SkyBox from the default 5000 units to something very close:
mySceneManager.SetSkyBox(True, "Examples/SpaceSkyBox", 10)
Nothing changed! This is because the fourth parameter that controls whether to draw the SkyBox first or not is set to true by default. If the SkyBox is drawn first, then anything rendered afterwards (like our Terrain) will be drawn on top of it, thus making the SkyBox always appear in the background. (Note that you shouldn't set the distance above to be closer than the near clip distance on the Camera or it will not be shown!) It is not actually desirable to draw the SkyBox first, because the full thing is rendered. When you draw it last, only the visible portions are drawn, which will provide a modest speed improvement. So, lets try setting our SkyBox to be drawn last:
mySceneManager.SetSkyBox(True, "Examples/SpaceSkyBox", 5000, False)
Again, this looks just like it did before, but now the parts of the SkyBox that are not visible won't be rendered. There is one thing you have to be careful about when using this technique though. If you set the SkyBox to be too close, you could be cutting part of the scene geometry off. For example, try this:
mySceneManager.SetSkyBox(True, "Examples/SpaceSkyBox", 100, True)
As you can see now, the terrain "pokes through" the SkyBox. Definitely not what we want. If you use SkyBoxes in your application you will have to decide how you want to use them. The speedup you get from rendering the SkyBox after the terrain is very modest, and you have to be careful not to obscure your geometry (unless that is what you are going for). Generally speaking, leaving everything past the second parameter as default is a very safe choice.
SkyDomes are very similar to SkyBoxes, and you use them by calling setSkyDome A giant cube is created around the Camera and rendered onto, but the bigest difference is the texture is "projected" onto the SkyBox in a spherical manner. You are still looking at a cube, but it looks as if the texture is wrapped around the surface of a sphere. The primary drawback to this method is that the bottom of the cube will be untextured, so you always need to have some type of terrain that hides the base.
The example texture that Ogre provides for SkyDomes will let you see this clearly. Clear out the setSkyBox call from createScene and add this code instead:
mySceneManager.SetSkyDome(True, "Examples/CloudySky", 5, 8)
When you run this, move the Camera to the dead center of the terrain and move the Camera so that's positioned fairly close to the surface of the terrain (this looks the best). After looking at this, hit the R button to switch to the mesh view. As you can see, we are still looking at a cube (without the base), but it looks as if the clouds are wrapped around a sphere at the top. (Also note that the movement of the clouds is a property of the "Examples/CloudySky" material, not of SkyDomes in general.)
The first two paramaters of setSkyDome are the same as setSkyBox, and you can turn the SkyDome off by calling 'win.SceneManager.SetSkyDome(false, "");'. The third parameter is the curvature used for the SkyDome. The API reference suggests using values between 2 and 65; lower for better distance effect, but higher values for less distortion and a smoother effect. Try setting the third paramater to 2 and 64 and look at the difference. The distance effect that the API reference was referring to can be clearly seen in these screenshots. This is setting the curvature to 2:
This is setting the curvature to 64:
The fourth parameter is the number of times the texture is tiled, which you will need to tweak depending on the size of your texture. Be sure to note that this parameter is a Real value (floating point) and not an integer. You can tile it 1.234 times, if that's what looks good for your application. The fifth and sixth parameters are distance and drawFirst, respectively, which we have already covered in the SkyBox section.
SkyPlanes are very different from SkyBoxes and SkyDomes. Instead of a cube to render the sky texture on, we use just a single plane. (Note for all of the following SkyPlane configurations you need to be somewhere towards the middle of the terrain and close to the ground.) Clear out all SkyDome code from createScene. The first thing we are going to do is create a plane, and face it downwards. The setSkyPlane method that we will be calling does not have a distance parameter like SkyBox and SkyPlane. Instead that parameter is set in the d variable of Plane:
Dim myPlane As Plane myPlane.d = 1000 myPlane.normal = Vector3.NEGATIVE_UNIT_Y
Now that we have the plane defined, we can create the SkyPlane. Note that the fourth parameter is the size of the SkyPlane (in this case 1500x1500 units) and the fifth parameter is how many times to tile the texture:
mySceneManager.SetSkyPlane(True, myPlane, "Examples/SpaceSkyPlane", 1500, 75)
Compile and run the program. There are two problems with the SkyPlane this creates here. First of all, the texture that is used is too low resolution, and it doesn't tile well. That could be fixed by simply creating a good, high resolution sky texture that tiles well. However, the primary problem with this technique is that if you look towards the horizon, you can see where the SkyPlane ends. Even if you had a good texture, it would not look good at all if you can see to the horizon. This basic use of a SkyPlane is really only useful when you have high walls (or hills) all around the viewpoint. Using a SkyPlane in that situation would be considerably less graphics intensive than creating a full SkyBox/SkyDome.
Fortunately, that is not all we can do with a SkyPlane. The sixth parameter to the skyplane is the familiar "renderFirst" parameter which we have already covered in the SkyBox and SkyDome sections. The seventh parameter allows you to specify the curvature of the SkyPlane, so that we are no longer using a plane, but a curved surface instead. We also have to now set the number of x and y segments used to create the SkyPlane (initially the SkyPlane was one big square, but if we want curvature we need to have the plane made up of smaller squares). The eighth and ninth parameters to the function are the number of x and y segments, respectively:
mySceneManager.SetSkyPlane(True, myPlane, "Examples/SpaceSkyPlane", _ 1500, 50, True, 1.5, 150, 150)
Compile and run the application. Now our SkyPlane looks much better, though again the tiling could use some work. You could also use this with the cloud material instead:
mySceneManager.SetSkyPlane(True, myPlane, "Examples/CloudySky", _ 1500, 50, True, 1.5, 150, 150)
Compile and run the application. The motion of the clouds and the way it is tiled seems to make it look slightly worse than a SkyDome, especially when you get near the edge of the Terrain and look out onto the horizon.
One other note, you can clear the SkyPlane by calling 'mySceneManager.SetSkyPlane(False, New Plane(), "")'
Which sky to use depends entirely on your application. If you have to see all around you, even in the negative y direction, then really your only real choice is to use a SkyBox. If you have terrain, or some kind of floor which blocks the view of the negative y direction, then using a SkyDome seems to give more realistic results. For areas where you cannot see to the horizon (such as a valley surrounded by mountains on all sides, or the inner courtyard of a castle), a SkyPlane will give you very good looking results for very little GPU costs. The primary reason to use a SkyPlane, as we will see in the next section, is because it plays nicely with fog effects.
These are only suggestions. For your application you should experiment and use whatever looks the best.
Fog in Ogre is very easy to use. There is one caveat that you need to know about before you try to use fog in your program. When you use the TerrainSceneManager, you must be careful to call the SetFog function before the SetWorldGeometry function. (In other SceneManagers it generally doesn't matter). Depending on which is called first, a different vertex program will be chosen to create the fog and terrain.
Before we get started, clear out all contents of the createScene function except for the call to setWorldGeometry.
The most important thing to know about setting fog is that it doesn't actually create a fog entity in empty space as you might imagine you would. Instead, fog is merely a filter applied to whatever objects you are currently looking at. This has some interesting implications. The most relevant of which is that when you stare off into nothingness (IE when you are not looking at an object), you do not see fog. In fact, you only see whatever the viewport background color is. So, in order to have fog look correct, we have to set the background to whatever the fog color currently is.
There are two basic types of fog: linear and exponential. Linear fog gets thicker in a linear fashion, while exponential fog gets thicker exponentially (every distance unit the fog thickness increases by more than it did the previous distance unit). It's easier to see the difference than to explain it, so on to the examples.
The first type of fog we will look at is linear, and it's the easiest fog to understand. The first thing we are going to do after we call SetWorldGeometry is set the viewport's background color. We could do this by overriding the CreateViewport function (like we did in the last tutorial), but sometimes we need to set it without recreating the viewport every time. This is how we do that:
'Fog Dim MyFadeColor As ColourValue = New ColourValue(0.9, 0.9, 0.9) myViewport.BackgroundColour = MyFadeColor
Once we set the background color, we can now create the fog:
mySceneManager.SetFog(FogMode.FOG_LINEAR, MyFadeColor, 0, 50, 500)
The first parameter to the SetFog function is the type of fog (in this case, linear). The second parameter to SetFog is the color of the fog we are using (in this case a very very light grey or "WhiteSmoke"). The third parameter is not used in linear fog. The fourth and fifth parameters specify the range where the fog gets thicker. In this case we have set the fog starting point to be 50 and the stopping point to be 500. This means that from 0 to 50 units in front of the camera, there is no fog. From 50 to 500 units away from the Camera, the fog gets thicker in a linear fashion. At 500 units away from the Camera, you can no longer see anything other than fog. Compile and run the application.
Another type of fog that we can use is exponential fog. Instead of setting starting and stopping bounds for fog, we instead set a density for the fog (the fourth and fifth parameters are unused). Replace the previous call to setFog with this:
mySceneManager.SetFog(FogMode.FOG_EXP, MyFadeColor, 0.005)
Compile and run the application. If you are using the DirectX Renderer you may find it completely fogged out, calling setFog after setWorldGeometry fixes this. The OpenGL Renderer behaves as documented. This creates a different look to the fog that is generated. There is also another exponential fog function which is more severe than the first one (IE fog gets much thicker each unit you move away from the Camera compared to the first fog function). Note that there is more fog-per-density when using FOG_EXP2. Replace the previous call to setFog with this:
mySceneManager.SetFog(FogMode.FOG_EXP2, MyFadeColor, 0.003)
Compile and run the application again. Fog is mostly interchangeable between the three functions that Ogre provides. You should experiment with all three fog functions and see which looks best in your application.
You can run into some interesting problems when trying to use fog with a SkyBox and SkyDome. Since SkyDomes and SkyBoxes are just cubes, using them with fog is problematic since fog works in a spherical manner. Clear out the contents of the createScene method. If we cleverly choose our SkyDome and fog parameters, we can see the problem directly:
Dim MyFadeColor As ColourValue = New ColourValue(0.9, 0.9, 0.9) myViewport.BackgroundColour = MyFadeColor mySceneManager.SetFog(FogMode.FOG_LINEAR, MyFadeColor, 0, 50, 515) mySceneManager.SetSkyDome(True, "Examples/CloudySky", 5, 8, 500)
Compile and run the application. If you move the camera around, you will see different portions of the SkyDome poke through the fog depending on what part of the SkyDome you are looking at (notice the blue coming through on the sides, but not in the middle).
This is certainly not what we want. Another option is to use a SkyPlane instead. Replace the code in createScene with this:
Dim MyFadeColor As ColourValue = New ColourValue(0.9, 0.9, 0.9) myViewport.BackgroundColour = MyFadeColor mySceneManager.SetFog(FogMode.FOG_LINEAR, MyFadeColor, 0, 50, 515) Dim myPlane As Plane myPlane.d = 100 myPlane.normal = Vector3.NEGATIVE_UNIT_Y mySceneManager.SetSkyPlane(True, myPlane, "Examples/CloudySky", _ 500, 20, True, 0.5, 150, 150)
This looks correct. If we look upwards we can see sky (which is the case in real life if the fog is just right), but it's not poking through in funny ways. No matter if you use curavature or not, this solves our problem of the user being able to see the horizon where the SkyPlane does not look right.
You may not want to use sky at all when you set fog, because if the fog is thick enough you cannot see the sky anyway. The trick with fog that we described above allows us to perform a nifty graphic hack that can be useful in some cases. Instead of setting the fog to a bright color, lets set it to be very dark and see what happens (note we have set the SkyPlane to be only 10 units away from the camera, which is before the fog sets in):
Dim MyFadeColor As ColourValue = New ColourValue(0.1, 0.1, 0.1) myViewport.BackgroundColour = MyFadeColor mySceneManager.SetFog(FogMode.FOG_LINEAR, MyFadeColor, 0, 10, 150) Dim myPlane As Plane myPlane.d = 10 myPlane.normal = Vector3.NEGATIVE_UNIT_Y mySceneManager.SetSkyPlane(True, myPlane, "Examples/SpaceSkyPlane", _ 100, 45, True, 0.5, 150, 150)
Compile and run the application.
Not too terrible. Of course, once you are able to, you should use proper lighting instead of this hack, but it does show the flexibility of fog, and some of the interesting things you can do with the engine. Using black fog might also be an interesting way to do a "blindness" or "darkness" spell effect if you are writing a game that uses first-person view.
- Proceed to Basic Tutorial 4 Frame Listeners and Windows.Forms Input