Basic Tutorial 2 (Cameras, Lights, and Shadows)

From Axiom

Show code samples in

Prerequisites

This tutorial assumes you have knowledge of C#, VB.Net, Python, or another .NET language, though only the mentioned languages will have sample code.
This tutorial also build off the First Tutorial

Getting Started

As with the last tutorial, we will be using the TechDemo class as our starting point. We will add two more methods to our Tutorial class: CreateViewport and CreateCamera. These two methods are virtual methods of the TechDemo class, but in this tutorial we will now look at them to see how Cameras and Viewports are actually created and used.

Add overrides of these methods to your tutorial class:

protected override void CreateCamera()
{
}

protected override void CreateViewports()
{
}

Protected Overrides Sub CreateCamera()
End Sub

Protected Overrides Sub CreateViewports()
End Sub

def CreateCamera(self):
        pass
def CreateViewports(self):
        pass

Cameras

A Camera is used to view the scene. A Camera is a special object which works somewhat like a SceneNode does. The Camera object has a Position property, as well as Yaw, Roll, and Pitch methods, and you can optionally attach it to any SceneNode. Just like SceneNodes, a Camera's position is relative to its parents (it's nice to respect one's elders). For all movement and rotation, you can basically consider a Camera a SceneNode.

One thing about Axiom Cameras that is different from what you might expect, is that you should only be using one Camera at a time (for now). In other words, we don't create multiple cameras for viewing different portions of the scene and then enabling or disabling to switch between them. Instead the way to accomplish this is to create SceneNodes which act as "camera holders". These SceneNodes simply sit in the scene and point at what the Camera might want to look at. When it is time to display a portion of the Scene, the Camera is simply attached to the appropriate SceneNode. We will revisit this technique in the FrameListener tutorial.

Finally, note that we are overriding TechDemo's default creation of the camera (we don't call base.CreateCamera(). If we didn't do that TechDemo would have created one for us by default.

Creating a Camera

First we will be overriding the default camera creation of the framework. Since Cameras are tied to the SceneManager which they reside in, we use the SceneManager object to create them. Find or add an override of the CreateCamera method and add the following code to it:

camera  =  scene.CreateCamera("PlayerCam");

camera  =  scene.CreateCamera("PlayerCam")

camera  =  self.scene.CreateCamera('PlayerCam')

This creates a Camera with the name "PlayerCam". You can use SceneManager's GetCamera method to get a Camera by its name if you decide not to hold a reference to it. Note that the TechDemo class provides us with the variable called 'camera' that holds the current camera, which is where we assigned the newly created camera object.

The next thing we are going to do is set the position of the Camera and the direction that it's facing. We will be placing objects around the origin, so we'll put the Camera a good distance in the +z direction and have the Camera face the origin. Add the following code to your CreateCamera method:

camera.Position = new Vector3(0, 10, 500);
camera.LookAt(Vector3.Zero);

