4.2.1.3 Creating a “World”

Now we have a very exciting application which opens a black window and waits for the ESC key to quit. We assume this is the application you always wanted to have? No? Ok then, let's create some 3D stuff.

We'll add a texture manager, a room (technically called a sector) and some lights. First, add a pointer to our main sector and a function CreateRoom() to the ‘Simple’ class header file:

class Simple
{
private:
  ...
  iSector* room;
  float rotX, rotY;
  ...
  void CreateRoom ();
  ...

Now add these chunks of code (texture manager, room, lights) to ‘simple.cpp’:

bool Simple::SetupModules ()
{
  ...
  // These are used store the current orientation of the camera.
  rotY = rotX = 0;
  ...
  CreateRoom ()
  
  engine->Prepare ();

  using namespace CS::Lighting;
  SimpleStaticLighter::ShineLights (room, engine, 4);

  rm = engine->GetRenderManager();
  ...
}
...
void Simple::CreateRoom ()
{
  if (!loader->LoadTexture ("brick", "/lib/std/castle/brick1_d.jpg"))
    ReportError("Error loading 'brick1_d' texture!");
  iMaterialWrapper* tm = engine->GetMaterialList ()->FindByName ("brick");
  
  room = engine->CreateSector ("room");

  // First we make a primitive for our geometry.
  using namespace CS::Geometry;
  DensityTextureMapper mapper (0.3f);
  TesselatedBox box (csVector3 (-5, 0, -5), csVector3 (5, 20, 5));
  box.SetLevel (3);
  box.SetMapper (&mapper);
  box.SetFlags (Primitives::CS_PRIMBOX_INSIDE);

  // Now we make a factory and a mesh at once.
  csRef<iMeshWrapper> walls = GeneralMeshBuilder::CreateFactoryAndMesh (
      engine, room, "walls", "walls_factory", &box);
  walls->GetMeshObject ()->SetMaterialWrapper (tm);

  csRef<iLight> light;
  iLightList* ll = room->GetLights ();

  light = engine->CreateLight (0, csVector3 (-3, 5, 0), 10,
        csColor (1, 0, 0));
  ll->Add (light);

  light = engine->CreateLight (0, csVector3 (3, 5,  0), 10,
        csColor (0, 0, 1));
  ll->Add (light);

  light = engine->CreateLight (0, csVector3 (0, 5, -3), 10,
        csColor (0, 1, 0));
  ll->Add (light);
}

This extra code first loads a texture with LoadTexture(). The first parameter is the name of the texture as it will be known in the engine; and the second is the actual filename on the VFS volume (see section Virtual File System (VFS)). This function returns a ‘iTextureWrapper’ which we don't use. Instead we use the ‘iMaterialWrapper’ which is created automatically by LoadTexture().

The next block of code shows how to add a normal map to the texture we just loaded.

Then, we create our room with CreateSector(). This room will initially be empty. A room in Crystal Space is represented by ‘iSector’ which is basically a container which can hold geometrical objects. Objects in Crystal Space are represented by mesh objects (see section Mesh Object Plug-In System). There are several types of mesh objects in Crystal Space. Every type of mesh object represents some different way to represent geometry. In this tutorial we are only going to use the “genmesh” mesh object type. This mesh object type is very useful for walls of indoor maps or buildings. Most mesh objects don't contain any geometry. The geometry definition is actually contained in the mesh factory. So that's why we first create a factory for our walls.

Now, we want to create the six walls of our room. For this the best object to use is the GenMesh object (see section Genmesh Mesh Object). With genmeshes the geometry is represented in the factory. From that factory you can then create multiple meshes. In our case we only need one mesh for the walls (which will be a box visible from the inside). So we will create one factory and one mesh from that factory.

There is a ‘CS::Geometry’ namespace where there are several conveniance classes to help you build genmeshes. In our case we need a box that is visible from the inside. We will use the ‘TesselatedBox’ class for that purpose. We use a tesselated box (as opposed to a normal box) so that our lighting is more accurate. If you don't use lightmaps (like in this example) then genmeshes are only lit at vertices of the model and lighting for the rest of the surface is interpolated. So to get accurate lighting you need a model that has sufficient vertices. We use a tesselation level so that every face has 16 vertices (3 times 3 quads or eighteen triangles for every face). You can increase the value in the TesselatedBox::SetLevel() call even more to get even better lighting resolution but that will increase the number of triangles in the model too much and it is not needed in this simple example.

From this primitive we can now create both the factory and the mesh at once using the GeneralMeshBuilder::CreateFactoryAndMesh() method. In the ‘GeneralMeshBuilder’ class there are other methods that you can use to create only factories or meshes but in our case we use the simple method of creating both at once. Because we give it a pointer to our tesselated box it will immediatelly populate the factory with the triangles and vertices required for this box. The CreateFactoryAndMesh() method places the object at the origin in the sector (i.e. ‘0,0,0’). If you want to change that you have to use iMeshWrapper::GetMovable(). But in this example the origin is fine.

The last thing we have to do is to set a material to use for this mesh. You can set a material both on the factory (in which case all objects that are created from this factory will share it) or on the mesh. In this case we set it on the mesh by using SetMaterialWrapper().

Finally, we create some lights in our room to make sure that we actually are able to see the walls. The interface ‘iLight’ represents a light. In this case we created some static lights which can not move and change intensity. We create three such lights and add them to the room with AddLight(). Note that the list of lights in a sector is represented by an object implementing ‘iLightList’. To get this list you call iSector::GetLights().

When creating a light we use several parameters. First we have the name of the light. This is not used often and mostly you can set this to 0. The second parameter is the location of the light in the world. Then follows a radius. The light will not affect polygons which are outside the sphere described by the center of the light and the radius. The next parameter is the color of the light in RGB format (<1,1,1> means white and <0,0,0> means black). The last parameter indicates whether or not we want to have a pseudo-dynamic light. A pseudo-dynamic light still cannot move but it can change intensity. There are some performance costs associated with pseudo-dynamic lights so it is not enabled by default.

The call to Prepare() prepares the engine for rendering your scene. It will prepare all textures and meshes.

Using the ShineLights() function we generate static vertex lighting for our dynamically created geometry. Most of the times Crystal Space applications will probably load maps from disk and for that situation the lighting information (vertex and lightmaps) should already be present as calculated by the ‘lighter2’ application. However, for dynamically generated geometry you can choose to either use some kind of hardware assisted lighting (by using the ‘unshadowed’ render manager for example) or else you can use static lighting. ShineLights() is a convenience function that has the same end result as if the objects were lit using ‘lighter2’ with vertex lighting.

Ok, now we have created our room and properly initialized it. If you compile and run this application you would still see a black screen. Why? Because we have not created a camera through which you can view the room.

This document was generated using texi2html 1.76.