Precompute pipeline

For a simple way to run the precompute process, use the precompute pipeline API from the Enlighten Pipeline library to drive the Enlighten precompute.

The Enlighten Pipeline library is designed to be easy to use and reliable and is intended only for use as part of your build pipeline or your editing tools. 

The API throws exceptions to indicate incorrect usage that is a violation of the API contract. Such an exception indicates a defect in the application, rather than a problem with the user's input. If you enable exception handling in your application, you may handle the exception and choose whether to attempt to continue or simply report a crash and terminate the application.

Limitations

The Enlighten Pipeline library is supported only for use in 64-bit Windows applications.

Only the most commonly used Enlighten features are usable. The following features are not currently supported:

• Baked lighting
• Manual probe placement
• Lightmap LOD
• Geometry objects which contain more than one mesh object within the same LOD level.
• Advanced precompute parameters

Please contact Enlighten support if a feature or option that you require is not usable. Full source code for the Enlighten Pipeline library is provided in case you wish to extend the implementation.

Incorrect or unsupported usage of the API may cause a fatal error message or PipelineError exception or cause the precompute to fail. Check for error messages or review the precompute log file for warnings and errors that may help you to debug the problem.

How to use

The sample pipeline implementation provides a basic example of how to use the precompute pipeline API.

Link your application with the Enlighten Pipeline library and include EnlightenPipeline/PrecomputePipeline.h.

First, create an instance of PrecomputePipeline and provide the following inputs to the constructor:

• the export path: where to export the scene for the High Level Build System.
• the tools path: where to find the High Level Build System tool binaries.
• the PrecomputeParameters to control the High Level Build System.
• the PipelineWorldAxes to enable the Enlighten debugging tools to display your scene correctly.
• the voxel size to determine maximum indirect lighting resolution for automatic probe placement.
• the environment validity parameter, UpperFaces when the sky is never visible far below the horizon.

To assemble the Enlighten scene, call the PipelineScene functions exposed by PrecomputePipeline:

• Call PipelineScene::AddGeom to add each geometry object.
• Call PipelineScene::AddInstance to add each radiosity instance.
• Call PipelineScene::AddInstanceParameters to add a set of parameters that control indirect lighting resolution for radiosity instances.
• Call PipelineScene::AddProbeRegion to add each probe region and configure the indirect lighting resolution for automatic probe placement.
• Call PipelineScene::AddCubemap to add an Enlighten cubemap for each local reflection probe.
• Call PipelineScene::AddRadiosityDependencies to add radiosity dependencies for a group of radiosity instances.

Export the Enlighten scene and run the precompute process:

• Call PrecomputePipeline::WriteScene to export the Enlighten scene. To enable incremental builds, this does not update timestamps for files that did not change since the last export.
• Call PrecomputePipeline::StartPrecompute to launch the precompute process. The parameterize option runs only the first part of the precompute to generate lightmap UVs and automatically place probes.
• To avoid blocking the thread which launched the precompute, call PrecomputePipeline::TryGetPrecomputeResult periodically to see if the precompute process finished.
• Call PrecomputePipeline::CancelPrecompute to kill the High Level Build System parent process and all child processes.
• Call PrecomputePipeline::WaitForPrecompute to put the current thread to sleep until the precompute completes.

Extract only the persistent runtime data you require from the objects that were produced by the precompute:

• To find the automatically generated radiosity systems and probe sets in a zone, call PrecomputePipeline::LoadGeneratedSystems and PrecomputePipeline::LoadOutputProbeOctree
• To obtain the maximum runtime memory footprint of per pixel probe lighting data, call PrecomputePipeline::LoadProbeAtlasMaxima.
• To obtain Lightmap UV data, call PrecomputePipeline::LoadPackedSystem, PrecomputePipeline::LoadPackedGeometry.
• To obtain Persistent radiosity data, call PrecomputePipeline::LoadRadSystemCore, PrecomputePipeline::LoadInputWorkspace, PrecomputePipeline::LoadRadiosityNormalTexture, PrecomputePipeline::LoadPrecomputedVisibilityData, PrecomputePipeline::LoadOctreeProbeSetCore, PrecomputePipeline::LoadRadCubeMapCore.
• To obtain Material colour data, call PrecomputePipeline::LoadClusterAlbedoWorkspaceMaterialData, PrecomputePipeline::LoadSystemDuster.

Extract any additional data that is required to implement visualisations in your world editor.

• To obtain the initial probe positions for an automatically generated probe set, call PrecomputePipeline::LoadInputProbeSet. This is available after running the precompute with or without the parameterize option.
• To obtain the final probe positions for an automatically generated probe set, call ExtractOctreeProbePositions. This is only available after running the full precompute without the parameterize option.