This is the documentation for Enlighten.

Providing albedo information

Owned by William Joseph
Sept 07, 2020
3 min read

This page shows an example usage of the Enlighten Albedo low level API to set material albedo and emissive colors using Material GUIDs.

Example code: 
// We need to work with 3 objects:
// Cluster albedo workspace - the current set of albedo colours for a system.
// Cluster albedo material data - describes the relation between instance, mesh and material-guids and albedo colours.
// Input workspace - describes the system we are applying albedo colours to.

// Load the cluster albedo material data from the output of the precompute.
// The second parameter specifies to also load the optional material GUIDs data block which is required for using instance, mesh and material GUIDs to identify uses of materials
Enlighten::ClusterAlbedoWorkspaceMaterialData* cawMaterialData = 
	Enlighten::ReadClusterAlbedoWorkspaceMaterialDataFromFile(myClusterMatFilename, Enlighten::Iff::ClusterAlbedoWorkspaceMaterialGuidsSection);

// Create a dynamic material workspace object
Geo::u32 dynamicMaterialWorkspaceSize = Enlighten::CalcDynamicMaterialWorkspaceSize(cawMaterialData);
void* dynamicMaterialWorkspaceMem = GEO_ALLIGNED_MALLOC(dynamicMaterialWorkspaceSize, 16); // 16-byte alignment is required.
DynamicMaterialWorkspace* dynamicMaterialWorkspace = Enlighten::CreateDynamicMaterialWorkspace(cawMaterialData, dynamicMaterialWorkspaceMem);

// We need to create a small "workspace" buffer which is used internally to help perform GUID lookups. The required size of this buffer is calculated
// by calling Enlighten::CalcMaterialGuidsLookupWorkspaceSize(cawMaterialData):
void* workspaceMemory = GEO_ALIGNED_MALLOC(Enlighten::CalcMaterialGuidsLookupWorkspaceSize(cawMaterialData), 8);

// Now we assign colours to materials and apply them in one go to the cluster albedo workspace.
// We apply the colours in bulk for efficiency reasons.

// We will set the colours the same way as done above in the GeoRadiosity demo
v128 solidBlack  = VConstruct(0.0f, 0.0f, 0.0f, 0.0f);
v128 solidBlue 	 = VConstruct(0.0f, 0.0f, 1.0f, 1.0f);
v128 solidYellow = VConstruct(1.0f, 1.0f, 0.0f, 1.0f);

// For all uses of material 0x000...0C2 set the albedo to blue and emissive to black (i.e. no emissive colour)
Enlighten::SetMaterialAlbedoColour(
	dynamicMaterialWorkspace, 
	cawMaterialData, 
	GeoGuid::Invalid, 
	GeoGuid::Invalid, 
	GeoGuid::Create(0x0000000000000000, 0x00000000000000C2), 
	solidBlue, 
	workspaceMemory);

Enlighten::SetMaterialEmissiveColour(
	dynamicMaterialWorkspace, 
	cawMaterialData, 
	GeoGuid::Invalid, 
	GeoGuid::Invalid,
	GeoGuid::Create(0x0000000000000000, 0x00000000000000C2), 
	solidBlack, 
	workspaceMemory);

// For the use of material 0x000...0C2 on the instance 0x000...A1 set the albedo to yellow and emissive to black (i.e. no emissive colour)
Enlighten::SetMaterialAlbedoColour(
	dynamicMaterialWorkspace, 
	cawMaterialData, 
	GeoGuid::Create(0x0000000000000000, 0x00000000000000A1), 
	GeoGuid::Invalid,
	GeoGuid::Create(0x0000000000000000, 0x00000000000000C2), 
	solidYellow, 
	workspaceMemory);

Enlighten::SetMaterialEmissiveColour(
	dynamicMaterialWorkspace, 
	cawMaterialData, 
	GeoGuid::Create(0x0000000000000000, 0x00000000000000A1), 
	GeoGuid::Invalid,
	GeoGuid::Create(0x0000000000000000, 0x00000000000000C2), 
	solidBlack, 
	workspaceMemory);

GEO_ALIGNED_FREE(workspaceMemory); //we have finished with the workspace memory

// Now allocate the albedo buffer.
// Because we handle the memory ourselves we first need to know the size to allocate (an InputWorkspace is required for this so load it).
Enlighten::InputWorkspace* inputWorkspace = Enlighten::ReadInputWorkspaceFromFile(myInputWorkspaceFilename);

Geo::u32 albedoBufferMemorySize = Enlighten::CalcAlbedoBufferSize(inputWorkspace);
void* albedoMemory = GEO_ALIGNED_MALLOC(albedoBufferMemorySize, 16); // 16-byte alignment is required.
Geo::u32 emissiveBufferMemorySize = Enlighten::CalcEmissiveBufferSize(inputWorkspace);
void* emissiveMemory = GEO_ALIGNED_MALLOC(emissiveBufferMemorySize, 16); // 16-byte alignment is required.

// Then we initialise the memory to be an AlbedoBuffer and EmissiveBuffer
Enlighten::AlbedoBuffer* albedoBuffer = Enlighten::CreateAlbedoBuffer(albedoMemory, inputWorkspace);
Enlighten::EmissiveBuffer* emissiveBuffer = Enlighten::CreateEmissiveBuffer(emissiveMemory, inputWorkspace);

// Now initialise albedo and emissive buffer for the first time.
InitialiseAlbedoBufferFromMaterialWorkspace(dynamicMaterialWorkspace, cawMaterialData, albedoBuffer);
InitialiseEmissiveBufferFromMaterialWorkspace(dynamicMaterialWorkspace, cawMaterialData, emissiveBuffer);

The resulting AlbedoBuffer and EmissiveBuffer objects from this example can be fed to the IndirectInputLighting function to provide the albedo and emissive colours.

Dynamic albedo update

It is possible to update the albedo, emissive and transparency dynamically at runtime by simply changing the material colours and applying them in bulk using the appropriate Set* and Update* functions. To set new colours, you will need to keep the DyanmicMaterialWorkspace data object around. This typically has a very small memory footprint unless you have a very large number of materials, but you can delete this object if it is no longer required. If you loaded the material data object using a Read function from the Utilities API, you should delete it with the corresponding Delete* call to ensure the memory allocation/free operations use the same memory system.

Dynamic material components should be initialised as dynamic before the call to Initialise*. Once initialised, dynamic material components can be updated with a call to the Set* functions. The updated material colours will only appear in the AlbedoBuffer, EmissiveBuffer or TransparencyBuffer once the relative Update/* function is called on the buffer. Numerous Set calls can be batched before calling the Update function.