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

C.7 Release Notes from 0.18 to 0.90

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

SCF

The set of SCF functions has been removed except for scfInitialize(). This function creates a global instance of the ‘iSCF’ interface which is always available to the application and to plugin modules as ‘iSCF::SCF’. All other SCF functionality should be accessed via this shared object. This change makes it possible to call SCF functions from within dynamic libraries (i.e. from plugins), which was not possible before. The only thing that is still not allowed is to use the SCF_REGISTER_STATIC() family of macros in dynamic libraries.

SCF now associates a so-called Interface ID Number with every interface name. You can get the number for an interface by calling ‘iSCF::SCF->GetInterfaceID("iInterface")’. It is currently not possible to get the interface name for a given number, but this should not be needed anyway (see below).

iBase::QueryInterface() now takes the interface ID as its parameter instead of the interface name. This makes a lot of optimization possible, because interfaces can be compared using simple integer comparison instead of string comparison. You will not see anything of this because the SCF_QUERY_INTERFACE() macro shields you from it. As a result, your program should not require any changes.

However, you can increase performance in critical areas by using two new macros which have been introduced. Place SCF_DECLARE_FAST_INTERFACE() somewhere at top-level in your source files (or in one of your header files). For every interface you do this you can then use SCF_QUERY_INTERFACE_FAST(). The advantage of this is a performance gain. The disadvantage is that you have to use SCF_DECLARE_FAST_INTERFACE() and that the name of the interface must be hard-coded (e.g. you cannot use SCF_QUERY_INTERFACE_FAST() if the name of the interface is given to your function as a parameter).

Three other changes have been done to SCF. First, it is now possible to get a list of registered classes using iSCF::SCF->QueryClassList(). Second, scfGetRefCount() has been introduced which allows access to an object's reference count without accessing the reference count variable directly. This function should only be used for debugging, however. Third, the macros which implement ‘iBase’ functions have been split up. For example, ‘SCF_IMPLEMENT_IBASE()’ is now composed from these components:

 
SCF_IMPLEMENT_IBASE_INCREF()
SCF_IMPLEMENT_IBASE_DECREF()
SCF_IMPLEMENT_IBASE_GETREFCOUNT()
SCF_IMPLEMENT_IBASE_QUERY()

This decomposition makes it easier to replace iBase methods individually in a particular implementation.

csObject and RTTI

The pseudo-RTTI system has been removed from csObject. Instead, SCF functions are now used to identify an object's type. As an example of how this affects your code, if your old code was checking an object's type in this fashion:

 
csObject* obj = ...;
if (obj->Type == csMyClass::Type)
{
  csMyClass* a = (csMyClass*)obj;
  ...
}

Then it should now do so in this fashion:

 
csObject *obj = ...;
iMyInterface* a = SCF_QUERY_INTERFACE(obj, iMyInterface);
if (a != NULL)
{
  ...
}

In performance-critical areas, you should use SCF_QUERY_INTERFACE_FAST() rather than SCF_QUERY_INTERFACE().

A result of this change is that child object iterators cannot easily iterate over objects of a certain type anymore. To achieve the same effect, you should create an iterator for all children and then use SCF_QUERY_INTERFACE() to test if an object implements a certain interface.

Note that if you don't want to create proper interfaces for all your classes, it is possible to query the class itself instead of an interface. Assuming that csMyClass is just a set of values, and you don't want to create an interface with accessor functions for it. Then you may place SCF_DECLARE_IBASE_EXT() into the class as usual (note the ‘EXT’ version of the macro because it extends the interface list of ‘csObject’). In addition, you must set a version number for the class using SCF_VERSION(csMyClass, ?, ?, ?). The interface list then looks like this:

 
SCF_IMPLEMENT_IBASE_EXT (csMyClass)
  SCF_IMPLEMENTS_INTERFACE (csMyClass)
SCF_IMPLEMENT_IBASE_EXT_END

Using this you can use SCF_QUERY_INTERFACE(object, csMyClass), i.e. use the class without an interface.

Another change is that ‘csObject’ stores its children as ‘iObject’ references now. It does not deal with ‘csObject’ pointers any longer. All children are correctly reference-counted. Also, all objects maintain a pointer to their “parent” object. How this pointer is used is left to you. The pointer is not reference-counted in order to avoid circular referencing. Consequently, the classes ‘csPObject’ and ‘csObjNoDel’, and the member function ObjRelease() have been removed.

This usually means that after calling ObjAdd(), you have to call DecRef() on the added child because you don't want to use the reference anymore. Of course, this only applies if you possess a valid reference. Similarly, if you want to unlink the object from its parent without deleting it (i.e. wherever you used ObjRelease() before), you should now call IncRef() on the child before removing it from its parent.

Platform Portability Encapsulation

The new macro ‘CS_IMPLEMENT_APPLICATION’ must now be invoked by exactly one compilation unit of each application. This macro encapsulates platform-specific implementation details for any given platform. For instance, on Windows, this macro defines the WinMain() function required by all Windows GUI applications.

The new macro ‘CS_IMPLEMENT_PLUGIN’ must now be invoked by exactly one compilation unit of each plugin module. This macro encapsulates platform-specific implementation details for any given platform. For instance, on Windows, this macro defines the DllMain() function required by all Windows DLL modules.

These macros alleviate the need to link applications with specially prepared object files or libraries. The summary below explains what this means for various platforms.

Unix

No longer required to link plugin modules against the ‘dummy.o’ file.

Visual-C++

No longer required to link applications against Crystal Space's ‘win32exe.lib’ library. No longer required to link plugin modules (DLL's) against the ‘win32dll.lib’ library. Also, the ‘libwin32exe.dsp’ and ‘libwin32dll.dsp’ project files have been removed.

Mingw

