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

## 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:

- `PLANE` => `ADDON`
- `THING` => `MESHOBJ`
- `SKY` => `MESHOBJ + RENDPRI`
- `MESHOBJ` => `MESHFACT` -- (for factories)
- `BEZIER` => `ADDON`
- `MATERIALS`
- `RENDERPRIORITIES`
- `PLUGINS`

### 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:

- `imeshobj.h` => `imesh/object.h` and `iengine/mesh.h`
- `light.h` => `iengine/light.h`

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.

- `CONSTRUCT_EMBEDDED_IBASE` => `SCF_CONSTRUCT_EMBEDDED_IBASE`
- `CONSTRUCT_IBASE` => `SCF_CONSTRUCT_IBASE`
- `CREATE_INSTANCE` => `SCF_CREATE_INSTANCE`
- `DECLARE_EMBEDDED_IBASE` => `SCF_DECLARE_EMBEDDED_IBASE`
- `DECLARE_FACTORY` => `SCF_DECLARE_FACTORY`
- `DECLARE_FAST_INTERFACE` => `SCF_DECLARE_FAST_INTERFACE`
- `DECLARE_IBASE_EXT` => `SCF_DECLARE_IBASE_EXT`
- `DECLARE_IBASE` => `SCF_DECLARE_IBASE`
- `DEC_REF` => `SCF_DEC_REF`
- `EXPORT_CLASS_DEP` => `SCF_EXPORT_CLASS_DEP`
- `EXPORT_CLASS_TABLE_END` => `SCF_EXPORT_CLASS_TABLE_END`
- `EXPORT_CLASS_TABLE` => `SCF_EXPORT_CLASS_TABLE`
- `EXPORT_CLASS` => `SCF_EXPORT_CLASS`
- `IMPLEMENTS_EMBEDDED_INTERFACE` => `SCF_IMPLEMENTS_EMBEDDED_INTERFACE`
- `IMPLEMENTS_INTERFACE_COMMON` => `SCF_IMPLEMENTS_INTERFACE_COMMON`
- `IMPLEMENTS_INTERFACE` => `SCF_IMPLEMENTS_INTERFACE`
- `IMPLEMENT_EMBEDDED_IBASE_DECREF` => `SCF_IMPLEMENT_EMBEDDED_IBASE_DECREF`
- `IMPLEMENT_EMBEDDED_IBASE_END` => `SCF_IMPLEMENT_EMBEDDED_IBASE_END`
- `IMPLEMENT_EMBEDDED_IBASE_GETREFCOUNT` =>
  `SCF_IMPLEMENT_EMBEDDED_IBASE_GETREFCOUNT`
- `IMPLEMENT_EMBEDDED_IBASE_INCREF` => `SCF_IMPLEMENT_EMBEDDED_IBASE_INCREF`
- `IMPLEMENT_EMBEDDED_IBASE_QUERY_END` =>
  `SCF_IMPLEMENT_EMBEDDED_IBASE_QUERY_END`
- `IMPLEMENT_EMBEDDED_IBASE_QUERY` => `SCF_IMPLEMENT_EMBEDDED_IBASE_QUERY`
- `IMPLEMENT_EMBEDDED_IBASE` => `SCF_IMPLEMENT_EMBEDDED_IBASE`
- `IMPLEMENT_FACTORY` => `SCF_IMPLEMENT_FACTORY`
- `IMPLEMENT_IBASE_DECREF` => `SCF_IMPLEMENT_IBASE_DECREF`
- `IMPLEMENT_IBASE_END` => `SCF_IMPLEMENT_IBASE_END`
- `IMPLEMENT_IBASE_EXT_DECREF` => `SCF_IMPLEMENT_IBASE_EXT_DECREF`
- `IMPLEMENT_IBASE_EXT_END` => `SCF_IMPLEMENT_IBASE_EXT_END`
- `IMPLEMENT_IBASE_EXT_GETREFCOUNT` => `SCF_IMPLEMENT_IBASE_EXT_GETREFCOUNT`
- `IMPLEMENT_IBASE_EXT_INCREF` => `SCF_IMPLEMENT_IBASE_EXT_INCREF`
- `IMPLEMENT_IBASE_EXT_QUERY_END` => `SCF_IMPLEMENT_IBASE_EXT_QUERY_END`
- `IMPLEMENT_IBASE_EXT_QUERY` => `SCF_IMPLEMENT_IBASE_EXT_QUERY`
- `IMPLEMENT_IBASE_EXT` => `SCF_IMPLEMENT_IBASE_EXT`
- `IMPLEMENT_IBASE_GETREFCOUNT` => `SCF_IMPLEMENT_IBASE_GETREFCOUNT`
- `IMPLEMENT_IBASE_INCREF` => `SCF_IMPLEMENT_IBASE_INCREF`
- `IMPLEMENT_IBASE_QUERY_END` => `SCF_IMPLEMENT_IBASE_QUERY_END`
- `IMPLEMENT_IBASE_QUERY` => `SCF_IMPLEMENT_IBASE_QUERY`
- `IMPLEMENT_IBASE` => `SCF_IMPLEMENT_IBASE`
- `INC_REF` => `SCF_INC_REF`
- `QUERY_INTERFACE_FAST` => `SCF_QUERY_INTERFACE_FAST`
- `QUERY_INTERFACE_SAFE` => `SCF_QUERY_INTERFACE_SAFE`
- `QUERY_INTERFACE` => `SCF_QUERY_INTERFACE`
- `REGISTER_STATIC_CLASS_DEP` => `SCF_REGISTER_STATIC_CLASS_DEP`
- `REGISTER_STATIC_CLASS` => `SCF_REGISTER_STATIC_CLASS`
- `REGISTER_STATIC_LIBRARY` => `SCF_REGISTER_STATIC_LIBRARY`

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

