This is the documentation for Enlighten.

.scene format


The XML schema for the .scene file format is available in Src/Samples/Libraries/GeoEn2Support/scene.xsd.

<scene>

The root <scene> element has the following attributes. The <scene> element may contain any number of <instance>, <probeSet>, <volume>, <autoProbeVolume>, <probeOctree> and <cubeMap> elements.

Attribute

Usage

Description

Values

name

Required

The name of this scene.

String

paramSetFile

Optional

The parameter file

File path (default ..\Default.paramset)

axes

Optional

Allows specifying the world coordinate system to be used when loading the scene in GeoRadiosity or GeoViewer. Specify for example +x+z-y for the commonly used right-handed y-up permutation.

String (default +x+y+z)

version

Required

The version of the scene format.

Integer


<instance>

Any number of <instance> elements may appear within your <scene>.

Attribute

Usage

Description

Values

name

Required

The name of this instance. Must be unique within the system.

String

zone

Optional

The name of the zone which contains this instance. If your world is split into chunks for streaming, use the zone attribute to group instances into a single zone for each chunk.

Positive integer

instanceId

Optional

The ID of this instance. Must be unique within the system. If you specify this for one instance in the scene, then you must specify it for all instances. If omitted this will be automatically generated.

Positive integer

systemId

Optional

The scene-wide unique name of the system. Use this to explicitly group radiosity instances into a radiosity system.

String

paramSet

Optional

The name of the parameter set used for this instance. If this does not exist in the paramset file, a new paramset (using defaults) will be created. May be skipped for Fully Dynamic or Static Set Dressing objects.

String

systemGuid

Optional

Overrides the internal system GUID generated from the system ID and paramset ID. Must be unique within the entire scene.

128-bit hex string

instanceGuid

Optional

Specifies the GUID for this instance. This must be unique within the whole scene. If omitted, this is automatically generated from the system and instance names.

128-bit hex string

guid

Deprecated

Deprecated: see systemGuid.


geometry

Required

The name of the .geom file that contains the mesh information.

String

type

Required

The lighting type for this instance: 
'Radiosity' is immovable geometry that is lit with a lightmap. 
'Fully Dynamic' instances do not bounce light and are lit by SH probes at runtime and can be moved - it is optional to include these as they do not participate in the precompute. 
'Probe Radiosity' instances are lit by SH probes at runtime but still bounce light so they cannot move.

Radiosity 
Fully Dynamic 
Probe Radiosity 
Static Set Dressing

useVolumeTexture

Optional

For dynamic objects, whether to create and use a volume texture.

Boolean (default true)

lmName

Optional

If being used in a Baking lightmap, the name of the map. Must be specified on the instance, or on each mesh, or both.

String

lmType

Optional

If being used in a Baking lightmap, the type of the map. Must be specified on either the instance or each mesh, not both.

String

lmAtlas

Optional

If being used in a Baking lightmap that will be packed, whether to atlas the UVs.

Boolean

position

Optional

The location of the instance in world coordinates.

3-element vector

rotation

Optional

A quaternion representing the rotation of the instance.

4-element vector

transform

Optional

A full matrix specifying translation, rotation and scaling. Should be avoided in favour of the simpler position/rotation attributes, but is required to allow scene extract of arbitrary scenes.

4x4 matrix

includeInAutoSystemGeneration

Optional

If set to false, this instance will not take part in automatic system generation.

Boolean (default true)

scaleUvsWithInstanceSize

Optional

