[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

C.10 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:

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:

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:

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.

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:

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html 1.76.