- `QUERY_PLUGIN_CLASS` => `CS_QUERY_PLUGIN_CLASS`
- `LOAD_PLUGIN` => `CS_LOAD_PLUGIN`
- `_LOAD_PLUGIN` => `CS_LOAD_PLUGIN_ALWAYS`

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

- `IS_KEYBOARD_EVENT` => `CS_IS_KEYBOARD_EVENT`
- `IS_MOUSE_EVENT` => `CS_IS_MOUSE_EVENT`
- `IS_JOYSTICK_EVENT` => `CS_IS_JOYSTICK_EVENT`
- `IS_NETWORK_EVENT` => `CS_IS_NETWORK_EVENT`

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

- `SOFTWARE_2D_DRIVER` => `CS_SOFTWARE_2D_DRIVER`
- `OPENGL_2D_DRIVER` => `CS_OPENGL_2D_DRIVER`
- `GLIDE_2D_DRIVER` => `CS_GLIDE_2D_DRIVER`
- `SOUND_DRIVER` => `CS_SOUND_DRIVER`

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.

- `BEGIN_TYPED_VECTOR()` => `CS_BEGIN_TYPED_VECTOR()`
- `FINISH_TYPED_VECTOR()` => `CS_FINISH_TYPED_VECTOR()`
- `DECLARE_TYPED_VECTOR()` => `CS_DECLARE_TYPED_VECTOR()`
- `DECLARE_TYPED_VECTOR_HELPER()` => `CS_CS_DECLARE_TYPED_VECTOR_HELPER()`
- `DECLARE_TYPED_VECTOR_NODELETE()` => `CS_CS_DECLARE_TYPED_VECTOR_NODELETE()`
- `DECLARE_TYPED_SCF_VECTOR()` => `CS_DECLARE_TYPED_IBASE_VECTOR()`

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.

