This is the documentation for Enlighten.

The scene root

Owned by Nathan Hunter (Unlicensed)
Oct 31, 2024
2 min read

The HLBS uses the .scene XML format and  .paramset XML format to describe the objects within the scene and their radiosity properties. 

Choose a unique name for the scene element's name attribute. Add a version attribute with the value 1, Save the file under the same name with the .scene extension, within a separate folder with the same name.

Empty/Empty.scene
<?xml version="1.0" encoding="utf-8"?>
<scene name="Empty" version="1">
</scene>

The build system reports an error if the name attribute, filename and containing folder do not match.

To complete your scene, add instances, probes and cubemaps.

Radiosity parameters

Create a separate file named Default.paramset within the same folder as the scene file.

We recommend that you provide a workflow which allows the artist to choose from a few preset combinations of parameters to control indirect lighting resolution.

Add a root parameterSetList element with a version attribute with the value 1. Add at least one of each child element: parameterSet, probesParameterSet and cubeMapParameterSet.

Make sure the name attribute of each child element has a unique name.

The environmentResolution attribute is common to all types of parameter set. This affects the accuracy of the environment light source. The default resolution is 2, effectively resulting in 2 x 2 = 4 values per face. Increase the environment resolution until the accuracy of the lighting is sufficient. We recommend to start with a value of 8, measure the runtime cost and adjust the value if necessary.

The environmentValidity attribute is common to all types of parameter set. Indirect lightmap information is invalidated, and probes are not automatically placed in areas that see the lower face of the environment. Unless the sky will be visible far below the horizon, we recommend to set environmentValidity to UpperFaces and specify the verticalAxis attribute.

Use the same environmentResolution value across all parameter sets in the scene.

The following attributes of parameterSet affect only instances:

  • clusterSize: The size of an input cluster in world space.
  • outputPixelSize: The desired size of an output lightmap pixel in world space (affects only instances that are lit using a lightmap)

The following attributes of probesParameterSet affect only probes

  • shNumCoefficients: The number of spherical harmonic coefficients with which to encode lighting. We recommend to use 4 coefficients, which we refer to as L1 probe lighting.
  • voxelSize: When you use automatic probe placement you must specify the voxelSize parameter to define the maximum resolution of the sparse voxel grid on which probes are placed.

To start with, we recommend to use default values for the remaining parameters. The default values generally provide a good balance between cost and quality for most scenes.

The following .paramset file contains two predefined indirect lighting resolution combinations that the artist can assign to objects in the editor: Interior and Exterior. You might use different values for outputPixelSize and clusterSize depending on the modelling units you use when creating the Enlighten scene.


Default.paramset
<?xml version="1.0" encoding="utf-8"?>
<parameterSetList version="1">
    <parameterSet name="Interior" id="0" environmentResolution="8" outputPixelSize="100" clusterSize="200"/>
    <parameterSet name="Exterior" id="1" environmentResolution="8" outputPixelSize="400" clusterSize="800"/>
    <probesParameterSet name="Probe" environmentResolution="8" shNumCoefficients="4" voxelSize="200"/>
    <cubeMapParameterSet name="Cubemap" environmentResolution="8"/>
</parameterSetList>