| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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:
crystalspaceCanvas, image loader, particle system, renderer, shader, sound loader, and sound renderer support, in addition to the normal Crystal Space classes and utilities.
crystalspace_directxDirectX support.
crystalspace_macosxMacOS/X canvas support.
crystalspace_openglOpenGL support.
crystalspace_pythonPython support.
crystalspace_windowsWindows support.
For a complete list of available convenience classes, consult the header files in the subdirectories of ‘CS/include/csplugincommon’.
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.hNearly all public headers in entire Crystal Space SDK.
csgeom.hContent of ‘CS/include/csgeom’.
csgfx.hContent of ‘CS/include/csgfx’.
csplugincommon.hContent of ‘CS/include/csplugincommon’.
cstool.hContent of ‘CS/include/cstool’.
csutil.hContent of ‘CS/include/csutil’.
iaws.hContent of ‘CS/include/iaws’.
iengine.hContent of ‘CS/include/iengine’.
igeom.hContent of ‘CS/include/igeom’.
igraphic.hContent of ‘CS/include/igraphic’.
imap.hContent of ‘CS/include/imap’.
imesh.hContent of ‘CS/include/imesh’.
inetwork.hContent of ‘CS/include/inetwork’.
isound.hContent of ‘CS/include/isound’.
itexture.hContent of ‘CS/include/itexture’.
iutil.hContent of ‘CS/include/iutil’.
ivaria.hContent of ‘CS/include/ivaria’.
ivideo.hContent 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/*.hDirectX-specific.
csplugincommon/macosx/*.hMacOS/X-specific.
csplugincommon/opengl/*.hOpenGL-specific.
csplugincommon/win32/*.hWindows-specific.
csutil/archive.hRequires zlib indirectly via ‘csutil/zip.h’.
csutil/getopt.hConflicts with platform-supplied ‘<getopt.h>’.
csutil/zip.hRequires zlib; http://www.gzip.org/zlib/
inetwork/vosapi.hRequires VOS; http://www.interreality.org/
ivaria/ode.hRequires ODE; http://www.ode.org/
ivideo/wxwin.hRequires 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.
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_ACCESSNo additional changes.
CS_SYSDEF_PROVIDE_ALLOCAUse the ‘CS_ALLOC_STACK_ARRAY()’ macro, rather than alloca().
CS_SYSDEF_PROVIDE_CASENo additional changes.
CS_SYSDEF_PROVIDE_DIRNo additional changes.
CS_SYSDEF_PROVIDE_EXPAND_PATHNo additional changes.
CS_SYSDEF_PROVIDE_GETCWDNo additional changes.
CS_SYSDEF_PROVIDE_GETOPTInclude ‘csutil/getopt.h’.
CS_SYSDEF_PROVIDE_MKDIRUse the ‘CS_MKDIR(path)’ macro to create the directory, rather than the obsolete ‘MKDIR()’ macro.
CS_SYSDEF_PROVIDE_PATHNo additional changes.
CS_SYSDEF_PROVIDE_SELECTNo additional changes.
CS_SYSDEF_PROVIDE_SOCKETSInclude ‘csutil/sockets.h’.
CS_SYSDEF_PROVIDE_SOFTWARE2DNo additional changes.
CS_SYSDEF_PROVIDE_TEMPUse the ‘CS_TEMP_DIR’ and ‘CS_TEMP_FILE’ macros, rather than the obsolete ‘TEMP_DIR’ and ‘TEMP_FILE’ macros.
CS_SYSDEF_PROVIDE_UNLINKNo additional changes.
CS_SYSDEF_VFS_PROVIDE_CHECK_VARNo 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.
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.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated using texi2html 1.76.