C.12 Release Notes from 0.17 to 0.18

This section documents the major changes between versions 0.17 and 0.18 of Crystal Space.

Name Change: csWorld => csEngine

The class ‘csWorld’ has been renamed to ‘csEngine’. Here is a summary of all the changes which result from this:

• iWorld becomes iEngine
• csWorld becomes csEngine
• csWorldConfig becomes csEngineConfig
• csWorldState becomes csEngineState
• csWorldStateVector becomes csEngineStateVector
• iworld.h becomes iengine.h
• world.h becomes engine.h

csThingTemplate Removed

The class ‘csThingTemplate’ has been removed. Instead you use normal ‘csThing’ instances and clone them using csThing::MergeTemplate(). The ‘thing_templates’ list in ‘csEngine’ is still there but it now contains instances of ‘csThing’ instead of ‘csThingTemplate’. This also means that ‘csPolygonTemplate’ is removed. Fixing applications for this change is not very hard. It mostly means replacing ‘csThingTemplate’ with ‘csThing’ and then doing small modifications to the API.

Configuration File Changes

The configuration file format has changed significantly. In contrast to the INI format used previously, Crystal Space now uses a flat format. Sections are gone. Every configuration file is just a list of keys in the following format:

; optional comment
; (can also be several lines long)
KeyName = Value

Also, key names have been changed completely. Keys are organized in a pseudo-hierarchical structure by using key names such as ‘Engine.Lighting.Ambient.Red’. To convert your own configuration files to the new format, you should take all keys from all sections and rename them using the template ‘ApplicationName.SectionName.KeyName’. This is only a suggestion. You can choose whatever name you want, except that the initial ‘ApplicationName.’ should be used in order to avoid naming collisions with keys in other configuration files. This is done to give every option a unique name. The same should be done for plugins (‘PluginName.SectionName.KeyName’).

Comments at the end of the file are preserved when saving the file.

On the application side, things have also changed:

• The old ‘csIniFile’ class still exists. All these changes refer to the difference between ‘csIniFile’ and ‘csConfigFile’, and the difference between ‘iConfigFile’ and ‘iConfigFileNew’. Sorry for this mess, but there were a few cases where I could not (yet) port modules to the new config system, so they still require the old system. This will change soon. The header files for the new system are ‘CS/csutil/cfgfile.h’ and ‘icfgnew.h’. The main system configuration file already uses the new system.
• To read or write configuration keys, you now only pass the key name and default value, because sections no longer exist. Be careful when porting, because the line:

  const char *s = Config->GetStr("section", "key");

  In your code may now be interpreted as:

  const char *s = Config->GetStr("key", "default");

  The compiler will not complain about this.

• GetYesNo() and SetYesNo() have been renamed to GetBool() and SetBool().
• The ‘dirty’ flag is now hidden inside the configuration file object. The Save() method respects this flag.
• The section and data iterators have been merged into a single object. This iterator can be used to cycle through all options, or through all options in one subsection, which is the initial substring of the key name. For example, if you iterate all options in subsection ‘Engine.Lighting.’, you will get all options whose name begin with this string. Note the trailing dot. It is part of the subsection name. This is important if you have other options like ‘Engine.LightingActivate’, which would otherwise be enumerated as well. It is also important because you can ask an iterator for the local name of the current key, which is everything but the subsection name. For example, If your iterator loops through ‘Engine.Lighting.’, then the key ‘Engine.Lighting.Ambient.Red’ would have the local name ‘Ambient.Red’. If you omit the trailing dot, this would be ‘.Ambient.Red’, which may not be what you want. To retrieve the local name, call Iterator->GetName(true);.
• Convenience methods such as GetInt(), GetFloat(), and GetBool() have been added to the iterators.
• The Prev() method of iterators has been removed because a new planned implementation of the ‘iConfigFileNew’ interface is probably not able to implement this method. Also, it was never used.

Mesh Object Plugins

Particle systems, 2D sprites, and 3D sprites are now no longer in the engine. This means that classes like ‘csSprite3D’, ‘csSprite2D’, ‘csParticleSystem’, etc., are no longer directly accessible and now have to be accessed through the new mesh object plugin system.

In the engine the two primary mesh-related classes are now ‘csMeshWrapper’ and ‘csMeshFactoryWrapper’. The old ‘csSprite’ class which was the superclass of all sprites has been replaced with ‘csMeshWrapper’ ‘csMeshFactoryWrapper’ is roughly similar to what ‘csSpriteTemplate’ used to do except that it is now also a parent for particle system and 2D sprite instances.

The explanation below mainly tells you how to port the original ‘csSprite3D’ code to the new system. The other stuff follows almost automatically from what you see below.

