This is the documentation for Enlighten.

Mesh objects

Owned by Nathan Hunter (Unlicensed)
Oct 31, 2024
3 min read

To construct a mesh object, create an object of type IPrecompInputMesh. Use the member functions to add vertices and faces.

To prevent unexpected behaviour, always initialize unused optional fields to zero.

Vertices

Enlighten expects the vertex positions of meshes in your world to be specified relative to the mesh origin. You do not need to transform these vertex positions to world space.

Each PrecompInputVertex has four attributes:

  • Position: Local position.
  • Normal: Vertex normal.
  • Chart UV: Input UV coordinates used when forming charts.
  • Optional: Albedo UV: Material UV coordinates used when rendering the mesh.

To simplify your code, use the same position values for each vertex as in the rendered mesh. To eliminate the need to re-order vertices later in the pipeline, add one vertex for each of the vertices of the rendered mesh, in the same order.

Faces

Each PrecompInputFace contains three indices into the vertex array, along with a material ID.

Enlighten uses the vertex normals to automatically determine the front facing direction of each triangle. To ensure that front and back faces are treated correctly, provide indices in the expected winding order. If your world uses a right handed coordinate system, use counter-clockwise winding order, otherwise use clockwise winding order. To change the winding order, swap any two indices within the triangle.

The m_AlbedoId field of PrecompInputFace is optional and can be zero for all triangles.

Mesh files

Save the object to disk using the Geo::SaveInterface function. Use a filename with the .pim extension.

If you use mesh LOD, save the mesh data for each detail level in a separate .pim file.

Materials

You can control certain radiosity properties of a mesh using a material. By default, all meshes are treated as opaque, with invalid back faces.

To get started quickly, you can omit the material information from the scene description.

To provide material information, create a .mats file and add a material element with id zero.

Single material
<?xml version="1.0" encoding="utf-8"?>
<materials version="1">
	<material id="0"/>
</materials>

When all faces in the mesh have the same properties, use zero for both m_AlbedoId and the material id attribute as shown in the example above.

When a mesh is composed of more than one part that can each be assigned different properties, group faces into as few groups as possible and assign each group an index in the sequence (0, 1, 2, ...)

Set the m_AlbedoId field of each PrecompInputFace to the index of its group. Add a material element for each group and set the id attribute to the group index.

Save the file in the same folder as the mesh object, using the same name but with the .mats extension.

Material attributes

You can optionally specify attributes for each material that affect the way a surface interacts with radiosity:

The backfaceBehaviourType attribute controls how the back of the surface is treated:

  • invalid — Lighting is invalidated for other surfaces that see the back of this surface. This is the default.
  • black — The back of this surface absorbs all incoming light, as if it were colored black.
  • doublesided — Both back and front faces of this surface transmit half the incoming light and reflect the rest.
  • transparent — All incoming light passes through the back of this surface.
  • doubleinvalid — Lighting is invalidated for other surfaces that see either the front or back of this surface.

The shadowfaceBehaviourType attribute controls how the surface interacts with direct shadows.

  • front — Front faces cast direct shadows.
  • back — Back faces cast direct shadows.
  • both — Both front and back faces cast direct shadows.

 The shadow-face behaviour type affects precomputed shadows for directional light sources like the sun.

Indirect transparency/reflectivity: the fraction of indirect light that passes through, and the fraction that is reflected by the material. For physically plausible results, ensure that both values are within the range [0, 1] and sum to one.

Is Emissive: where possible, set this to true for materials that will emit light at runtime. This can boost the accuracy of both bounce lighting and local reflections, particularly for small emissive surfaces. This also prevents unwanted smoothing of local reflection probes at the boundary of an emissive surface.

The remaining elements of the material element defined in the .mats format control how a mesh will be rendered when the scene is loaded in GeoRadiosity or GeoViewer.

A typical implementation of Enlighten does not need to add these elements.