Core Module Overview

The clanCore library is the base library used by all other ClanLib libraries. It provides a basic framework with common functionality needed by almost all types of applications.

Platform abstraction

Perhaps the most important features of clanCore are its platform abstraction classes. While the C++ Standard Library also includes a limited platform abstraction, the clanCore classes extend, complement, or completely replace them in some cases.

More information: Threading

General utility classes

In addition to the above classes there are also a few general purpose classes providing infrastructure for other parts of the library.

Thread run-loop

Most operating systems uses a model where a thread receives messages from the host system by participating in a message run loop.

In ClanLib, the run-loop is known as the keep-alive application loop and the following classes provides this infrastructure:

Signals and callbacks

Templates for creating type-safe callbacks are provided by clanCore. They come in two flavors: signals and callbacks.

Signals are one-to-many callback templates. When the invoke function is called on a signal, all connected callback functions are called. clan::Slot is the representation of a connected callback function and if the slot is destroyed the connection to the signal is broken. clan::SlotContainer is provided for keeping multiple slots connected.

Callback templates are just pointing at a single callback function. The clan::invoke can only be called safely if a function has been set. The main advantage callbacks have over signals is that the callback can return a value to the invoking function. A signal would have to pass such a return value by reference.

More information: Template Callbacks

Math

ClanCore sports a lot of classes for doing basic graphics related math. The most important classes are:

Text

All strings are assumed to be UTF-8, unless otherwise specified. std::string is used as the main string class.

XML

Working with XML can be done by using either the XML tokenizer classes, the Document Object Model (DOM) classes, or the XPath evaluator.

JSON

The clan::JsonValue class allows you to parse or generate JSON strings.

I/O devices

The clan::IODevice class implements the classic input/output stream. It is derived by clan::File and others to support various different devices. The full set of classes working with I/O devices are as follows:

File systems

There are several ways to deal with file systems. The clan::File class mentioned above can be used or files can be opened via clan::FileSystem. The file system class supports virtual file systems, such as opening files in a zip file. In addition to this, there are several classes for working with files and paths:

Zip files

Zip files can be managed using either the clan::FileSystem class mentioned in the file systems section, or they can be read or written using the following lower level classes:

Resource management

The resource management system in ClanLib is based on the principle that for each resource type there is a resource cache object responsible for fetching resources of that type.

Since resources can be virtually anything (images, textures, 3D meshes, shared GPU objects, etc), the system relies on casting the generic clan::ResourceObject class to a specific clan::Resource<Type> object. The clan::Resource<Type> template can return a reference the actual shared resource object, as well as track if the resource has been modified.

Just like resources can be virtually anything, the method for fetching a clan::ResourceObject also varies from type to type. To get a resource, the resource cache object managing it must first be retrieved. clan::ResourceManager has a clan::get_cache<Type>(name) function with returns a specific cache. For clanDisplay based resources, the cache interface is the clan::DisplayCache class, and it is stored in the clan::ResourceManager with the name "clan.display".

clan::ResourceManager is in other words just a map of cache objects for different resource types. It is possible to create custom resource handling by constructing clan::ResourceManager manually, then attach your own implementation of clan::DisplayCache and so on.

Most applications rely on the default implementation which is provided by constructing clan::XMLResourceManager instead. It loads resources described in an XML file. For the standard objects offered by ClanLib, such as the clan::Sprite class, the above manual fetching of resource is also not needed. The convenience function clan::Sprite::resource(gc, id, resources) takes care of the common case.

Resource infrastructure classes:

More information: Resource Management

Crypto

Cryptographic classes for dealing with SHA hashing, AES encryption and TLS are provided:

Error reporting

To deal with errors, clanCore offers the following functionality: