C.1.8 Libraries and Headers Changes

Library Consolidation

In order to simplify end-user documentation and client usage, the Crystal Space link libraries `csutil', `csgeom', `csgfx', and `cstool' have been merged into a single master library named `crystalspace' (i.e. `libcrystalspace.a' or `crystalspace.lib').

The tools `cs-config' and `jamtemplate' (see section Creating an External Crystal Space Application), documentation, and all other client-oriented utilities have been updated appropriately to reflect this change. If you had installed Crystal Space previously, you should manually removed the now obsolete installed libraries from the installation location (typically, `${prefix}/lib').

Developers of Crystal Space itself should note that the sources and headers continue to reside in their separate `csutil', `csgeom', etc., directories; and (importantly) the modules themselves remain conceptually distinct. This will not change. The consolidation of the physical link library was an end-user convenience.

Convenience Classes and Libraries

Crystal Space now publishes several convenience classes and libraries which eliminate much of the drudgery associated with implementing SCF interfaces in certain types of common plugin modules. For example, the `csGraphics2D' class implements the `iGraphics2D' interface and provides much of the functionality common to most canvases. Likewise, the `csGraphics3D' class implements the `iGraphics3D' interface and provides much functionality common to renderers. You are not required to utilize these implementations when authoring your own plugins, but they are available for your convenience.

Most of these newly published facilities are bundled in the consolidated master `crystalspace' library, but a few are provided in separate libraries because they rely upon external resources which may not be present on all platforms or in all installations. The convenience libraries are:

crystalspace

Canvas, image loader, particle system, renderer, shader, sound loader, and sound renderer support, in addition to the normal Crystal Space classes and utilities.

crystalspace_directx

DirectX support.

crystalspace_macosx

MacOS/X canvas support.

crystalspace_opengl

OpenGL support.

crystalspace_python

Python support.

crystalspace_windows

Windows support.

For a complete list of available convenience classes, consult the header files in the subdirectories of `CS/include/csplugincommon'.

Convenience Headers

For convenience, several top-level master header files have been added to the project. These should simplify client usage by allowing users to choose the level of granularity which suits them best. The list of new header files follows.

crystalspace.h

Nearly all public headers in entire Crystal Space SDK.

csgeom.h

Content of `CS/include/csgeom'.

csgfx.h

Content of `CS/include/csgfx'.

csplugincommon.h

Content of `CS/include/csplugincommon'.

cstool.h

Content of `CS/include/cstool'.

csutil.h

Content of `CS/include/csutil'.

iaws.h

Content of `CS/include/iaws'.

iengine.h

Content of `CS/include/iengine'.

igeom.h

Content of `CS/include/igeom'.

igraphic.h

Content of `CS/include/igraphic'.

imap.h

Content of `CS/include/imap'.

imesh.h

Content of `CS/include/imesh'.

inetwork.h

Content of `CS/include/inetwork'.

isound.h

Content of `CS/include/isound'.

itexture.h

Content of `CS/include/itexture'.

iutil.h

Content of `CS/include/iutil'.

ivaria.h

Content of `CS/include/ivaria'.

ivideo.h

Content of `CS/include/ivideo'.

Users new to the SDK will probably want to include `crystalspace.h' since it is simplest; whereas more advanced users may want to include `csutil.h', `cstool.h', etc.; and power users can continue to include only the individual headers required by a particular piece of code.

As a corollary, the old `CS/include/css.h' header, which included many, though not all Crystal Space header files, has been removed. If you require this type functionality from a header, then include the new `crystalspace.h' instead.

Be aware that there is a very small set of public headers not included in any of the master headers. These are omitted from the master headers because they reference external resources which might not be known or available to all clients of the master headers. Clients requiring these special-case headers will need to include them manually, on an as-needed basis, and arrange that the build system has sufficient knowledge about the external resources to satisfy the dependencies at build time. The list of headers which are excluded from the master headers follows.

csplugincommon/directx/*.h

DirectX-specific.

csplugincommon/macosx/*.h

MacOS/X-specific.

csplugincommon/opengl/*.h

OpenGL-specific.

csplugincommon/win32/*.h

Windows-specific.

csutil/archive.h

Requires zlib indirectly via `csutil/zip.h'.

csutil/getopt.h

Conflicts with platform-supplied `<getopt.h>'.

csutil/zip.h

Requires zlib; http://www.gzip.org/zlib/

inetwork/vosapi.h

Requires VOS; http://www.interreality.org/

ivaria/ode.h

Requires ODE; http://www.ode.org/

ivideo/wxwin.h

Requires wxWidgets; http://www.wxwidgets.org/

As an example, if you need access to the `iWxWindow' interface, then you must include `ivideo/wxwin.h' manually; it will not be included as part of `crystalspace.h' or `ivideo.h'. Furthermore, you will need to let the build system know where it can find the wxWidgets resources (headers and libraries). Typically, this is done by adding a wxWidgets check to your project's `configure' script; emitting the results of the check to your `Jamconfig' file with the CS_EMIT_BUILD_RESULT() Autoconf macro; and finally utilizing the result of that check in your project's `Jamfile' by invoking the Jam rule `ExternalLibs'. For MSVC project files, the location of the wxWidgets resources will have to be added as additional include directories and additional library directories, in the project settings or globally, to ensure that MSVC will be able to find them.

`cssysdef.h' Changes

The `CS_SYSDEF_PROVIDE_FACILITY' macros, which clients would #define before including `cssysdef.h' in order to alter the behavior of `cssysdef.h', have been removed. Retirement of these macros eliminates the polymorphic behavior of `cssysdef.h', thus helping to pave the way toward eventually pre-compiling Crystal Space's headers in order to reduce overall compilation time. In addition to removing these macros from your code, the following table explains what else (if anything) needs to be done to account for the removal.

CS_SYSDEF_PROVIDE_ACCESS

No additional changes.

CS_SYSDEF_PROVIDE_ALLOCA

Use the `CS_ALLOC_STACK_ARRAY()' macro, rather than alloca().

CS_SYSDEF_PROVIDE_CASE

No additional changes.

CS_SYSDEF_PROVIDE_DIR

No additional changes.

CS_SYSDEF_PROVIDE_EXPAND_PATH

No additional changes.

CS_SYSDEF_PROVIDE_GETCWD

No additional changes.

CS_SYSDEF_PROVIDE_GETOPT

Include `csutil/getopt.h'.

CS_SYSDEF_PROVIDE_MKDIR

Use the `CS_MKDIR(path)' macro to create the directory, rather than the obsolete `MKDIR()' macro.

CS_SYSDEF_PROVIDE_PATH

No additional changes.

CS_SYSDEF_PROVIDE_SELECT

No additional changes.

CS_SYSDEF_PROVIDE_SOCKETS

Include `csutil/sockets.h'.

CS_SYSDEF_PROVIDE_SOFTWARE2D

No additional changes.

CS_SYSDEF_PROVIDE_TEMP

Use the `CS_TEMP_DIR' and `CS_TEMP_FILE' macros, rather than the obsolete `TEMP_DIR' and `TEMP_FILE' macros.

CS_SYSDEF_PROVIDE_UNLINK

No additional changes.

CS_SYSDEF_VFS_PROVIDE_CHECK_VAR

No additional changes.

The age-old restriction that `cssysdef.h' could be included only by source files (`.cpp') has been lifted. This restriction was an unfortunate side-effect of the polymorphic behavior of `cssysdef.h' in the presence of various `CS_SYSDEF_PROVIDE_FACILITY' macros. It is now safe, even recommended, to include `cssysdef.h' in header files (`.h'). Doing so helps to make header files more self-contained, thus reducing the burden of clients of those headers.

C++ Standard Conformance

Crystal Space's public header files are now C++ Language Standard conformant. This means that Crystal Space-based projects which choose to adhere strictly to the C++ Language Standard (such as those which employ gcc's `-ansi' and `-pedantic' options) can now include Crystal Space headers safely.

`imap/parser.h' Deprecated

All functionality in the header `imap/parser.h' was long ago moved to `imap/loader.h', which declares interfaces to access the Crystal Space map loader. At that time, `imap/parser.h' became a very thin wrapper which merely included `imap/loader.h' and did nothing more. Since `imap/parser.h' has no useful purpose, it is now officially deprecated, and deprecation warnings have been added. Use `imap/loader.h' instead.

This document was generated using texi2html 1.76.