Here is a list of things that are removed and which things you will have to use instead. More detailed info will come later:

• csSprite => csMeshWrapper
• csSprite2D => csMeshWrapper, iSprite2DState
• csSprite3D => csMeshWrapper, iSprite3DState
• csSpriteTemplate => csMeshFactoryWrapper, iSprite3DFactoryState
• csFrame => iSpriteFrame
• csSpriteAction => iSpriteAction
• csSkeleton => iSkeleton
• csSkeletonLimb => iSkeletonLimb
• csSkeletonConnection => iSkeletonConnection
• csSkeletonState => iSkeletonState
• csSkeletonLimbState => iSkeletonLimbState
• csSkeletonConnectionState => iSkeletonConnectionState
• iSprite => iMeshWrapper
• iSpriteTemplate => iMeshFactoryWrapper
• csLoader::LoadSpriteTemplate() => Use ‘spr3dldr’ plugin to load factories
• csLoader::LoadSprite() => Use ‘spr3dldr’ plugin to load sprites
• csEngine::sprites => csEngine::meshes
• csEngine::RemoveSprite => csEngine::RemoveMesh
• csEngine::UnlinkSprite => csEngine::UnlinkMesh
• csEngine::sprite_templates => csEngine::mesh_factories
• csSector::sprites => csSector::meshes

In addition to that the ‘SPRITE’ keyword in map files is also no longer supported. Instead you should use the new ‘MESHOBJ’ keyword.

It is recommended that anyone who wants to convert to the new system should first to read the general documentation about the mesh object plugin system (see section Mesh Object Plug-In System). Read this very carefully. A good understanding is required to perform a successful conversion.

In addition to what is explained, there are also two convenience functions to create mesh factories and mesh objects:

/**
 * Convenience function to create a mesh factory from a
 * given type.  The type plugin will only be loaded if
 * needed.  'classId' is the SCF name of the plugin (like
 * 'crystalspace.mesh.object.cube').  Returns NULL on
 * failure.  The factory will be registered with the engine
 * under the given name.  If there is already a factory with
 * that name no new factory will be created but the found
 * one is returned instead.  If the name is NULL then no
 * name will be set and no check will happen if the factory
 * already exists.
 */
virtual iMeshFactoryWrapper* CreateMeshFactory(
  const char* classId, const char* name) = 0;

/**
 * Convenience function to create a mesh object for a given
 * factory.  If 'sector' is NULL then the mesh object will
 * not be set to a position.  Returns NULL on failure.  The
 * object will be given the specified name.  'name' can be
 * NULL if no name is wanted.  Different mesh objects can
 * have the same name (in contrast with factory objects).
 */
virtual iMeshWrapper* CreateMeshObject(
  iMeshFactoryWrapper* factory, const char* name,
  iSector* sector, const csVector3& pos) = 0;

To see how to use them you can take a look at the Simple application.

Here are a few examples of old code compared to new code:

Old code:

// Load a sprite template from disk.
csSpriteTemplate* spritetmpl =
  csLoader::LoadSpriteTemplate (engine, "/lib/std/sprite1");
// Add the sprite to the engine.
csSprite3D* sprite = spritetmpl->NewSprite (engine);
sprite->SetName ("MySprite");
engine->sprites.Push (sprite);
sprite->GetMovable ().SetSector (room);
csMatrix3 m; m.Identity (); m *= 5.;
sprite->GetMovable ().SetTransform (m);
sprite->GetMovable ().SetPosition (csVector3 (-3, 5, 3));
sprite->GetMovable ().UpdateMove ();
sprite->SetAction ("default");
sprite->InitSprite ();

New code:

// Load a sprite template from disk.
csMeshFactoryWrapper* spritetmpl =
  csLoader::LoadMeshObjectFactory (engine, "/lib/std/sprite1");
if (spritetmpl == NULL)
{
  Printf (MSG_FATAL_ERROR, "Error loading mesh object factory!\n");
  cleanup ();
  exit (1);
}
// Add the sprite to the engine.
iMeshWrapper* sprite = engine->CreateMeshObject (
   QUERY_INTERFACE (spritetmpl, iMeshFactoryWrapper),
  "MySprite",
  QUERY_INTERFACE (room, iSector),
  csVector3 (-3, 5, 3));
csMatrix3 m; m.Identity (); m *= 5.;
sprite->GetMovable ()->SetTransform (m);
sprite->GetMovable ()->UpdateMove ();
iSprite3DState* spstate =
  QUERY_INTERFACE (sprite->GetMeshObject (), iSprite3DState);
spstate->SetAction ("default");
spstate->DecRef ();

