Crystal Space 2.0.0: 5.6.1 lighter2 User's Manual

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 5.6.1 `lighter2` User's Manual

## Introduction

`lighter2` is a tool to compute static lighting for a CrystalSpace world.

Static means that the lighting effects on objects in the world are precomputed in a preprocessing step during and after modelling of the world. The benefit is that it is very cheap to render; it makes no difference if a world uses one or one thousand lights, the runtime performance is the same. Shadows are supported as well. However, as the name “static” implies, the lighting can't be changed at runtime - that is, moving a light source won't have an effect on statically lit geometry.

The opposite is dynamic lighting which is computed entirely at runtime. This means that light sources can be moved as desired, with changes immediately being reflected; however, shadows and multiple light sources all increase the runtime cost of lighting.

In practice, static and dynamic light can be mixed: lights sources that don't change their position (e.g. a streetlight) can be computed statically, while moving light sources (e.g. a flashlight held by the player) are computed dynamically.

## Basic Usage

`lighter2` is usually invoked from the command line:

    lighter2 [options] <map file>

`options` optionally specify one or more command-line options (which are described in the course of this section). `map file` specifies the path to a directory or ZIP file containing an XML map file named `‘world’` or the direct file name of an XML map file. Note: it is recommended to extract worlds in ZIP files before lighting as this will result in noticeably faster disk input/output, especially when the results are saved.

Once started, lighting will be computed for the world without further user intervention being necessary.

## Light computation

Lighting for objects is either computed as a lightmap or per-vertex.

Lightmap lighting can be thought of as a grid being laid over surfaces in the world and the lighting for a surface being computed at the grid points.

The distribution of lighting grid points for a surface is controlled by the lightmap density. This density specifies the amount of sample points in u- respectively v-direction of the surface, measured in points per world unit. E.g. a density of 2 means 2 by 2 sample points for a square of 1 by 1 world units of a surface. If a world unit equals one meter, this would mean a lighting value is computed every 0.5m.

Increasing the lightmap density means shadows get more detailed, but lightmaps also get bigger (and more lightmaps may be produced). Decreasing the lightmap density reduces lightmap sizes and amounts, but also means less detailed and blurrier shadows. However, it may make sense for cases where shadows are not very detailed anyway (such as large outdoor surfaces).

The default lightmap density is 2x2, which can usually be considered “low” quality. A density of 8x8 can be considered “medium” quality and 16x16 as “high” quality and sufficient in most cases.

Per-Vertex lighting means that lighting for surfaces is computed at its vertices.

### When to Use Per-vertex Lighting

For objects that consist of relatively large and few surfaces lightmap lighting is great: light is sampled at a lot of points distributed over the surfaces, giving good light and shadow details. Using per-vertex lighting for such kind of objects would mean that lighting is only sampled at the surface corner and interpolated over the surface, meaning much detail is lost.

However, on highly tesselated objects (ie lots of small surfaces) lightmap lighting usually produces sub-par results. Due to the way the lightmapper works it can happen that a lot of seams are visible (especially when surfaces are smaller than the spacing of the lightmap grid). But if an object is highly tesselated it usually means that there are so many vertices so close together that sampling lighting at these can already give sufficient light and shadow detail, giving results as good as lightmaps, even though lighting for individual surfaces is only interpolated over them.

Below is a comparison between different lightmap densities and per-vertex lighting on a relatively highly tesselated, round object:

At the lowest used density (4x4), the object appears rather un-smooth with a number of visible edges and shadow issues. At the next density – 16x16, a 16-fold increase from the lowest lightmap resolution – the appearance is smoother, but still some visible artifacts remain. With the highest density – 64x64 – the object looks acceptable, but the price being a ridiculously high lightmap density which is directly reflected in a hight number of lightmaps needed, high runtime memory usage and, ultimatively, lower runtime performance. In comparison, the vertex-lit variant has a bit less detailed shadows, but looks more smooth overall with zero visible edges. Per-vertex lighting also has only low memory requirements.

Per-vertex lighting can also be beneficial on objects quite the opposite: when surfaces are extremely large, lightmaps will also be. If a large object is lit in such a way that very few shadows are cast on it, meaning that the lighting is very smooth on the surfaces and varies only little, there is no benefit from using lightmaps, as the shadowing detail they can possible provide is not present. Using per-vertex lighting on such an object can save resources by omitting the lightmaps with little visual difference.

## Setting Global Options

Some options are “global” and affect all meshes or factories or the execution of `lighter2` itself. These options can be set in two ways: the command line and a configuration file.

For example, the global option `‘foo’` can be set to the value `‘bar’` in any of the following ways:

- On the command line by specifying `-foo=bar`.
- In a configuration file by setting the key `‘Lighter2.foo=bar’`. The configuration file can be utilized via CrystalSpace's `-cfgfile` command line option.
- In `‘lighter2.cfg’` by setting the key `‘Lighter2.foo=bar’`.

Note that this is list is ordered by precedence – e.g. a command line option will always override an option set in a configuration file, and a user-specified configuration file will always override options from `‘lighter2.cfg’`.

## List of Options

### Lightmap Density

Please see the “Light computation” section above for an explanation of lightmap density.

- Can be set on mesh factories.
- Can be set globally: `lmdensity`

### Per-Vertex Lighting

Per-vertex lighting means that lighting is not computed on a grid laid over the surfaces but at the vertices of a mesh.

For a discussion of cases where using per-vertex lighting can be beneficial read the paragraph “When to Use Per-vertex Lighting”.

- Can be set on mesh factories.
- Can be set on mesh objects. Note that if per-vertex lighting has been enabled for a factory it can't be disabled for objects of that factory.

### Disable self shadows

Disables casting of shadows from an object onto itself.

- Can be set on mesh factories.
- Can be set on mesh objects.

### Advanced Options

#### Black Threshold

This controls the threshold of a lightmap pixel below which it is considered black. Can be used to "cull" away lightmaps that have only very, very low lighting values. However, while setting this value high may cause less lightmaps to be produced, it may also cause visible lighting artifacts (as low lightmap values are actually amplified at runtime).

- Can be set globally: `blackthreshold`.

#### Normals Tolerance

When computing the lightmap layout (that is, determining the area of the lightmap onto which a surface is mapped), coplanar surfaces are layouted adjacent to each other. However, in practice, due to inaccuracies etc. some surfaces may not be exactly coplanar, but close enough to be practically considered as such. The normals tolerance specifies the maximum angle between two surface normals (in degrees) at which the surfaces are still considered coplanar.

- Can be set globally: `normalstolerance`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated using texi2html 1.76.