Enlighten runtime data

The precompute outputs radiosity data for systems, probes and cubemaps. The precompute also produces a set of lightmap UVs for each mesh.

You need this persistent runtime data to display indirect lighting in the game runtime, or in a real time preview within your editing tools. The data is compact and typically uses much less disk space than baked lightmaps.

The runtime data is derived from the world geometry and can be regenerated automatically at any time. Because the time required to regenerate all of the runtime data for a large project can be significant, it is essential to store the persistent runtime data on disk so that it is not necessary to run the precompute every time the scene is loaded.

If the world geometry was modified since the persistent runtime data was generated, you can still use the stale data, but the indirect lighting may be incorrect.

Data flow

The diagram below shows how data flows from the Enlighten scene to the persistent runtime data.

The precompute process stores the result of the precompute in the precomp and radiosity sub-directories within the __Build_<scene>__ directory at the scene root. When the precompute process completes successfully, extract the persistent runtime data from these locations and store it in a form ready to be loaded by the game runtime and editing tools.

The precompute generates a lot of additional intermediate data in the __Build_<scene>__ directory . To keep the size of stored persistent runtime data small, extract only the parts of the result that you need.

The exported Enlighten scene and the intermediate data in __Build_<scene>__ are used only by the precompute and debugging tools, and are not required for runtime radiosity updates.

For a prototype implementation you might load files from the __Build_<scene>__ directory directly in your game runtime, but this would not be practical in a production implementation.

Data layout

Enlighten runtime data is grouped into separate objects for each system, probe set and cubemap.

For most implementations, we recommend to use the precompute pipeline API both to run the precompute and to load these objects.

To find the automatically generated systems in a zone, load the IPrecompGeneratedSystems object.

// path: "precomp/[zone name].gs"
const Enlighten::IPrecompGeneratedSystems* generatedSystems
	= Geo::LoadInterfaceCompressed<Enlighten::IPrecompGeneratedSystems>(path);

for (Geo::s32 systemIndex = 0; systemIndex != generatedSystems->GetNumSystems(); ++systemIndex)
{
	const Enlighten::IPrecompInputSystem* inputSystem = generatedSystems->GetSystem(systemIndex);
	Geo::GeoFileString systemName(inputSystem->GetName());

	// extract radiosity data associated with this system
}

To find the automatically generated probe sets in a zone, load the IPrecompOutputProbeOctree object.

// path: "precomp/[zone name].opo"
// paramSetName (optional): the value of the probesParamSet attribute of the probeRegions within the zone
const Enlighten::IPrecompOutputProbeOctree* probeOctree
	= Geo::LoadInterfaceCompressed<Enlighten::IPrecompOutputProbeOctree>(path);

for (Geo::s32 probeSetIndex = 0; probeSetIndex != probeOctree->GetLocalProbeSetCount(); ++probeSetIndex)
{
	Enlighten::PrecompOctreeCode octreeCode = probeOctree->GetProbeSetOctreeCode(probeSetIndex);
	Geo::GeoFileString probeSetName = Enlighten::PipelinePaths::MakeOctreeProbeSetName(octreeCode, paramSetName);

	// extract radiosity data associated with this probe set
}

Each probe set name refers to a chunk of unique radiosity data. The same probe set name may appear in more than one zone. When two zones are loaded in the game runtime, you can save memory by storing only one copy of the radiosity data common to both zones.

When you add a cubemap to the Enlighten scene, keep track of its name so that you can extract the runtime data after the precompute.

If you choose to use explicit system groups or manually placed probes, keep track of the system and probe set names in the same way.

We recommend to combine all systems, probe sets and cubemaps in a single zone into a single chunk for efficient load in your runtime file-system.

Below is a practical example of the data layout for a single chunk:

for each lightmap UV set
- lightmap UV array
for each lightmap-lit system
- lightmap-lit system radiosity data
for each probe-lit system
- probe-lit system radiosity data
for each lightmap-lit instance
- instance GUID
- pointer to lightmap UV set
- lightmap UV transform
- index of lightmap-lit system
for each probe set
- probe set radiosity data
for each cubemap
- cubemap radiosity data

We recommend to compress each chunk of persistent runtime data on disk to save space and speed up loading.

Large teams

For production use of Enlighten within a large team we recommend to consider two workflows in which the runtime data is generated. Both involve running the precompute, but each has quite different requirements.

1. Enable the artist to iterate on Enlighten configuration of (part of) the world in the editor tools.

The artist chooses to precompute only parts of the world that are relevant to them, to reduce the time taken.
The artist chooses to start the precompute after making a significant change to the world.
To preview the lightmap layout, the artist can choose to quickly generate only lightmap UVs.
Include the artist's in-progress changes to the world so that they can see the effect on indirect lighting.

To get started quickly, implement the above workflow first.

2. Produce a packaged build for review

Automated, ideally as part of an unattended distributed continuous build on a build farm.
Precompute all parts of the world at the same time.
Always use the latest version/configuration of the world.
Run the precompute for each version of the world no more than once.
Store recent build results in a central repository, tied to each version of the world.

This separation provides the following benefits:

In a packaged game build, the Enlighten runtime data should always be reliable. Automating the process helps to minimize human error.
In a large team with many people working on the world, each member of the team does not need to run the precompute locally unless they want to preview the effect of their changes to the world.

Debugging data

The precompute produces debugging data that can be used to debug the runtime. This data is used, for example, in the GeoRadiosity visualisation services; you can use it to create your own visualisations.

For more details, see Debugging the precompute.