4.2.2.3 Creating a Mesh from a Factory

To create a mesh just add the following code in Simple::CreateSprites() (before ‘return true’ and after the code we just added to load the mesh factory):

void Simple::CreateSprites ()
{
  ...

  // Add the sprite to the engine.
  csRef<iMeshWrapper> sprite (engine->CreateMeshWrapper (
        imeshfact, "MySprite", room,
        csVector3 (-3, 5, 3)));
  csMatrix3 m; m.Identity ();
  m *= 5.; // Don't do this scale in your own code! (see discussion)
  sprite->GetMovable ()->SetTransform (m);
  sprite->GetMovable ()->UpdateMove ();
  csRef<iSprite3DState> spstate (
    scfQueryInterface<iSprite3DState> (sprite->GetMeshObject ()));
  spstate->SetAction ("default");
  sprite->SetZBufMode (CS_ZBUF_USE);
  sprite->SetRenderPriority (engine->GetObjectRenderPriority ());
}

The easiest way to create a mesh is to use engine->CreateMeshWrapper(). This will take care of using the given mesh factory to create the mesh, give it a name, and correctly place it at the given position in the world. The name of a mesh can be useful for scripting so that a script can refer to objects with their names.

Moving meshes (and things) is done through the iMovable interface to which you can get a reference by doing sprite->GetMovable(). The calls to SetTransform() and SetPosition() set up a transformation matrix and vector to correctly place the mesh in the room. In this particular case we use the identity matrix as a transform and scale it with five to make the sprite five times bigger. After doing movement (either updating the sectors or the position) you must call movable->UpdateMove() to change internal data structures (i.e. the engine may use this to recalculate visibility information).

WARNING: The code above actually scaled the object by giving it a transformation matrix which is multiplied with 5. Don't do this in your own code. Many subsystems in Crystal Space (like the collision detection system, the visibility culling system and the lighting system) don't work properly with scaled objects. Instead scale your object using HardTransform().

If you read the mesh object documentation (see see section Mesh Object Plug-In System) carefully you will see that in order to control visual attributes of mesh objects you will have to get the state interface for either the object or the factory. In this example we query ‘iSprite3DState’ from the mesh in order to set the default action. An action is a set of frames and is used to control animation. In our simple example the sprite has only one frame so there is not much animation to see.

The calls to SetZBufMode() and SetRenderPriority() are not strictly required since the values set here are default for meshes anyway. But the two lines serve as an example on how to set other values for these. SetZBufMode() sets the Z-buffer mode that the engine will use to render this object. With ‘CS_ZBUF_USE’ this means that the Z-buffer will be used fully. Other values are ‘CS_ZBUF_FILL’ (only fill the Z-buffer), ‘CS_ZBUF_TEST’ (only test the Z-buffer), or ‘CS_ZBUF_NONE’ (ignore the Z-buffer). ‘CS_ZBUF_USE’ is a good default for objects in a room. ‘CS_ZBUF_FILL’ is usually used for the outside walls of a sector.

SetRenderPriority() controls when this object is rendered in this sector. By default there are several render priorities. Some of the more important ones are: sky, wall, object, and alpha. Every object can be put in a render priority queue. Objects in lower render priorities will be rendered before objects in higher render priorities. In addition some render priority queues sort objects internally based on some other criteria. For example, the ‘alpha’ render priority will render all objects in that queue from back to front. You can create your own additional render queues if you want. The default render priority is object which you can get with the call engine->GetObjectRenderPriority(). Most objects with Z-buffer mode equal to ‘CS_ZBUF_USE’ are placed in the ‘object’ render priority queue.

For more information on render priorities and Z-buffer mode you can look at the HOWTO on this subject (see section Render Priorities and Objects in Sectors).

This concludes the second Simple tutorial. You can now go on to the next tutorial (see section Simple Tutorial 3: Map Loading, Collision Detection)) to learn how you can load a map from a file instead of creating your rooms programmatically.

This document was generated using texi2html 1.76.