camera.Position = New Vector3(0, 10, 500
camera.LookAt(Vector3.Zero)

self.camera.Position = Vector3(0, 10, 500)
self.camera.LookAt(Vector3.Zero)

The LookAt method is pretty nifty. You can have the Camera face any position you want to instead of having to Yaw, Rotate, and Pitch your way there. SceneNodes have this function as well, which can make setting Entities facing the right direction much easier in many cases.

Finally we will set a near clipping distance of 5 units. The clipping distance of a Camera specifies how close or far something can be before you no longer see it. Setting the near clipping distance makes it easier to see through Entities on the screen when you are very close to them. The alternative is being so close to an object that it fills the screen and you can't see anything but a tiny portion of it. You can also set the far clipping distance as well. This will stop the engine from rendering anything farther away than the given value. This is primarily used to increase the framerate if you are rendering large amounts of things on the screen for very long distances. To set the near clipping distance, add the following line to your CreateCamera method:

camera.Near = 5;

camera.Near = 5

self.camera.Near = 5

You can also change the far clipping distance by setting the Far property (though you should not use a far clip distance with Stencil Shadows, which we will be using in this tutorial).

Viewports

When you start dealing with multiple Cameras, the concept of a Viewport class will become much more useful to you. However, we are bringing this topic up now because it is important for you to understand how Axiom decides which Camera to use when rendering a scene. It is possible to have multiple SceneManagers running at the same time or to split the screen up into multiple areas, and have separate cameras render to separate areas on the screen (think of a split view for 2 players in an Xbox game, for example). While it is possible to do these things, we will not be covering how to do them until the advanced tutorials.

To understand how Axiom renders a scene, consider three of Axiom's constructs: the Camera, the SceneManager, and the RenderWindow. The RenderWindow we have not covered, but it is basically the window in which everything is displayed. The SceneManager object creates Cameras to view the scene. You must tell the RenderWindow which Cameras to display on the screen, and what portion of the window to render it in. The area in which you tell the RenderWindow to display the Camera is your Viewport. Under most typical uses of Axiom, you will generally create only one Camera, register the Camera to use the entire RenderWindow, and thus only have one Viewport object.

In this tutorial we will go over how to register the Camera to create the Viewport. We can then use this Viewport object to set the background color of the scene we are rendering.

Creating a Viewport

We will be overriding TechDemo's creation of the viewport. To create the Viewport we simply call the AddViewport method of RenderWindow and supply it with the Camera we are using. Find or add an override of the CreateViewports method and add the following code to it:

Viewport viewport = window.AddViewport(camera);
viewport.BackgroundColor = ColorEx.Black;
camera.AspectRatio = viewport.ActualWidth / viewport.ActualHeight;

Dim viewport as Viewport = window.AddViewport(camera)
viewport.BackgroundColor = ColorEx.Black
camera.AspectRatio = viewport.ActualWidth / viewport.ActualHeight

viewport = window.AddViewport(camera)
viewport.BackgroundColor = ColorEx.Black
self.camera.AspectRatio = viewport.ActualWidth / viewport.ActualHeight;

Alright, so what did we do here? First, we created a viewport by using window.AddViewport() and passed it our camera. Second we made the background color black. This color is what is seen when there's not an Entity being rendered. And last we set the AspectRatio, which is needed if the window is resized. Alternatively camera.AutoAspectRatio can be be set to True.

Shadows in Axiom

Axiom currently supports three types of Shadows:

Modulative Texture Shadows (ShadowTechnique.TextureModulative) - The least computationally expensive of the three. This creates a black and white
render-to-texture of shadow casters, which is then applied to the scene.
Modulative Stencil Shadows (ShadowTechnique.StencilModulative) - This technique renders all shadow volumes as a modulation after all non-transparent
objects have been rendered to the scene. This is not as intensive as Additive Stencil Shadows, but it is also not as accurate.
Additive Stencil Shadows (ShadowTechnique.StencilAdditive) - This technique renders each light as a separate additive pass on the scene.
This is very hard on the graphics card because each additional light requires an additional pass at rendering the scene.

Axiom does not support soft shadows as part of the engine. If you want soft shadows you will need to write your own vertex and fragment programs. Note that this is just a quick introduction here - the Ogre manual fully describes shadows in Ogre (and therefore, Axiom) and the implications of using them.

Adding the Shadows

Using shadows in Axiom is relatively simple. The SceneManager class has a ShadowTechnique property that we can use to set the type of Shadows we want. Then whenever you create an Entity, set the CastShadows property to set whether or not it casts shadows.

We will now set the ambient light to complete darkness and then set the shadow type. Add the following code to your CreateScene method:

scene.AmbientLight   = ColorEx.Black;
scene.ShadowTechnique = ShadowTechnique.StencilAdditive;

scene.AmbientLight  = ColorEx.Black
scene.ShadowTechnique = ShadowTechnique.StencilAdditive

self.scene.AmbientLight   = ColorEx.Black
self.scene.ShadowTechnique = ShadowTechnique.StencilAdditive;

You'll also need to add Axiom.Graphics to your usings/imports

Now the SceneManager uses additive stencil shadows. Lets create an object on the scene and make it cast shadows.

Entity ent = scene.CreateEntity("ninja", "ninja.mesh");
ent.CastShadows = true;
scene.RootSceneNode.CreateChildSceneNode().AttachObject(ent);

Dim ent as Entity = scene.CreateEntity("ninja", "ninja.mesh")
ent.CastShadows = true
scene.RootSceneNode.CreateChildSceneNode().AttachObject(ent)

ent =  self.scene.CreateEntity("ninja", "ninja.mesh")
ent.CastShadows = True
scene.RootSceneNode.CreateChildSceneNode().AttachObject(ent)

We also need something for the Ninja to stand on (so that he has something to cast shadows onto). To do this we will create a simple plane. This is not meant to be a tutorial on using MeshManager, but we will go over the very basics since we have to use it to create a plane. First we need to define the Plane object itself, which is done by supplying a normal and the distance from the origin. We could (for example) use planes to make up parts of world geometry, in which case we would need to specify something other than 0 for our origin distance. For now we just want a plane to have the positive y axis as its normal (that means we want it to face up), and no distance from the origin:

Plane plane = new Plane(Vector3.UnitY, 0);

Dim plane as Plane = New Plane(Vector3.UnitY, 0)

plane = Plane(Vector3.UnitY, 0)

Now we need to register the plane so that we can use it in our application. The MeshManager class keeps track of all the meshes we have loaded into our application (for example, this keeps track of the ogreHead.mesh and the ninja.mesh that we have been using). The CreatePlane member function takes in a Plane definition and makes a mesh from the parameters. This registers our plane for use:

 MeshManager.Instance.CreatePlane("ground",
        ResourceGroupManager.DefaultResourceGroupName, plane,
        1500, 1500, 20, 20, true, 1, 5, 5, Vector3.UnitZ);

 MeshManager.Instance.CreatePlane("ground",
        ResourceGroupManager.DefaultResourceGroupName, plane,
        1500, 1500, 20, 20, True, 1, 5, 5, Vector3.UnitZ)

 MeshManager.Instance.CreatePlane("ground",
        ResourceGroupManager.DefaultResourceGroupName, plane,
        1500, 1500, 20, 20, True, 1, 5, 5, Vector3.UnitZ)

Again, we are not going to delve into the specifics of how to use the MeshManager just yet (consult the API reference if you want to see exactly what each parameter is doing). Basically we have registered our plane to be 1500 by 1500 in size and new mesh is called "ground". Now, we can create an Entity from this mesh and place it on the scene:

Entity groundEnt = scene.CreateEntity("GroundEntity", "ground");
scene.RootSceneNode.CreateChildSceneNode().AttachObject(groundEnt);

Dim groundEnt as Entity = scene.CreateEntity("GroundEntity", "ground")
scene.RootSceneNode.CreateChildSceneNode().AttachObject(groundEnt)

groundEnt = self.scene.CreateEntity("GroundEntity", "ground")
self.scene.RootSceneNode.CreateChildSceneNode().AttachObject(groundEnt)

Neat huh? There are two more things we need to do with our ground before we are finished with it. The first is to tell the SceneManager that we don't want it to cast shadows since it is what's being used for shadows to project on. The second thing is we need to put a texture on it. Our ogreHead and ninja meshes already have material scripts defined for them. When we manually created our ground mesh, we did not specify what texture to use on it. We will use the "Examples/Rockwall" material script that Ogre includes with its samples:

groundEnt.SetMaterialName("Examples/Rockwall");
groundEnt.CastShadows = false;

groundEnt.SetMaterialName("Examples/Rockwall")
groundEnt.CastShadows = False

groundEnt.MaterialName ="Examples/Rockwall";
groundEnt.CastShadows = False

Now that we have a Ninja and ground in the scene, let's compile and run the program. We see... nothing! What's going on? In the previous tutorial we added Ogre heads and they displayed fine. The reason the Ninja doesn't show up is because the scene's ambient light has been set to total darkness. So let's add a light to see what is going on.

Lights In Axiom

There are three types of lighting that Ogre provides.

Point (LightType.Point) - Point light sources emit light from them in every direction.
Spotlight (LightType.Spotlight) - A spotlight works exactly like a flashlight does. You have a position where the light starts,
and then light heads out in a direction. You can also tell the light how large of an angle to use for the inner circle of light and the outer circle of light
(you know how flashlights are brighter in the center, then lighter after a certain point?).
Directional (LightType.Directional) - Directional light simulates far-away light that hits everything in the scene from a direction.
Let's say you have a night time scene and you want to simulate moonlight. You could do this by setting the ambient light for the scene, but that's not exactly
realistic since the moon does not light everything equally (neither does the sun). One way to do this would be to set a directional light and point in the direction the
moon would be shining.

Lights have a wide range of properties that describes how the light looks. Two of the most important properties of a light are its DiffuseColor and SpecularColor color. Each material script defines how much diffuse and specular lighting the material reflects, which we will learn how to control in a later tutorial.

Creating the Lights

To create a Light in Axiom we call SceneManager's CreateLight method and supply the light's name, very much like how we create an Entity or Camera. After we create a Light, we can either set the position of it manually or attach it to a SceneNode for movement. Unlike the Camera object, light only has Position and Direction and not the full suite of movement functions like Translate, Pitch, Yaw, Roll, etc. So if you need to create a stationary light, you should use the Position property. If you need the light to move (such as creating a light that follows a character), then you should attach it to a SceneNode instead.

So, let's start with a basic point Light. The first thing we will do is create the light, set its type, and set its position:

Light pointLight = scene.CreateLight("pointLight");
pointLight.Type     = LightType.Point;
pointLight.Position = new Vector3(0, 150, 250);

Dim pointLight as Light = scene.CreateLight("pointLight")
pointLight.Type = LightType.Point
pointLight.Position = New Vector3(0, 150, 250)

pointLight = self.scene.CreateLight("pointLight")
pointLight.Type     = LightType.Point
pointLight.Position = Vector3(0, 150, 250)

Now that we have created the light, we can set its Diffuse(external link) and Specular(external link) color. Let's make it red:

pointLight.DiffuseColor  = ColorEx.Red;
pointLight.SpecularColor = ColorEx.Red;

pointLight.DiffuseColor  = ColorEx.Red;
pointLight.SpecularColor = ColorEx.Red;

pointLight.DiffuseColor  = ColorEx.Red
pointLight.SpecularColor = ColorEx.Red

Now compile and run the application. Success! We can now see the Ninja and he casts a shadow. Be sure to also look at him from the front, a complete silhouette. One thing to notice is that you do not "see" the light source. You see the light it generates but not the actual light object itself. Many of Axiom's tutorials add a simple entity to show where the light is being emitted from. If you are having trouble with lights in your application you should consider creating something similar to what they do so you can see exactly where your light is.

Next, let's try out directional light. Notice how the front of the ninja is pitch black? Let's add a small amount of yellow directional light that is shining towards the front of his body. We create the light and set the color just like we do for a point light:

Light directionalLight = scene.CreateLight("directionalLight");
directionalLight.Type  = LightType.Directional;
directionalLight.DiffuseColor  = ColorEx.Yellow;
directionalLight.SpecularColor = ColorEx.Yellow;
directionalLight.Direction = new Vector3(0, -1, 1);

Dim directionalLight as Light = scene.CreateLight("directionalLight")
directionalLight.Type  = LightType.Directional
directionalLight.DiffuseColor  = ColorEx.Yellow
directionalLight.SpecularColor = ColorEx.Yellow
directionalLight.Direction = New Vector3(0, -1, 1)

directionalLight as Light = self.scene.CreateLight("directionalLight")
directionalLight.Type  = LightType.Directional
directionalLight.DiffuseColor  = ColorEx.Yellow
directionalLight.SpecularColor = ColorEx.Yellow
directionalLight.Direction = Vector3(0, -1, 1)

Compile and run the application. We now have two shadows on the screen, though since the directional light is so faint, the shadow is also faint. The last type of light we are going to play with is the spotlight. We will now create a blue spotlight:

Light spotLight = scene.CreateLight("spotLight");
spotLight.Type           = LightType.SpotLight;
spotLight.DiffuseColor  = ColorEx.Blue;
spotLight.SpecularColor = ColorEx.Blue;
spotLight.Direction = new Vector3(-1, -1, 0);
spotLight.Position  = new Vector3(300, 300, 0);

spotLight = scene.CreateLight("spotLight")
spotLight.Type           = LightType.SpotLight
spotLight.DiffuseColor  = ColorEx.Blue
spotLight.SpecularColor = ColorEx.Blue
spotLight.Direction = New Vector3(-1, -1, 0)
spotLight.Position  = New Vector3(300, 300, 0)

 spotLight = self.scene.CreateLight("spotLight")
spotLight.Type           = LightType.SpotLight
spotLight.DiffuseColor  = ColorEx.Blue
spotLight.SpecularColor = ColorEx.Blue
spotLight.Direction = Vector3(-1, -1, 0)
spotLight.Position  = Vector3(300, 300, 0)

Spotlights also allow us to specify how wide the beam of the light is. Imagine a flashlight beam for a second. There is a core beam in the center that is brighter than the surrounding light. We can set the width of both of these beams by calling the SetSpotlightRange method:

spotLight.SetSpotlightRange(35, 50);

spotLight.SetSpotlightRange(35, 50)

spotLight.SetSpotlightRange(35, 50)

Compile and run the application. Purple Ninja...dangerous!

Things to Try

Different Shadow Types

In this demo we only set the shadow type to be StencilAdditive. Try setting it to the other two types of shadows and see what happens. There are also many other shadow-related functions in the SceneManager class. Try playing with some of them and seeing what you come up with.

Light Attenuation on Ambient Light

Lights define an Attenuation property which allows you to control how the light dissipates as you get farther away from it. Add a function call to the Point light that sets the attenuation to different values. How does this affect the light? Also try setting the AmbientLight to another color.