TerrainLightmapper v1.0
Oliver Marsh
Owen Marsh
marshin@marshinsoftware.com

-Installing TerrainLightmapper
-Known Bugs
-Running TerrainLightmapper
-Creating Environment Scripts


Installing TerrainLightmapper
_____________________________

1. Unzip the file to a directory of your choosing, where it will create a folder called TerrainLightmapper.


Known Bugs
__________

The output lightmap is flipped vertically with regards to the input heightmap.
Currently it must be fixed manually using an image editor.

Attempting to use a non 24bit bitmap as the input heightmap can lead to unexpected results, including
program crashes.


Running TerrainLightmapper
__________________________

1) Starting the program:
Navigate to the TerrainLightmapper folder and execute TerrainLightmapper.exe.

2) Loading a heightmap:
Click the 'Open heightmap file' buttton and select a 24bit bitmap heightmap file. (Example heightmaps are included in the TerrainLightmapper/Example Data folder.) The 3D representation of the heightmap will now be navigable in the application window. Use the arrow keys to zoom and rotate the terrain.

3) Loading an environment (light sources):
Click the 'Load environment script' button and select a .ohm file. (Example environment scripts are included in the TerrainLightmapper/Example Data/Environment Scripts folder.) The 3D representation of the heightmap will now have light sources applied to it.

4) Setting the blur level:
A guassian blur is applied to the output lightmap after generation in order to reduce the appearance of pixelation. The default level (5) should be appropriate in most cases. If you do not wish to apply any blur, select 0 as the blur level.

5) Generating a lightmap:
Click the 'Generate lightmap' button to create the lightmap. The progress meter will indicate the current progress, and when generation is complete a 3D representation of the lightmap will be navigable in the application window.
The output file is created in the same directory as the input heightmap, and will have the same name as the heightmap, except with _lightmap appended to it. For instance, if the input file was called heightmap.bmp, the output file will be called heightmap_lightmap.bmp.
If you wish to save a lightmap, it is import that you back it up somewhere as it will be overwritten the next time a lightmap is generated using the same heightmap.


Creating Environment Scripts
____________________________

The best way to create your own environment script is to work from one of the examples provided. Within the Environment() scope (which must be nested within the GetComponent(WORLD) scope) you can define the environment settings. The Clear command resets the environment to the default settings (no lighting). Without the Clear, any new environment settings will be added to the current settings.

All COLOR rgb values should be set with floats and are internally capped between 0.0 and 1.0.
0.0 corresponds to 0 and 1.0 corresponds to 255.

To set the ambient light value, create a new COLOR variable called ambient_light in the Environment() scope.

To create a light source, you must create an AddInfiniteLightSource() scope and within it set a COLOR variable called color, as well as call SetPosition.
The SetPosition call lets you set a theoretical origin for the infinite light source. This position is used to calculate the direction vector for the light. The actual source of the light is considered to be at an infinite distance away.
An environment can have as many infinite light sources as you want (but performance will degrade with more lights).

The fog settings are not used for the TerrainLightmapper. Keep fog_enabled = FALSE.