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

C.7 Release Notes from 0.17 to 0.18

This section documents the major changes between versions 0.17 and 0.18 of 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 ] [ >> ]

This document was generated using texi2html 1.76.