Specifies whether the scaling of the transform of this instance should be taken into account when generating the per-instance lightmap UVs (that is, whether the output pixel size specified for this instance should be in world units (true) or in local geometry units (false).

Boolean (default true)

additionalUvScale

Optional

 Specifies an additional scale that should be applied to the lightmap UVs for this instance (to change the output pixel size). This is applied in addition to any scaling related to the scaleUvsWithInstanceSize flag.

Positive decimal (default 1.0)

clusterSize 

Optional

The size of the clusters to generate for this instance, in world space units. If not specified, uses the system cluster size. 

Positive decimal  


Material Overrides

Any number of <materialOverrides> or <pbrMaterialOverrides> elements may appear within your <instance> elements. They contain a list of per-instance material overrides for a mesh. Note that these overrides are done on a per-property basis, i.e. the final value of any single material property will come from the <materialOverrides>/<pbrMaterialOverrides> if present and the .mats file if not. If no value is specified in either the <materialOverrides>/<pbrMaterialOverrides> or the .mats then the default value will be used. This means that the value of each material property can come from a different source.

Attribute

Usage

Description

Values

meshName

Required

The name of the mesh (as specified in the .geom file) for which these material overrides apply.

String

version

Optional

The version of the material overrides.

Positive integer

Your <materialOverrides>/<pbrMaterialOverrides> element may contain any number of <material>/<pbrMaterial> elements respectively as specified in the .mats format.

<probeOctree>

Any number of <probeOctree> elements may appear within your <scene>.

Attribute

Usage

Description

Values

name

Required

A unique name for this volume.

String

<probeSet>

Any number of <probeSet> elements may appear within your <scene>.

Attribute

Usage

Description

Values

name

Required

Unique name of this probeset.

String

lmType

Optional

If being used in a baking lightmap, the type of the map. If not specified, uses the system paramset.

String

<volume>

Any number of <volume> elements may appear within your <scene>.

Attribute

Usage

Description

Values

name

Required

A unique name for this volume.

String

guid

Optional

Overrides the GUID generated from the name. Must be unique within the entire scene.

128-bit hex string

quality

Optional

Deprecated: The quality of the SH calculation. Use values 0, 1 or 2.

Integer (default 1)

probesParamSet

Optional

The probesParameterSet to use for this volume. If not specified, use the default parameters.

String

isUnstructuredSet

Optional

Internal.

Boolean (default false)

unstructuredSetNumProbes

Optional

Internal.

Unsigned integer

unstructuredSetRandomSeed

Optional

Internal. Seed used for generating random positions of unstructured probe set.

Unsigned integer (default 0)

lmType

Optional

If being used in a baking lightmap, the type of the map. If not specified, uses the system paramset.

String

The <volume> element must contain the following sub-elements, with the attributes described:

  • <resolution> — the number of samples within the volume, as attributes x, y and z. You can usually keep z at 1, if z is up.
  • <size> — the length of each side of the volume, in world space, as a 3-element vector (attributes x, y and z).
  • <position> — the world coordinates of the origin of the volume (that is, the corner), as a 3-element vector (attributes x, y and z)
  • <basis> — the basis vectors specifying the orientation of the volume. These must be orthogonal. 
    The <basis> element must contain three sub-elements holding 3-element vectors: <U>, <V> and N, each with attributes x, y and z. See the example below.
<autoProbeVolume>

Deprecated.

Any number of <autoProbeVolume> elements may appear within your <scene>.

Attribute

Usage

Description

Values

name

Required

A unique name for this volume.

String

probesParamSet

Optional

The probesParameterSet to use for generated volumes. If not specifed, use the default parameters.

String

minProbeSetSize

Required

The minimum size of a probe set, affects the octree voxels size to use for this volume.

Integer

mergingThreshold

Required

The threshold for merging new voxels and empty space.

Float

minProbeSpacing

Required

The minimum probe spacing for a probe volume.

Integer

maxProbeSpacing

Required

The maximum probe spacing for a probe volume.

Integer

The <autoProbeVolume> element must contain the following sub-elements, with the attributes described:

  • <size> — the length of each side of the volume, in world space, as a 3-element vector (attributes x, y and z).
  • <position> — the world coordinates of the origin of the volume (that is, the corner), as a 3-element vector (attributes x, y and z)
  • <basis> — the basis vectors specifying the orientation of the volume. These must be orthogonal. 
    The <basis> element must contain three sub-elements holding 3-element vectors: <U>, <V> and N, each with attributes x, y and z. See the example below.
<cubeMap>

Any number of <cubeMap> elements may appear within your <scene>.

Attribute

Description

name

Required: A unique name for this cube map.

cubeMapParamSet

Optional: The cube map parameter set to use for this volume. If not specifed, use the default parameters.

There are also several child elements, all of which are required:

Element

Description

faceWidth

The width of a cube map face. All faces are square and must have power of 2 widths

position

The cube map centre in world space

boxOrigin

The world space centre of the oriented box that approximates the depth of the scene of the cube map

boxSize

The length of each side of the box, in world space

boxBasis

The basis vectors specifying the orientation of the box, consisting of 3 child elements U, V and N (see example). These must be orthogonal.