RAMSES Client Code Structure

The Client API and its implementation are separated using the PIMPL(*) pattern, to support a high degree of API stability, while still being able to change almost any aspect of the underlying implementation.

(*) PIMPL = Pointer to IMPLementation

The RAMSES Renderer API follows the same priniciples as the Client API, just with much smaller number of classes.

Object Lifecycle

The RAMSES Client API was designed with efficient data structures for distributed use cases. The major impact of that design decision is a strict memory management strategy implemented in the RAMSES framework. Another direct result is the mandatory use of factories to create (and destroy) all framework managed data structures.

All objects created by one of the client API factories (RamsesClient, Scene or AnimationSystem) are owned by the object containing the factory and must be destroyed with the corresponding destroy() function. Using an object after passing it to a destroy() function is an application bug. Destroying the factory automatically destroys all its managed objects.

Any object created by application code is owned by application. RAMSES takes neither ownership nor longer term reference unless explicitly specified in the API.

Resulting Code Rules

1. Every RAMSES client object derives from RamsesObject, directly or indirectly
   • RamsesObject provides functionality common for all RAMSES objects
2. Make its constructor, destructor protected, Copy/Move-constructor deleted
   • force applications to use factories
3. Every PIMPL object derives from RamsesObjectImpl, directly or indirectly
   • RamsesObjectImpl provides functionality common for all PIMPL objects
4. Define factory as its friend
5. The high level API implementation only forwards calls to the internal PIMPL class, only the PIMPL contains logic and has access to internal framework.
6. Factory owns RAMSES client object and the client object owns its PIMPL
7. PIMPLS refer to internal framework data
   • PIMPLS control lifecycle of internal data
8. RAMSES objects are passed as references into all API functions unless nullptr is a valid parameter