- `SYSDEF_ACCESS` => `CS_SYSDEF_PROVIDE_ACCESS`
- `SYSDEF_ALLOCA` => `CS_SYSDEF_PROVIDE_ALLOCA`
- `SYSDEF_CASE` => `CS_SYSDEF_PROVIDE_CASE`
- `SYSDEF_DIR` => `CS_SYSDEF_PROVIDE_DIR`
- `SYSDEF_GETCWD` => `CS_SYSDEF_PROVIDE_GETCWD`
- `SYSDEF_GETOPT` => `CS_SYSDEF_PROVIDE_GETOPT`
- `SYSDEF_MKDIR` => `CS_SYSDEF_PROVIDE_MKDIR`
- `SYSDEF_PATH` => `CS_SYSDEF_PROVIDE_PATH`
- `SYSDEF_SELECT` => `CS_SYSDEF_PROVIDE_SELECT`
- `SYSDEF_SOCKETS` => `CS_SYSDEF_PROVIDE_SOCKETS`
- `SYSDEF_TEMP` => `CS_SYSDEF_PROVIDE_TEMP`
- `SYSDEF_UNLINK` => `CS_SYSDEF_PROVIDE_UNLINK`

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()`.

- `GetMiniBspNumVerts()` => `GetMiniBspVertexCount()`
- `GetNumActions()` => `GetActionCount()`
- `GetNumberAging()` => `GetAgingCount()`
- `GetNumberEmitters()` => `GetEmitterCount()`
- `GetNumberMetaBalls()` => `GetMetaBallCount()`
- `GetNumberParticles()` => `GetParticleCount()`
- `GetNumCameraPositions()` => `GetCameraPositionCount()`
- `GetNumChars()` => `GetCharCount()`
- `GetNumCollections()` => `GetCollectionCount()`
- `GetNumCollisionPairs()` => `GetCollisionPairCount()`
- `GetNumCurves()` => `GetCurveCount()`
- `GetNumCurveVertices()` => `GetCurveVertexCount()`
- `GetNumDimensions()` => `GetDimensionCount()`
- `GetNumEdges()` => `GetEdgeCount()`
- `GetNumElements()` => `GetElementCount()`
- `GetNumFonts()` => `GetFontCount()`
- `GetNumFormats()` => `GetFormatCount()`
- `GetNumFrames()` => `GetFrameCount()`
- `GetNumMaterials()` => `GetMaterialCount()`
- `GetNumMeshFactories()` => `GetMeshFactoryCount()`
- `GetNumMeshObjects()` => `GetMeshObjectCount()`
- `GetNumNormals()` => `GetNormalCount()`
- `GetNumObjects()` => `GetObjectCount()`
- `GetNumPalEntries()` => `GetPalEntryCount()`
- `GetNumPlanes()` => `GetPlaneCount()`
- `GetNumPlugIns()` => `GetPlugInCount()`
- `GetNumPoints()` => `GetPointCount()`
- `GetNumPolygons()` => `GetPolygonCount()`
- `GetNumPolyTxtPlanes()` => `GetPolyTxtPlaneCount()`
- `GetNumRepeats()` => `GetRepeatCount()`
- `GetNumShadows()` => `GetShadowCount()`
- `GetNumSpokes()` => `GetSpokeCount()`
- `GetNumTexels()` => `GetTexelCount()`
- `GetNumTextureLayers()` => `GetTextureLayerCount()`
- `GetNumTextures()` => `GetTextureCount()`
- `GetNumTriangles()` => `GetTriangleCount()`
- `GetNumVertices()` => `GetVertexCount()`
- `GetNumVertsToLight()` => `GetVertexToLightCount()`
- `GetStaticNumSamples()` => `GetStaticSampleCount()`
- `NumVertices()` => `GetVertexCount()`
- `ReportNumberTriangles()` => `ReportTriangleCount()`
- `SetNumber()` => `SetCount()`
- `SetNumberMetaBalls()` => `SetMetaBallCount()`
- `SetNumberParticles()` => `SetParticleCount()`
- `SetNumEdges()` => `SetEdgeCount()`
- `SetNumPolygons()` => `SetPolygonCount()`
- `SetNumSpokes()` => `SetSpokeCount()`
- `SetNumVertices()` => `SetVertexCount()`
- `Update_Num()` => `UpdateCount()`

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

- `ByteSwap16bit()` => `csByteSwap16bit()`
- `ByteSwap16bitBuffer()` => `csByteSwap16bitBuffer()`
- `ByteSwap32bit()` => `csByteSwap32bit()`
- `ByteSwap32bitBuffer()` => `csByteSwap32bitBuffer()`
- `Combinations()` => `csCombinations()`
- `expandname()` => `csExpandName()`
- `FindNearestPowerOf2()` => `csFindNearestPowerOf2()`
- `fnamematches()` => `csFilenameMatches()`
- `fSquare()` => `csSquareFloat()`
- `fSwap()` => `csSwapFloat()`
- `GenerateHalo()` => `csGenerateHalo()`
- `GenerateNova()` => `csGenerateNova()`
- `get_token()` => `csGetToken()`
- `get_token_float()` => `csGetTokenFloat()`
- `get_token_int()` => `csGetTokenInt()`
- `IsPowerOf2()` => `csIsPowerOf2()`
- `iSwap()` => `csSwapInt()`
- `RndNum()` => `csRndNum()`
- `ScanStr()` => `csScanStr()`
- `skip_token()` => `csSkipToken()`
- `splitpath()` => `csSplitPath()`
- `strnew()` => `csStrNew()`

### 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:

- `GetNormalCount()` and `GetTexelCount()` have been removed. Sprites do not allow to have different numbers of vertices, normals and texels. So `GetVertexCount()` should be used instead.
- The ``count'` parameter has been removed from `SetVertices()`, `SetNormals()` and `SetTexels()`. These functions only worked properly if the current number of vertices was passed for ``count'`, so passing the parameter at all makes no sense.
- `GetVertex()`, `GetNormal()` and `GetTexel()` now return ``const'` objects. To modify these objects, `SetVertex()`, `SetNormal()` and `SetTexel()` have been added.

### 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:

- `iEngine::EnableLightingCache()`
- `iEngine::IsLightingCacheEnabled()`

They were replaced by these methods:

- `iEngine::SetLightingCacheMode()`
- `GetLightingCacheMode()`

``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 ] | [ >> ]

This document was generated using texi2html 1.76.