Albedo handling

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()

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.

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().