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

C.8 Release Notes from 0.16 to 0.17

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

Signature Change: NextFrame(elapsed_time/current_time)

csSystemDriver::NextFrame() no longer accepts `elapsed_time' and `current_time' arguments, so you have to change the prototype of your own subclassed version of NextFrame() and call the following three lines in the order below (only if you need the elapsed and current time, of course):

 
void MySubclass::NextFrame()
{
  SysSystemDriver::NextFrame();
  cs_time elapsed_time, current_time;
  GetElapsedTime(elapsed_time,current_time);
  ...

Signature Change: HandleEvent(csEvent)

The argument of csSystemDriver::HandleEvent() has changed from a `csEvent*' parameter to an `iEvent*'. Update your subclassed versions if present.

Materials Versus Textures

Crystal Space 0.17 supports materials in the sense that the API is ready for it. There is no real material support though. A material currently just corresponds with a texture. Here are a few short remarks about the changes:

In general, in most places where you used to use SetTexture() or GetTexture() you now need to use the material versions. There are few places where you deal directly with textures. The material system sits on top of the texture system and is what you should use in most cases.

`csWorld' now has a GetMaterials() function which you probably should use wherever you used GetTextures() in the past.

In the loader you can find a new function, csLoader::FindMaterial(), which will find a material with the given name. If not found it tries to find a texture with of the same name and, if found, will automatically then create a material from that texture.

The csLoader::LoadTexture() method is a bit special. As before, it loads a texture (and returns a `csTextureWrapper') but it also adds a material with the same name to the material list. You can then fetch that material from that list with code similar to the following:

 
csLoader::LoadTexture(world,"myTexture","/lib/std/stone4.gif");
csMaterialWrapper* m =
  world->GetMaterials()->FindByName("myTexture");

Collision Detection Plugin

This is a very significant change. The RAPID collision detection system has been completely removed from the engine and is now available through a plug-in module. This change will most likely require the most complicated changes to your code.

The first thing you need to add to your application is code to load the plugin. You can do this with the following code:

 
char const* p = Config->GetStr (
  "YourGame",
  "COLLDET_PLUGIN",
  "crystalspace.colldet.rapid");
collide_system =
  LOAD_PLUGIN(this, p, "CollDet", iCollideSystem);
if (!collide_system)
{
  Printf(MSG_FATAL_ERROR,
    "No Collision Detection plugin found!\n");
  return false;
}

This code loads the rapid collision detection plugin by default (which is the only one we have now) but it also reads an entry from your config file so that the user can possibly change it. If you don't want that then you can just hardcode the `p' pointer with the name of the RAPID plugin.

Note that you need to store the value of `collide_system' some place where it can be accessed by the routines that need to do the collision detection.

Then the class `csRAPIDCollider' has been removed from csengine. Instead there is a new class, `csCollider'. This class encapsulates an `iCollider' (which is something that is returned from `collide_system'). This is the easiest way to use the new collision detection system as it more closely resembles what was possible with `csRAPIDCollider'. To make a `csCollider' you can use the following code:

 
iPolygonMesh* mesh =
  QUERY_INTERFACE(object, iPolygonMesh);
csCollider* collider =
  new csCollider(*object, collide_system, mesh);

`object' can be a sector, sprite, thing, or your own object that supports the `iPolygonMesh' interface. The new collider will be attached (through the `csObject' system) to the object. This is similar to what happened with the old `csRAPIDCollider' class.

To do collision detection you need to find the colliders (or have them stored somewhere) and then you can do:

 
bool rc = collide_system->Collide(
  col1->GetCollider(), trans1,
  col2->GetCollider(), trans2);

Or:

 
bool rc = col1->Collide(*object2, trans1, trans2);

With `col1' and `col2' are the colliders (`csCollider') and `object2' is the second object. `trans1' and `trans2' are the respective transformations.

Note that before you call this you probably want to initialize the collision system like this:

 
collide_system->ResetCollisionPairs();
collide_system->SetOneHitOnly(true/false);

The argument for the second function depends on whether or not you are interested in receiving more than one hit.

Note that ResetCollisionPairs() is important. Every call to Collide() will add additional collision pairs to this array. So you have to reset it if you are no longer interested in that.

Note that csRAPIDCollider::Report() is gone. If you want that functionality you have to do it on your own (which is not difficult).

Texture Mapping Changes

The way engine defines and uses texturing has changed. There are four polygon texturing types now:

POLYTXT_NONE

No texturing. Useful when using materials without textures. It defines no texturing parameters at all thus saves memory.

POLYTXT_FLAT

Flat-shading. Only the angle between light and polygon normal is considered if `CS_POLY_LIGHTING' flag is set, and entire polygon is painted with one lighting value. Every vertex has an U/V pair associated.

POLYTXT_GOURAUD

Every polygon vertex has a color and those colors are interpolated across scanlines.

POLYTXT_LIGHTMAP

A polygon which has an associated lightmap and a texture plane.

Now it is possible to define and use objects which have flat-color but still receive light with Gouraud as well as without Gouraud interpolation; in general this open a whole new area for experimenting.

In practice this means that `csGouraudShaded' is gone and has been replaced with `csPolyTexGouraud'. `csLightMapped' has also gone and is replaced with `csPolyTexLightMap'.

Sound Changes

Merged sound buffers into sound sources. We now have 3D and non-3D sound sources. Non-3D sources are what were formerly sound buffers. As a parameter to `Renderer->CreateSource()' you can indicate if you want a 3D or non-3D source.

The sound loader is now a plugin and must be loaded as such. It uses the `iSoundLoader' interface. A loaded sound data block is represented by `iSoundData'.

If you use standard Crystal Space libraries to load sounds, this is all you need to be aware of. Otherwise you should also know how to load a sound without `csParser'.

To load a sound the sound loader now needs some information describing the format of the sound. This information can be queried from the sound renderer. Also, a sound can be optionally be loaded as stream. This is currently not useful for anything, but will instead affect performance and memory in a negative way. It is intended as a future option to load background music. All member functions of `iSoundData' are intended for private use (of course you may use them, but I don't think they are useful). To load a sound, perform the following steps.

  1. Load the file buffer from a VFS path. See section Virtual File System (VFS).
  2. Ask the sound renderer for the format descriptor (`csSoundFormat').
  3. Pass both the file data and the format to the sound loader, using `false' for streaming (the default). After that, you may delete the file data.

Thing and Sprite Changes (csMovable)

The movement system of Things and Sprites has been merged into one class called `csMovable'. Thus, all functions such as SetPosition(), SetTransform(), and so on, have been removed from `csThing' and `csSprite'. Instead there is a function GetMovable() (both for Things and Sprites) which returns the `csMovable' for that object. There is also a new function called csMovable::UpdateMove()-which resembles the original csThing::Transform() somewhat-which you must call after updating the position and/or transformation of the movable which belongs to the object.

In addition to the changes related to `csMovable' the linked list of sky and thing objects in a sector has also been replaced by a `csVector' and things are now also kept in a global list in the `csWorld', just like sprites. This means that sprites and things look a lot more like each other now with regards to movement and placement in sectors. This means that functions such as AddThing(), GetNumThings(), RemoveThing() and GetFirstThing() are now gone, as are the similar methods for sky objects. Instead, you should work through the new public `skies' and `things' vectors. In addition to this the GetNext() and GetParent() functions have been removed from `csPolygonSet'.

Given the old code to operate on things:

 
csThing* thing = new csThing(world);
sector->AddThing(thing);
thing->SetPosition(csVector3(0,0,3));
thing->SetTransform(csMatrix3());
thing->Transform();
...
sector->RemoveThing(thing);
delete thing;

It will need to be converted to the following:

 
csThing* thing = new csThing(world);
world->things.Push(thing);
csMovable& move = thing->GetMovable();
move.SetSector(sector);
move.SetPosition(csVector3(0,0,3));
move.SetTransform(csMatrix3());
move.UpdateMove();
...
world->RemoveThing(thing);

Given the old to operate on sprites:

 
csSprite3D* sprite = new csSprite3D(world);
world->sprites.Push(sprite);
sprite->MoveToSector(sector);
sprite->SetPosition(csVector3(0,0,3));
sprite->SetTransform(csMatrix3());

It will need to be transformed to:

 
csSprite3D* sprite = new csSprite3D(world);
world->sprites.Push(sprite);
csMovable& move = sprite->GetMovable();
move.SetSector(sector);
move.SetPosition(csVector3(0,0,3));
move.SetTransform(csMatrix3());
move.UpdateMove();

Especially note the new call to UpdateMove().

API Changes: csCamera

The function SetFOV() now needs an extra parameter which is the width of the display. This is needed for calculating the angle of the FOV (field of view). In addition, there are now new SetFOVAngle() and GetFOVAngle() functions. GetFOVAngle() used to be in csRenderView().

API Changes: csWorld

Here is a list of the more significant API changes to `csWorld'.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated using texi2html 1.76.