Use the instance element to specify an instance object in the .scene file.

Radiosity instances

Add an instance element for each engine mesh to be included in the radiosity computation, with a name attribute that is unique within the scene.

Make sure the geometry attribute of each instance element refers to a geometry object.

Use the position and rotation attributes to set the world transform of the instance.

Set the type attribute:

Radiosity: lit using a lightmap.
Probe Radiosity: lit using probes.

Set the zone attribute to group instances into as few groups as possible. For a small world, use a single zone for all instances in the scene. If your world is split into chunks for streaming, use the zone attribute to group instances into a single zone for each chunk.

When lit using a lightmap, each instance can have a maximum pixel count of 512x512=262,144 pixels. If your world contains a single instance which requires this number of pixels, the precompute reports an error. You can avoid this by ensuring that such very large instances are split into smaller chunks.

Instance GUIDs

Set the instanceGuid attribute so that you can easily identify the original engine mesh for which you added a radiosity instance. The attribute value is a 128-bit hex string.

A single zone cannot contain two instances with the same instanceGuid.

If your engine already generates a unique 128-bit value for each engine mesh, we recommend to use this value.

If your engine uses strings to identify an engine mesh, we recommend to use a 128-bit hash of the string, computed with a good hash function.

A 128-bit hash computed with a good hash function has an extremely low (but non-zero) probability of generating a collision.

When the instanceGuid changes, you must re-run the precompute. If you want to avoid a precompute after an engine mesh is renamed, maintain a persistent Enlighten GUID for each engine mesh. Generate this Enlighten GUID in your editing tools and save it with your source assets.

We strongly recommend that instance identifiers do not change between precomputes. We recommend not to generate a new random GUID each time you run the precompute.

Excluded instances

If a mesh is not included in the radiosity computation, you do not need to add it to the scene. However, you may find it useful to add such instances so they are shown when the scene is loaded in GeoRadiosity.

To add such a mesh, add an instance element with a unique name, set the type attribute to Fully Dynamic and add only the geometry object and world transform attributes.

Unlit instances

To prevent certain types of light leak, the artist might place invisible geometry to block unwanted sky or sun light from a particular area of the world. To eliminate unnecessary Enlighten lighting data for such a mesh, add an Instance element with a unique name and set the type attribute to Unlit. Set the zone attribute to group unlit instances in the same way as radiosity instances. By default, unlit instances block light but do not reflect light, as if their surface was perfectly black.

To eliminate unnecessary Enlighten lighting data in an area outside the world that does not need Enlighten indirect lighting, the artist should place invisible geometry with a special invalid material. For such a mesh, add an unlit instance and set the backfaceBehaviourType material attribute to doubleinvalid.

Radiosity parameters

To control the indirect lighting resolution of a radiosity instance, set the paramSet attribute to the name of a parameterSet element of the radiosity parameters.

All instances in the same zone must have the same paramSet.

Example scene

The scene file below contains a single instance.

Cornellbox/Cornellbox.scene

<?xml version="1.0" encoding="utf-8"?>
<scene name="Cornellbox" version="1">
	<instance name="Cornellbox" instanceGuid="0000000000000000" systemId="Cornellbox" paramSet="Interior"
		geometry="Cornellbox" type="Radiosity" position="0 0 0" rotation="0 0 0 1" />
</scene>

Instance scale

For instances that are lit using a lightmap, unwanted behaviour may occur when a scale factor is applied to the instance:

a negative scale factor causes lightmap pixels to become smaller than the desired indirect lighting resolution.
a non-integer scale factor results in lightmap pixels that may not match the desired indirect lighting resolution.
a non-uniform scale produces non-square lightmap pixels which can cause lighting artifacts.
a large positive scale factor causes wasted space in the lightmap.

To avoid this behaviour, when a instance with a lightmap has a scale factor, we recommend to bake this scale factor into the geometry object. If your scene contains more than one instance of the same geometry object with different scale factors, create a new geometry object for each unique scale factor.

It's generally safe to apply a uniform scale factor between 1 and 4. To apply such a scale factor to the instance, replace the position and rotation with the transform attribute.

For instances that are lit using a lightmap, we recommend not to use a non-uniform or negative scale in the transform attribute.

Materials

To override a mesh object material attribute for a given instance, add a materialOverrides child element to the instance with the corresponding meshName attribute. The materialOverrides element contains material elements defined in the same way as for the mesh object.

The example below shows an instance Flagpole1 which overrides the properties of the material of the mesh Flag with ID 0:

<instance name="Flagpole1" instanceGuid="0000000000000000" systemId="System1" paramSet="High" geometry="Flagpole" type="Radiosity" position="0 0 0" rotation="0 0 0 1" />
	<materialOverrides meshName="Flag" >
		<material id="0" backfaceBehaviourType="doubleSided"/>
	</materialOverrides>
</instance>

When you specify a material attribute in both the mesh and the instance, the attribute in the instance overrides the attribute in the mesh.

For each attribute, the Enlighten takes the value from:

the instance material attribute, if specified, otherwise..
the mesh material attribute, if specified, otherwise..
the default