4.1.3 Basic Crystal Space Concepts

In order to write a Crystal Space application there are several concepts that you need to know about. Here we will give a quick overview of all important things you need to know about when writing Crystal Space applications. This section explains the concepts from the perspective of using Crystal Space as a framework. Read the next section to learn about engine concepts.

The SCF Facility

The SCF (see section Shared Class Facility (SCF)) system is the core low-level memory framework for Crystal Space. You must initialize this before doing anything else (one way is to use csInitializer::InitializeSCF()).

Reference Counting

Reference counting is a very important part of the Crystal Space framework. Read the SCF (see section Shared Class Facility (SCF)) documentation for more information about this but keep in mind that it is very important and try to make sure you manage references correctly in your own code. Missing a DecRef() can cause big memory leaks.

The Object Registry

The object registry is the central repository for all objects in Crystal Space. Everything in Crystal Space will use the object registry to get the pointer to the objects it is interested in. One of the first tasks a Crystal Space application has to do is to create the object registry. You can create an object registry using csInitializer::CreateObjectRegistry() or csInitializer::CreateEnvironment().

The Plugin Manager

The plugin manager is responsible for loading and unloading plugins. A plugin is a shared library of functions that can be loaded dynamically into a running Crystal Space application. On Unix a plugin has the ‘.so’ extension and on Windows the ‘.dll’ extension is used. Almost everything in the Crystal Space framework is itself a plugin. So the plugin manager is an important object. You can create the plugin manager with csInitializer::CreatePluginManager() or csInitializer::CreateEnvironment().

The Event Queue

Crystal Space is an event-driven framework. So a Crystal Space application will also be event driven. The event queue manages the event system and sends events to listeners. Every module or plugin that implements ‘iEventHandler’ can register itself with the event queue so it gets notified when certain events happen. You can create the event queue with csInitializer::CreateEventQueue() or csInitializer::CreateEnvironment().

A Crystal Space application will also have to create an event handler on its own in order to actually be able to do something. This event handler will be responsible for actually rendering to the screen (this has to be done in response to the cscmdProcess event) and also catching keyboard/mouse input. But there is much more. To setup an event handler for the application you can use csInitializer::SetupEventHandler().

The Virtual Clock

Most Crystal Space applications will be time-based. The virtual clock supports the notion of CURRENT TIME and ELAPSED TIME. It is called a virtual clock because it doesn't necessarily have to correspond with real time. For example, a game can be paused. Note that a well-behaved game should always take elapsed time (between two frames) into consideration for calculating what could have happened in that time. This is important especially for physics calculations and also for speed of moving objects. You want an object moving at some speed to move with the same speed on a system with low framerates compared to a system with high framerates. The virtual clock can be created with csInitializer::CreateVirtualClock() or csInitializer::CreateEnvironment().

The Commandline Parser

The commandline parser is responsible for parsing options from the commandline. If you properly initialize it with ‘argc’ and ‘argv’ then you can use it to query options that have been given to the commandline. Several Crystal Space plugins and modules will also query the commandline so it is important to have this object correctly initialized. The commandline parser can be created with csInitializer::CreateCommandLineParser() or csInitializer::CreateEnvironment().

The Configuration Manager

The configuration manager is responsible for reading options from configuration files. All configuration files are put in a global pool which is managed by the configuration manager. Several Crystal Space plugins and modules will query options from the configuration manager and Crystal Space applications can also do that if they want.

You can create the configuration manager with:

csInitializer::CreateConfigManager()

or

csInitializer::CreateEnvironment()

You can setup the configuration manager with:

csInitializer::SetupConfigManager()

The Input Drivers

There are three standard input drivers included with Crystal Space: keyboard, mouse, and joystick. Calling:

csInitializer::CreateInputDrivers()

or

csInitializer::CreateEnvironment()

will create the drivers and publish them via the object registry. These drivers will post events to the global event queue.

The csInitializer class

We already mentioned several of the functions above. This class (for which the definition can be found in ‘include/cstool/initapp.h’) is a convenience class that can be used to help you setup everything needed to get the application running. In the tutorial below we will use several of the functions from ‘csInitializer’. This class contains only static member functions.

This document was generated using texi2html 1.76.