This is the documentation for Enlighten.

Albedo handling

Owned by William Joseph
Dec 22, 2020
3 min read

The Enlighten Albedo API provides a flexible way to specify surface colors, either as an initial block of data or changed while the simulation is running.

Each surface has albedo, emissive and transparent material components.

Material components are provided per system to the Indirect Input Lighting stage via an Enlighten::AlbedoBuffer, Enlighten::EmissiveBuffer and Enlighten::TransparencyBuffer. These buffers can be initialised from a combination of static material data and dynamic material data. Once initialised, the dynamic materials can be quickly updated at runtime without having to completely recreate the buffer.

Material runtime

There are four main Enlighten objects required when dealing with Albedo, Emissive and Transparency.

  • class ClusterAlbedoWorkspaceMaterialData — This object is generated by the precompute and describes how the user-specified material IDs/GUIDs map onto the system.
  • AlbedoBuffer — This is a run-time object that caches the albedo colours for a system. It is set as an input on the IndirectInputLightingInternalParameters struct.
  • EmissiveBuffer — This is a run-time object that caches the emissive colours for a system which can be optionally set as an input on the IndirectInputLightingInternalParameters struct.
  • TransparencyBuffer — This is a run-time object that caches the transparency values for a system which can be optionally set as an input on the IndirectInputLightingInternalParameters struct.
  • class DynamicMaterialWorkspace — This is a run-time object that records the albedo and emissive colours and transparency values for the system materials. It also records which material components are static and which are dynamic.

See: ReadClusterAlbedoWorkspaceMaterialDataFromFile(), ReadClusterAlbedoWorkspaceMaterialData(), CalcAlbedoBufferSize(), CreateAlbedoBuffer(), CalcEmissiveBufferSize(), CreateEmissiveBuffer(), CalcTransparencyBufferSize(), CreateTransparencyBuffer(), CalcDynamicMaterialWorkspaceSize(), CreateDynamicMaterialWorkspace()

Initialisation

Once the DynamicMaterialWorkspace has been created, the contents need to be set up to describe the system's material configuration. By default, all materials in the workspace are initialised as static (not updateable) with a default albedo and emissive of black (0,0,0,0) and Transparency of opaque (0). See InitialiseMaterialAlbedoAsDynamic(), InitialiseMaterialEmissiveAsDynamic(), InitialiseMaterialTransparencyAsDynamic(), InitialiseMaterialAlbedoAsStatic(), InitialiseMaterialEmissiveAsStatic(), InitialiseMaterialTransparencyAsStatic(), SetMaterialAlbedoColour(), SetMaterialEmissiveColour(), SetMaterialTransparency().

When the DynamicMaterialWorkspace is set up for the materials in the system, the AlbedoBuffer, EmissiveBuffer and TransparencyBuffer must be initialised. The buffers are initialised from a combination of dynamic colour data (via the DynamicMaterialWorkspace) and static colour data, which can come from one of the following sources:

  1. Static material colours in the DynamicMaterialWorkspace — see InitialiseAlbedoBufferFromMaterialWorkspace(), InitialiseEmissiveBufferFromMaterialWorkspace(), InitialiseTransparencyBufferFromMaterialWorkspace()
  2. A texture — See InitialiseAlbedoBufferFromTexture(), InitialiseEmissiveBufferFromTexture()), InitialiseTransparencyBufferFromTexture()
  3. An array of colours-per-point data — See InitialiseAlbedoBufferFromColoursPerPoint(), InitialiseEmissiveBufferFromColoursPerPoint(), InitialiseTransparencyBufferFromColoursPerPoint()

In these last two methods, only the samples or pixels that fall on static materials will be used. For samples or pixels that fall on dynamic materials, the material colours in the DynamicMaterialWorkspace are used.

Dynamic albedo, emissive and transparency

Once the AlbedoBuffer, EmissiveBuffer and TransparencyBuffer have been initialised, the dynamic materials in the DynamicMaterialWorkspace can be updated relatively inexpensively at run-time. See SetMaterialAlbedoColour(), SetMaterialEmissiveColour(), SetMaterialTransparency(). When all material colours have been updated within the workspace, the AlbedoBuffer, EmissiveBuffer and TransparencyBuffer must be updated before any changes in the workspace will be reflected. See UpdateAlbedoBuffer(), UpdateEmissiveBuffer(),
UpdateTransparencyBuffer().
The dynamic-ness and static colours of material components in the DynamicMaterialWorkspace can also be updated at run-time, however the related AlbedoBuffer, EmissiveBuffer and TransparencyBuffer will need to be completely re-initialised again.
Internally, Enlighten tracks the status of the buffers so if a buffer update function is called but Enlighten detects that the buffer needs to be initialised, a warning will be printed. The integration can check that an initialisation is required via IsAlbedoBufferInitialiseRequired(), IsEmissiveBufferInitialiseRequired() and IsTransparencyBufferInitialiseRequired(). Furthermore, if an update function is called but Enlighten detects that no update is required, the update function will return straight away, making it very inexpensive to call.

For performance reasons, it is ideal to defer the call to UpdateAlbedoBuffer(), UpdateEmissiveBuffer() and UpdateTransparencyBuffer() until after all material values have been set in the DynamicMaterialWorkspace.

Serialisation

The AlbedoBuffer, EmissiveBuffer, TransparencyBuffer and DynamicMaterialWorkspace can be serialised with the following utility functions in EnlightenUtils.h:

WriteAlbedoBuffer(), ReadAlbedoBuffer(), WriteEmissiveBuffer(), ReadEmissiveBuffer(), WriteTransparencyBuffer(), ReadTransparencyBuffer(),
WriteDynamicMaterialWorkspace(), ReadDynamicMaterialWorkspace().