The low level runtime API offers the greatest control and makes as few assumptions about its usage as possible. In particular, it does not allocate memory or perform any filesystem operations. It is a cross-platform API where no performance impact will be incurred, with platform specific differences only where necessary. For details, see the Core Runtime API reference documentation.

We recommend in most cases to use the high level runtime which efficiently handles the most common use-cases of Enlighten.

Overview

The low level runtime API functions read and write buffer objects. All potentially time consuming functions are referred to as 'tasks' in the API and accept buffers for input and output. Tasks are designed to be easily offloaded onto other threads or processors. The Enlighten runtime does not allocate any memory itself and does not hold any internal state outside of the buffers it operates on. The widespread use of buffers allows you complete control of the resources used by Enlighten, but also provides a simple means for you to cache results and skip computation when you know the inputs have not changed. This low level approach gives you maximum control and exposes many opportunities for optimisation.

As a basic overview, the Enlighten runtime operates by taking a description of the direct lighting, writing direct lighting information into incident lighting buffers, adding indirect lighting to produce an input lighting buffer, and then running a 'solve' task to generate the indirect lighting result. The workflow can be visualised like this:

The workflow consists of the following steps:

Provide GPU calculated duster visibility (optional).
Write input lights to incident lighting buffers. See Input lighting.
Composite direct input lighting from the incident lighting buffers with indirect lighting by applying bounce, albedo, and emissive and calculate the lighting difference for temporal solves producing an input lighting buffer.
Solve the radiosity.
Resample light from output texture to produce bounce buffer.

The common theme is of direct lighting being captured into a buffer, composited, and then operated upon (solved) to produce an output. As shown in the diagram, there are nuances that allow for more efficient operation (such as temporal optimisation), or inputs for additional information (such as extra visibility data). For more information, see the detailed Low level runtime walkthrough.

Message reporting and error handling

If you experience problems when using the low level runtime API, call the GeoAttachSystemLogger/GeoAttachLogger functions to issue error and warning messages. For more information, see the API documentation on Message Reporting and Error Handling.