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

C.1 API Changes from 0.96 to 0.98

This section documents the major changes between versions 0.96 and 0.98 of of Crystal Space.

Polygon Texture Mapping Changes

The following interfaces have been removed: iPolyTexNone, iPolyTexGouraud, iPolyTexFlat, and iPolyTexLightMap. The combined API from iPolyTexNone and the iPolyTexLightMap have moved to iPolygon3D itself.

iPolygon3D->SetTextureType() and GetTextureType() have been removed. Instead use:

iPolygon3D->GetPolyTexType() has been removed.

The `shading' keyword in polygons now accepts a boolean value instead of `NONE', `FLAT', `GOURAUD', or `LIGHTMAP'. With this you can enable/disable lightmapping.

If you want gouraud shaded polygons you should use the `genmesh' mesh object plugin instead.

Bezier Curve Changes

The notion of curve templates has been reworked. iCurveTemplate has been removed and it's functionality has moved to iCurve itself. As a consequence of this change the bezier addon loader has been removed. Also curves have been seperated from the thing plugin and now live in the 'bezier' plugin. So a curve like this in the past:

 
<addon>
  <plugin>crystalspace.mesh.loader.thing.bezier</plugin>
  <params>
    <name>b1</name>
    <material>mosaic</material>
    <v>0</v> <v>1</v> <v>2</v>
    <v>3</v> <v>4</v> <v>5</v>
    <v>6</v> <v>7</v> <v>8</v>
  </params>
</addon>
<meshfact name="tunnel">
  <plugin>crystalspace.mesh.loader.factory.thing</plugin>
  <params>
    <curvecenter x="0" y="0" z="0" />
    <curvescale>80</curvescale>
    <curvecontrol x="5" y="2" z="0" u="1" v="0" />
    ...
    <curve name="bez">b1</curve>
  </params>
</meshfact>

should now become (mark the new plugin line):

 
<meshfact name="tunnel">
  <plugin>crystalspace.mesh.loader.factory.bezier</plugin>
  <params>
    <curvecenter x="0" y="0" z="0" />
    <curvescale>80</curvescale>
    <curvecontrol x="5" y="2" z="0" u="1" v="0" />
    ...
    <curve name="b1">
      <material>mosaic</material>
      <v>0</v> <v>1</v> <v>2</v>
      <v>3</v> <v>4</v> <v>5</v>
      <v>6</v> <v>7</v> <v>8</v>
    </curve>
  </params>
</meshfact>

On the API side nothing much changes except that when you use the bezier mesh plugin you need to use iBezierState and iBezierFactoryState.

The iThingEnvironment no longer has code to maintain bezier curve templates.

iThingState and iPolygon3D Changes

iPolygon3D and iThingState no longer implement iObject. So the QueryObject() function has been removed. Polygons can still have names though. Added SetName() and GetName() for that.

iPolygon3D has been split in iPolygon3D and iPolygon3DStatic. The static version contains all static data that can be put in a factory. Several functions like iThingState->CreatePolygon() will now return iPolygon3DStatic.

iThingState has been split in iThingState and iThingFactoryState. A thing mesh no longer implements both a mesh object and a mesh object factory. Instead things now work like usual mesh objects where iMeshObjectType->NewFactory() creates a factory that implements iThingFactoryState and iMeshObjectFactory->NewInstance() creates an instance that implements iThingState. The engine convenience functions to create a thing mesh will automatically create both the factory and mesh so you don't have to worry about that. You can use iThingState->GetFactory() from a thing mesh object to get the iThingFactoryState so you can build the polygons. Note that SCF_QUERY_INTERFACE of iThingFactoryState no longer works on a thing mesh object. You must use GetFactory.

Polygon Planes

Polygon planes are removed. So it is no longer possible to use the plane addon loader to define texture mapping for a polygon outside of the polygon itself. To fix this you must specify all texture mapping information in the texmap statement of the polygon. `map2cs' now correctly outputs polygons like this (no longer outputs planes) and `levtool' can convert old style maps to new format like this:

iThingEnvironment no longer has code to maintain polygon texture mapping planes.

The plane loader and saver addons have been removed from the thing loader plugin.

Removed iPolyTxtPlane interface. Added iPolygon3DStatic->GetTextureSpace() function to get texture space definition for polygon.

 
levtool -planes yourmap.zip

Portal changes

Several methods in iPortal have changed slightly. For example SetMirror now expects a plane instead of a polygon.

Datatype changes

The csSome, csConstSome and uint types have been removed. Use void*, const void* and unsigned int instead.

csHashMap changes

csHashIterator can no longer iterate over all objects. To do that you need to use csGlobalHashIterator.

Procedural textures

Instead of only built-in types, procedural textures have been moved into plugins. That means that the <type> token now works the same way as the <plugin> token for meshes. That is, either specify a full class ID (e.g. crystalspace.proctex.loader.fire), or a shortcut specified in the <plugins> token of the world. To simulate the old <type> behaviour, paste the following lines into a map's <plugin> section:

 
<plugin name="dots">crystalspace.texture.loader.dots</plugin>
<plugin name="fire">crystalspace.texture.loader.fire</plugin>
<plugin name="water">crystalspace.texture.loader.water</plugin>
<plugin name="plasma">crystalspace.texture.loader.plasma</plugin>

This requires that you move the <plugin> block in front of the <textures> block, as otherwise the shortcuts won't be recognised.

The behaviour of procedural textures also differs as a material of the same name was created along with the texture; this isn't the case any more, you have to create a material which uses the procedural texture manually.

