Crystal Space 2.0.0: C.5.8 Libraries and Headers Changes

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

### C.5.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.

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

This document was generated using texi2html 1.76.