4.5.4.1 System Configuration

This section describes how the base system can be configured via a configuration file. The default values are stored in ‘CS/data/config/system.cfg’, except the list of default SCF classes to instantiate, for which no default exists. Typically, the list of default requested classes will appear in an application's own configuration file.

List of SCF Classes

The most important part of the system configuration is the list of SCF classes to instantiate by default. A class is instantiated with the following line:

System.Plugins.InterfaceName = ClassName

‘System.Plugins.’ is obligatory and tells the system to instantiate the class at startup. The ‘InterfaceName’ specifies the name of the abstract SCF interface which this module is expected to implement. For example the interface name ‘iGraphics3D’ means that this plug-in is used for 3D rendering. Note that it is not possible to load more than one module with the same functionality identifier.

Finally, ‘ClassName’ determines which SCF class to instantiate. The class you mention here must be designed for the purpose for which you try to use it. In other words, it must implement the interface specified with ‘InterfaceName’ (it may also implement additional interfaces). For example, if you load a sound driver with the ‘iGraphics3D’, the application will not be able to instantiate the driver because it does not implement that interface.

Note that some modules depend on others. If module A depends on module B, then you must first load B, then A. If you don't do this then module A will usually fail to initialize.

Here is an example of a line from the configuration file:

System.Plugins.iGraphics3D = crystalspace.graphics3d.opengl

This line instantiates the SCF class ‘crystalspace.graphics3d.opengl’ (the OpenGL graphics driver) which implements the abstract ‘iGraphics3D’ interface, and makes the instantiated object available via shared object registry.

The interface name mentioned above is exactly the name of the C++ abstract interface which modules implement. Some of the common ones which you will see or use in configuration files are listed below.

iVFS

The virtual file system. Presently, there is only one VFS implementation, and it is named ‘crystalspace.kernel.vfs’.

iGraphics3D

A 3D renderer. Some possible values include

crystalspace.graphics3d.software

Uses the platform-specific 2D canvas to perform 3D graphics operations.

crystalspace.graphics3d.software.offscreen

This is a variant of the software renderer that renders to a buffer in memory, not to the screen.

crystalspace.graphics3d.opengl

Uses OpenGL for 3D output, and by this takes advantage of hardware acceleration. Requires installed OpenGL run-time libraries.

Other Low-Level Configuration Options

Apart from the list of plug-in modules, the following keys are recognized:

System.UserConfig = true

Specifies whether or not user-specific configuration information should be used and maintained. See Config PerUser.

This document was generated using texi2html 1.76.