No longer required to link applications with the ‘exeentry.o’ object file. No longer required to link plugin modules (DLL's) with the ‘dllentry.o’ object file.

OS/2

No longer required to link plugin modules with the ‘dllentry.o’ object file.

System Driver Removal and Application Structure

The classes SysSystemDriver, and csSystemDriver, and the interface iSystem have been removed. All the functionality that used to be present in the system driver has moved to smaller components (plugin manager, event queue, configuration manager, commandline parser, virtual clock, etc.).

There is now a new concept called the object registry which is the central repository where all objects can register themselves. When you used to do CS_QUERY_PLUGIN you now have to do CS_QUERY_REGISTRY instead.

Applications can no longer inherit from SysSystemDriver. Instead there is now a new csInitializer class which helps in the initialization of an application. Check out the simple tutorial (see section Simple Tutorial 1: Basic Setup, World Creation) to see how this works. This tutorial also explains all the new concepts very clearly.

Removal of Function ID's

Function ID's (a concept of the old plugin system) have been removed. This has an effect on configuration files where you now must replace things like:

 
System.PlugIns.LevelLoader = crystalspace.level.loader

with:

 
System.PlugIns.iLoader = crystalspace.level.loader

So in general use the interface name. This interface name will be the tag with which the loaded plugin is registered in the object registry.

Image Loading

‘csImageLoader’ is gone and has now become a plugin which implements the ‘iImageIO’ interface. To use it you typically use the following code:

 
#include "igraphic/imageio.h"
...
iDataBuffer* buf = ...;
iImageIO* imgldr = CS_QUERY_PLUGIN (System, iImageIO);
imgldr->Load (buf->GetUint8 (), buf->GetSize (),
txtmgr->GetTextureFormat ());
...
imgldr->DecRef ();

Map Loading (csLoader)

The level loader is now a plugin. Make sure you have it loaded by putting the following in your configuration file:

 
System.PlugIns.iLoader = crystalspace.level.loader

Or you can add ‘CS_REQUEST_LEVELLOADER’ to the list of requested plugin in the call to csInitializer::RequestPlugins(). Then you can get the level loader with:

 
iLoader* level_loader = CS_QUERY_REGISTRY (object_reg, iLoader);

When you don't need it anymore you must call level_loader->DecRef (). Check the API reference to see what functions you can use on level_loader. There are functions to load a map, textures, mesh objects, etc. Many of these functions have been renamed as well.

Things are Mesh Objects

Things are now mesh objects which means that you can no longer access csThing directly. iThing has been removed. Instead there is iThingState. Check out the simple tutorial (see section Simple Tutorial 1: Basic Setup, World Creation) for more information about this.

Map File Changes

The following map file elements have changed:

Sky Objects Removed

Sky objects must now be created the same as normal mesh objects but you need to give them a low render priority (i.e. 'sky' render priority).

Using the Engine as a Plugin

It is now recommended to use the engine as a plugin. Linking directly to the ‘csengine’ library is still possible but strongly discouraged. We will not be able to guarantee API compatibility on this level.

Using the engine as a plugin means in the first loading the engine plugin instead of linking to the ‘csengine’ library. You can do this with:

 
csInitializer::RequestPlugins (object_reg,
  CS_REQUEST_ENGINE,
  ...,
  CS_REQUEST_END);
iEngine* engine = CS_QUERY_REGISTRY (object_reg, iEngine);

You then use the engine through SCF interfaces. Therefore, your programs should include header files from ‘CS/include/iengine’ rather than ‘CS/include/csengine’. Importing files from ‘CS/include/csengine’ is discouraged.

Sectors Have No Polygons

Sectors can no longer contain polygons. All geometry is now represented with mesh objects (see the section above about how to create csThing mesh objects). To create the outer walls of a sector (i.e. the geometry that used to go to the sector in 0.18 or earlier) you create a csThing mesh object. In a world file this happens like this:

 
SECTOR 'room' (
  MESHOBJ 'walls' (
    PLUGIN ('crystalspace.mesh.loader.thing')
    PARAMS (
      VERTEX (...) ...
      POLYGON (...) ...
    )
    ZFILL ()
    PRIORITY ('wall')
  )
  ...
)

In code you can use iEngine::CreateSectorWallsMesh() like this:

 
iMeshWrapper* mesh =
  engine->CreateSectorWallsMesh (sector, "walls");

Header Directory Changes

All SCF interfaces (class names starting with the letter ‘i’ such as ‘iPolygon3D’) have moved from ‘CS/include’ to individual subddirectories of ‘CS/include’. A few brief examples:

The following new header directories exist:

include/iengine

Everything related to the engine itself (view.h, camera.h, light.h, sector.h, engine.h, texture.h, ...).

include/igame

For the ‘csgame’ plugin (csgame.h).

include/igeom

For the ‘csgeom’ library (clip2d.h).

include/igraphic

For the ‘csgfx’ library and the image loader plugins (image.h, imageio.h, and loader.h).

include/imap

For the map loader and mesh object loaders and savers (parser.h, reader.h, and writer.h).

include/imesh

For everything related to mesh objects and the state interfaces of mesh objects (object.h, spr3d.h, ball.h, thing.h, ...).

include/inetwork

For networking plugins (driver.h and socket.h).

include/isound

For sound (listener.h, renderer.h, ...).

include/isys

Everything related to the system driver and its facilities (event.h, evdefs.h, plugin.h, vfs.h, and system.h).

include/iutil

For the ‘csutil’ library (string.h, object.h, config.h, ...).

include/ivideo

Everything for the 3D and 2D driver subsystems (graph2d.h, graph3d.h, texture.h, fontserv.h, txtmgr.h, ...).

include/ivaria

Everything that does not fit anywhere else (collider.h, conin.h, conout.h, iso.h, keyval.h, script.h, ...).

Global API Changes

All SCF macro names are now prefixed with ‘SCF_’ in order to avoid polluting the global namespace.

Plugin management macro names are now prefixed with ‘CS_’ in order to avoid polluting the global namespace.

Macros for classifying events are now prefixed with ‘CS_’ in order to avoid polluting the global namespace.

Platform-specific configuration macros are now prefixed with ‘CS_’ in order to avoid polluting the global namespace.

All ‘csVector’-related macros are now prefixed with ‘CS_’ in order to avoid polluting the global namespace. Furthermore, DECLARE_TYPED_SCF_VECTOR() has been renamed to CS_DECLARE_TYPED_IBASE_VECTOR() in order to more clearly indicate that this array type works with reference-counted ‘iBase’ objects.

All ‘SYSDEF_BLAH’ request macros are now prefixed with ‘CS_’ in order to avoid polluting the global namespace. Furthermore, each macro name now contains the word “provide” since these macros are used by client code to request that ‘cssysdef.h’ provides certain facilities.

Methods in many classes and SCF interfaces have been renamed in order to improve naming consistency throughout the project. The following method name changes follow the pattern where GetNumSomething() or GetNumberSomething() became GetSomethingCount().

The prefix ‘cs’ was added to the following list of functions, and their names were also normalized.

Library Renamed: csfx

The ‘csfx’ library was renamed to ‘cstool’.

Library Removed: csobject

The ‘csobject’ library has been removed. All files in that library have moved to ‘csutil’.

csCollider

The ‘csCollider’ facility moved from ‘csengine’ to ‘cstool’ and was renamed to ‘csColliderWrapper’.

Key/Node Mechanism

The ‘csKeyValuePair’ and ‘csMapNode’ classes moved from ‘csengine’ to ‘cstool’.

csView

The ‘csView’ class moved from ‘csengine’ to ‘cstool’.

DDG Terrain Engine Removed

The DDG landscape engine which used to be featured in Crystal Space has been removed and was replaced with a simpler landscape engine, but one which is better integrated with the project. It is now also a mesh object.

CSWS Modal Session Paradigm Shift

csApp::Execute() has been removed. This method ran a modal session for dialog panels, and would only return control to the caller when the dialog was dismissed. As a replacement for Execute(), csApp::StartModal() and csApp::StopModal() have been introduced. StartModal() sets up modality for the given component and then immediately returns to the caller. From the perspective of the GUI user the component behaves in the standard modal fashion, but from the perspective of the application programmer this represents a paradigm shift since the application must now watch events arriving in its csApp::HandleEvent() method in order to determine when the modal session has terminated. Notification arrives in the form of a ‘csevCommand’ event with command code cscmdStopModal. This is sent when then component's modal session terminates, such as when the “OK” or “Cancel” button is pressed.

With StartModal() you can provide a userdata argument (which is an SCF interface that you can implement on your own). The userdata will be available at any time while the modal session is active by calling csApp::GetTopModalUserdata(). The modal component can be retrieved with csApp::GetTopModalComponent(). The ‘Event.Command.Info’ field will be an integer containing the ID of the pressed button (i.e. cscmdOK, cscmdCancel, etc.).

A related change was made to csMessageBox(). It also now returns immediately. It nows sends a similar message to the application when the message box is closed (via “OK” or “Cancel”). In this case, the userdata object will implement the SCF interface iMessageBoxData, so you can use SCF_QUERY_INTERFACE() to check for this.

Here is an example on how to define your own userdata object.

 
struct ModalData : public iBase
{
  ...
  SCF_DECLARE_IBASE;
  ModalData ()
  {
    SCF_CONSTRUCT_IBASE (NULL);
  }
};

SCF_IMPLEMENT_IBASE (ModalData)
SCF_IMPLEMENT_IBASE_END

bool MyApp::HandleEvent (iEvent &Event)
{
  switch (Event.Type)
  {
    case csevCommand:
      switch (Event.Command.Code)
      {
        case APP_OPEN_FILE:
        { // Allow user to select a file with csFileDialog.
          csWindow* d = csFileDialog (this, "test file dialog");
          ModalData* data = new ModalData ();
          ...
          StartModal (d, data);
          data->DecRef ();
          return true;
        }
        case cscmdStopModal:
        {
          csComponent* d = GetTopModalComponent ();
          int rc = (int)Event.Command.Info;
          if (rc == 0 || rc == cscmdCancel)
          {
            delete d;
            return true;
          }
          iMessageBoxData* mbd =
            SCF_QUERY_INTERFACE (d, iMessageBoxData);
          if (mbd)
          {
            mbd->DecRef ();
            delete d;
            return true;
          }
          ModalData* md = (ModalData*)GetTopModalUserdata ();
          ... // csFileDialog was closed.
          return true;
        }
        ...
}

3D Sprite Factories

The sprite factory interface has been modified to show the restrictions of 3D sprites and to clean it up:

Miscellaneous Changes

The SCF name of the 3D engine changed:

crystalspace.engine.core => crystalspace.engine.3d

csEngine::NextFrame() and iEngine::NextFrame() are removed. This is now done automatically in csEngine::Draw().

Renamed iPortal::GetPortal() to GetSector() and iPortal::SetPortal() to SetSector().

Removed csMeshWrapper::GetChildren(). Instead use csMeshWrapper::AddChild() and csMeshWrapper::RemoveChild().

Renamed iEngine::CreateMeshObject() to iEngine::CreateMeshWrapper(). In general all iEngine functions that work mesh wrappers will be renamed like that.

Renamed csFilenameMatches() to csGlobMatches() (from ‘csutil’ library).

From the ‘iEngine’ interface, these two methods were removed:

They were replaced by these methods:

‘FrameWidth’ and ‘FrameHeight’ are no longer available in ‘SysSystemDriver’ (entire system driver is gone, in fact). Instead you have to call GetWidth() and GetHeight() on the pointer to the canvas (‘iGraphics2D’).

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

This document was generated using texi2html 1.76.