In addition, the loader now doesn't distinguish between normal and procedural textures any more, both are loaded with the same <texture> block. The syntax recognized is a combination of both old <texture> and <proctex> tokens - so renaming all <proctex> to <texture> tags is sufficient to convert a level (apart from fixing the <type> tokens.)

Regions

Region handling has changed considerably. The engine no longer has the concept of a current region. The engine still manages all regions though. Objects also no longer register themselves to the current region. It is the responsability of the object creator to do that. The standard loader has support for adding objects to a region now.

The following functions have been removed from iEngine:

There is one new function iEngine->CreateRegion() which will create a new region.

In iLoader the functions LoadMapFile() and ThreadedLoadMapFile() now expect an optional pointer to a region in addition with a boolean to restrict searching to that region.

In addition to all these changes the `region' keyword in XML is no longer supported.

Mesh objects/factories and iPolygonMesh

Some mesh factories used to support the querying of the iPolygonMesh interface (e.g. Thing, Sprite3D, Genmesh). Due to the way this was implemented internally this caused leaks. So, querying iPolygonMesh directly from the object is now discouraged. Although it may still work in some cases, this feature may be dropped without further notice and may not work in all cases.

Similar for mesh objects. Querying iPolygonMesh is discouranged here as well.

Instead, if you want the polygon mesh from an object, use the GetObjectModel() method from the iMeshObject interface, resp. query for the iObjectModel interface in case of a factory, and utilize one of the GetPolygonMeshXXX() methods, depending on what you need (the old interface query returned the collision detection mesh.) This has also the advantages that you can get different meshes for different purposes (currently, visibility culling and collision detection in addition the the base mesh), and that those meshes can be overridden by user-defined meshes (e.g. if the collision detection mesh needs to have a shape different from the visible mesh.)

In iPolygonMesh the IsDeformable() method has been replaced with the more general GetFlags(). In addition to that Cleanup() is removed and instead Lock() and Unlock() are added.

iPolygonMesh now has GetTriangles() and GetTriangleCount(). Check out the API docs for implementation details.

Iterator Changes

Changed the following iterators to conform to the following iterator standard:
 
  bool iterator->HasNext() returns true if there are more items.
  T* iterator->Next() returns next element or 0.
  void Reset() optionally resets the iterator (not all implement this).

Changes to AWS

iAWS::CreateCustomCanvas was removed. To set up the AWS with a cavas, use iAWS::SetupCanvas instead.

csPArray removed

csPArray has been removed in favor of csArray. So use csArray<T*> instead of csPArray<T>.

csStrVector and iStrVector removed

csStrVector has been removed in favor of csStringArray. This means that functions like iVFS::MountRoot() and iVFS::FindFiles() now return an iStringArray.

csVector and csBasicVector removed

csVector and csBasicVector have been removed. Instead you should use one of the templated arrays: csArray, csPDelArray, or csRefArray.

If you were using a regular csVector then this can usually be replaced directly by csArray<type*> with `type' the type you were storing in the vector.

If you subclassed from csVector in order to override FreeItem() then you have to decide what to do depending on the code in FreeItem(). If that code performed a delete then you can use csPDelArray. If that code performed a DecRef() then you can use csRefArray but you still have to be careful because csRefArray will automatically incref objects that are pushed on the array. In other cases you probably need to handle deletion manually.

csVector also allowed to override Compare() and CompareKey in order to drive QuickSort, FindSortedKey, InsertSorted, and FindKey. This is no longer possible. Instead you can do the following transformation. First the old code:

 
class MyVector : public csVector
{
public:
  virtual ~MyVector ()
  {
    DeleteAll ();
  }
  virtual void FreeItem (void* item)
  {
    delete (MyType*)item;
  }
  virtual int Compare (void* i1, void* i2, int mode) const
  {
    ...
  }
  virtual int CompareKey (void* i, const void* key, int mode) const
  {
    ...
  }
};

This could be transformed roughly to the following class:

 
class MyVector : public csPDelArray<MyType>
{
public:
  static int Compare (MyType const* i1, MyType const* i2)
  {
    ...
  }
  static int CompareKey (MyType const* i, void* key)
  {
    ...
  }
};

In the calls to InsertSorted, FindKey, ... you would then pass in one of the static functions to use.

Array changes

All arrays have been modified to inherit from csArray. This means that there are some slight API changes because many functions were not consistent with csArray.

Also csGrowingArray has been renamed to csDirtyAccessArray.

iEventQueue clients now responsible for their own references

Clients passing a csEvent instance iEventQueue::Post() or iEventOutlet::Post() must now DecRef() the csEvent after the call, since the iEventQueue will IncRef() it during the call and then DecRef() it when it's been handled.

This means that if you are calling Post() like this:
 
  iEvent *e = new csEvent (foo, bar);
  eventq->Post(e);
You must now call it like this:
 
  csRef<iEvent> *e = csPtr<iEvent> (new csEvent (foo, bar));
  eventq->Post(e);

Events created with iEventQueue::CreateEvent() or iEventOutlet::CreateEvent() are unaffected by this change.

New Renderer Related Changes

The mesh object API has changed considerably so we recommend looking at the documentation on that to see how to modify your own mesh object for the new API. In this section we describe API modifications that are relevant for user applications:

For iLight: SetRadius, GetRadius, and GetSquaredRadius have been replaced with SetInfluenceRadius, GetInfluenceRadius, and GetInfluenceRadiusSq.

For iMaterialEngine and related: GetTextureWrapper for layers now expects a csStringID instead of an integer.


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

This document was generated using texi2html