Keep in mind that for this to work ‘/lib/std/sprite1’ has to be modified from old to new syntax, as well.

Here is an example for sprite templates:

Old syntax (sprite template):

SPRITE 'mySpriteTmpl' (
  TEXNR ('xxx.gif')
  FRAME (...)
  ...
)

New syntax (mesh wrapper factory):

MESHOBJ 'mySpriteTmpl' (
  PLUGIN ('crystalspace.mesh.loader.factory.sprite.3d')
  PARAMS (
    MATERIAL ('xxx')
    FRAME (...)
    ...
  )
)

And here is an example for actual sprite instances:

Old syntax (sprite):

SPRITE 'mySprite' (
  TEXNR ('xxx.gif')
  TEMPLATE ('mySpriteTmpl', 'someAction')
  MOVE (...)
)

New syntax (mesh wrapper):

MESHOBJ 'mySprite' (
  PLUGIN ('crystalspace.mesh.loader.sprite.3d')
  PARAMS (
    MATERIAL ('xxx')
    FACTORY ('mySpriteTmpl')
    ACTION ('someAction')
  )
  MOVE (...)
)

Here are some additional notes.

• Notice that MOVE() goes outside the PARAMS() block for a sprite.
• Note that the new ‘spr3d’ can not work with textures. It needs materials. So add a definition to the ‘MATERIALS’ section.

csPixmap Moved and Renamed

‘csPixmap’ has moved to the new ‘csfx’ library, so you will need to include the header file from that library. Note that ‘csPixmap’ is now also an abstract class so where you would, in the past, instantiate ‘csPixmap’, you now need to instantiate ‘csSimplePixmap’, instead. In arguments and variables it is recommended you still use ‘csPixmap’ as it will allow you to use other kinds of pixmaps there, as well.

General Use of SCF Interfaces

In general it is now a good idea to use SCF interfaces to access objects instead of the normal classes wherever possible. This applies mostly to the engine (i.e. use methods from ‘iEngine’ rather than ‘csEngine’). Consequently, also use ‘iMeshWrapper’ instead of ‘csMeshWrapper’, and ‘iMaterialWrapper’ instead of ‘csMaterialWrapper’, and so on. This will make the transition to version 1.0 easier when the engine will be fully accessible as a plugin.

Sound System Changes

There have been three main changes in the sound system:

• Some of the options in the configuration file have become redundant. The others have been moved to ‘CS/data/config/sound.cfg’. Have a look at this file to see which options remain.
• As before, a sound can be loaded as a static or streamed sound, but this difference is now expressed by using different classes: ‘iSoundData’ and ‘iSoundStream’. You can create any number of instances (sources) of a static sound, but only one instance of a streamed sound. In fact, whenever you play a static sound, a separate sound stream is created from it. The definition of a static sound is now explicitly “a sound of which any number of instances can be created”.
• The system of 3D and non-3D sources has been changed a bit. Every sound source now has a new attribute, the 3D mode. This mode can also be changed after the source is created. It can be set to the following values:

  SOUND3D_DISABLE

  This will cause the sound source to produce no 3D effect. This is also the only mode in which the original stereo effects are preserved. (This does not work correctly at the moment.)

  SOUND3D_ABSOLUTE

  This will interpret the position of the sound source and the listener as absolute coordinates and create the 3D effect based on this.

  SOUND3D_RELATIVE

  This will ignore the listener's position and interpret the position of the sound source as relative coordinated to the listener. In other words, it calculates the 3D effect as if the listener was positioned at (0,0,0) with default orientation.

Miscellaneous Changes

iGraphics2D::WriteChar() has been removed. Use Write() instead.

All UpdateLighting() calls now accept ‘iLight’ pointers intead of ‘csLight’ pointers. In addition csEngine::GetNearbyLights() returns an array of ‘iLight’ pointers.

The obsolete ‘CLights’ class (for uniform dynamic lighting) has been removed. It was not working properly anyway.

The csEngine::PrepareParticleSystems() method has been removed. Instead, use the new csEngine::PrepareMeshes() method.

The csEngine::AdvanceSpriteFrames() method has been renamed to NextFrame(). In addition UpdateParticleSystems() has been removed and is now also handled by csEngine::NextFrame().

With the new mesh object plugin system the ‘iParticle’ interface also changed a little. Check out the header to see the changes.

FastSqrt() is gone. Use qsqrt() instead. If you want to calculate 1/sqrt() then use qisqrt().

‘csRenderView’ has no public members anymore. You need to access everything through GetFoo() and SetFoo() methods Check out the header for more details.

This document was generated using texi2html 1.76.