Terrain point light system

From SIMboxWiki
Jump to navigation Jump to search

This document describes how to use the terrain point light system (also known as the airport light system). The document describes how to operate the system from the point of view of the end user, in this case, the developer.

Note this feature pertains to SimiGon Graphic Engine Version 5 (SGEV5) only.

Light Table

The light table is a file containing definitions for different light points. Each light point may be defined with different properties such as color, intensity and direction.

Roles

The light table file has 2 roles:

• 3ds Max light table

• Simulation light table

3ds Max Light Table

The first role is to provide a list of light‐point property definitions for the 3ds Max light‐export plug‐in. The plug‐in uses the file to fill the "light type" list and in order to export and fill the OpenFlight file format appropriately.

When an OpenFlight file is exported the file contains all the attributes defined by the light‐table file, except for the following 2 attributes: "Max Intensity Range" and "Min Intensity Range". The reason these 2 attributes are not included is because the OpenFlight format currently does not support them.

In order for the light‐point exporter plug‐in to receive the light table file, the light table file must be placed in the 3ds Max plug‐ins directory alongside the actual plug‐in.

Simulation Light Table

The second role of the light table occurs in the simulation. When running the simulation, the light table file provides the missing "Max Intensity Range" and "Min Intensity Range" attributes. The file also provides a way to override any attribute values of the light points as exported by the 3ds Max plug‐in.

If the light table file is not made available to the simulation, all the light points will work as defined by the light table (that is supplied with the 3ds Max). Then the "Max Intensity Range" will be set to 0 and the "Min Intensity range" will be set to value of the "Visibility Range".

In order for the simulation to receive the light table file, the light table file must be placed in the same directory as the terrain with which it is associated.

Format

This section specifies the format of the light table that defines the types of lights that may participate in the light point model. A light table is a text file containing light table entries.

Each entry has the following format:

LTBL [Num] [Red] [Green] [Blue] [Max Intensity Range] [Min Intensity Range] [Visible Range] [Max Strength] MNSR=[Min Pixel Size] MXSR=[Max Pixel Size] DIAM=[Physical Size] LTMD=[Fog Effect] TMON=[Phase Time On] TMOF=[Phase Time Off] IDEL=[Phase Delay] DRCT=[Directionality] LOBH=[Horizontal Lobe] LOBV=[Vertical Lobe] BCLR=[Back Color Red] BCLG=[Back Color Green] BCLB=[Back Color Blue] BINT=[Back Intensity] NAME="[Name]" DESC="[Description]"

[Num] ‐ A unique integer number representing the id of the group.

[Red] [Green] [Blue] ‐ The color of the light. Range 0 to 255.

[Max Intensity Range] ‐ The distance at which the light as at its highest intensity. Value in meters.

[Min Intensity Range] ‐ The distance at which the light as at its lowest intensity. Value in meters.

[Visible Range] ‐ The maximum distance the light can appear from. Value in meters.

[Max Strength] ‐ How strong the light is when at min strength range. Range 0 to 100.

[Min Pixel Size] ‐ Minimum size of the light point. Value in pixels.

[Max Pixel Size] ‐ Maximum size of the light point. Value in pixels.

[Physical Size] ‐ Virtual Physical size of the light point. Value in meters.

[Fog Effect] ‐ is given in the values of 0 to 15 where 0 is full fog affect 1 is none.

[Phase Time On] ‐ (For flashing lights) ‐ The time period for which the light is on. Value in 1/60 of a second.

[Phase Time Off] ‐ (For flashing lights) ‐ The time period for which the light is off. Value in 1/60 of a second.

[Phase Delay] ‐ (For flashing lights) ‐ The amount of time the light flashing should be delayed by. Value in 1/60 of a second.

[Directionality] ‐ Specify for directional light type: (default 0)

o 0 – Omni‐directional Light (default).
o 1 – Unidirectional Light.
o 2 – Bidirectional Light.

[Horizontal Lobe] ‐ The horizontal lobe angle for which the light is visible. Relevant for unidirectional lights only. Value in Degrees 0 to 180.

[Vertical Lobe] ‐ The vertical lobe angle for which the light is visible. Relevant for unidirectional lights only. Value in Degrees 0 to 180.

[Back Color R/G/B] ‐ Light color of the back light. Relevant for bidirectional lights only. Range 0 to 255.

[Back Intensity] ‐ The intensity of the back color. Relevant for bidirectional lights only. Range 0 to 100.

[Name] ‐ Short name for the light. Description can be surrounded by '"' to ensure that space values are included.

[Description] ‐ Long description for the light. Description can be surrounded by '"' to ensure that space values are included.

Example

This section shows an example of the light table format based on the format specified in the previous section.

LTBL 2 255 0 0 10 1000 2000 50 MNSR=1 MXSR=5 DIAM=3 LTMD=15 TMON=30 TMOF=60 IDEL=10

Attributes:

Color number 2
Bright red
Starts dimming after 10 meters
Stops dimming at 1000 meters
Stops being visible after 2000 meters.
At its brightest it has a 0.5 alpha value.
Its min pixel size is 1
Its max pixel size is 5
Has a physical size of 3 meters
In animation light is visible for half a second
In animation after the light is on it turns off to a period of 1 second
In animation the light is delayed by 1/6 of a second (compared to other lights).

Point Lights in OpenFlight

Note: The following information contains technical specifications for the OpenFlight format. You only need this information if you intend to create an OpenFlight file with point lights without the use of the 3ds Max exporter plug‐in (discussed in the next section).

Point lights come as a standard feature in the OpenFlight format. The graphic engine can read this format and display the point lights as instructed. However, the OpenFlight format only allows for a static representation of the terrain. Several tags need to be added to the format to allow for manipulation of point lights during runtime.

Grouping

Tags can be added to the OpenFlight format in order to group several point lights together. Grouping point lights allows control over the grouped point lights in run‐time. For instance, the graphic engine's API allows turning on and off point lights which have been grouped together.

To group several lights together, add an OpenFlight "group" tag followed by a "long id" tag containing the name of the group.

Hierarchical Grouping

Groups of point lights can be grouped together inside other.

To group several groups inside another group:

Add an OpenFlight "group" tag, followed by a "long id" tag containing the name of the container group, followed by a "push" tag, followed by the rest of the information of the contained groups. Close the group using a "pop" tag.

Light Table Reference

The OpenFlight format can be used to link between a specific point light and a point light in the Light Table. Changing the properties of lights in the Light Table will allow you to control the properties of the point Lights in the terrain without needing to constantly rebuild the OpenFlight terrain.

To link a point light to a point light type in the Light Table, add a "comment" tag to the OpenFlight format just before the "PointLight" tag with the following string

"#LM_ATTRIBUTES LIGHT_INDEX [number of light type]"

The Light Table that the open flight references should be placed in the directory of the terrain under the name "LightTable.txt".

Using 3d Max to OpenFlight Point Light Exporter

Note: The following section refers to the OpenFlight Point Light exporter plug‐in for 3ds Max. You can create point lights without using this tool using the standard OpenFlight format.

SimiGon has developed a tool for exporting point lights models from 3ds Max to facilitate the creation of large complex point light systems. The following section explains the tool.

Model Creation

PlugIn Installation

To create a point model using the plug‐in, install the "Open Flight Light Exporter" max plug‐in in the max "Plug‐ins" directory. Also add your Light Table file to the same directory. The Light Table file should have the name "LightTable.txt".

Creating Light Points

After installing the plug‐in specified above, you will notice that a new helper object has been added to the 3ds Max API under the "Standard" category called "Flt Light". This new object represents the single light point.

There are 3 things to note when creating a light point:

• Type – Select the appropriate type of light for your light point. The type of light point you select will control the size, color, direction and visibility properties of the light.

• Position – Place the light point just above the terrain. Light points that are level with the terrain might be slightly hidden.

• Direction – Some lights are defined as directional lights. This means that their light is directed along a specific vector. In max that vector is represented by the local z vector of the object.

Grouping Light Points

You can use the grouping mechanism of max to group lights points together. These groups will be recorded in the exported file, and later allow manipulation of the light system in runtime.

Using grouping will allow the user to control the properties of the lights contained in a group in real time. It will then be easy for the user to turn a group of lights on and off, or to change the color of the lights in the group.

Note that even though the groups are maintained in a hierarchical structure, a group's attribute is controlled through its name only and not though its position in the hierarchy. For example, say you have 2 groups of lights named "Group 1" and "Group 2", and both of those groups contain a third group named "Group 3". The user will be able to manipulate the properties of the lights inside "Group 3" which will control the light point both inside "Group 1" and "Group 2".

Exporting the Model

To export the model use the use the Light exporter found under File‐>Export‐> Light Exported (*.FLT).

Integrating the Model into a Terrain

In order to add the model to the terrain we will use Terra Vista software. The action is the same as adding simple model to the terrain:

1. Import the model to “model library” in “libraries” tab (in the project tree).

2. In order to place the lights on the terrain we will use vector that will attach the model to the terrain where the vector is. We can either import a vector that is already exist or create a new vector:

a. Import an existent vector – Import it to Project tree>Source tab>Culture Data.
b. Create new vector‐ Go to Tools tree> vector editor> layers tab: Right click and “create empty layer”. Once the layer is added, stab a point on the terrain where you want the model to be placed (using the icon on the tool‐ bar). After the point is added, mark the point and set an attribute that will be equal to the model. (Usually we use “code= XXX).

3. Set the settings you want to the lights in Culture Parameters>Default> Feature Models> Points> lights feature model. You can set the range limit, the footprint code and etc.

4. Build the terrain.

Manipulation of the Point Lights Run-time

The Light point system allows you to manipulate the lights in real time.

Manipulation Logic

As mentioned before, when building a light system model, light points can be arranged together using groups. The Point Light manipulation API is based on manipulating the properties and on/off state of the groups the light points are arranged in.

Concerning setting a group of lights on and off, a light point will only be displayed if all of its ancestor groups on/off state are set to on. Obtaining and setting the value of the on/off state is done using the API functions: GetLightGroupOnState() and SetLightGroupOnState().

Concerning Light Point group properties, Light point groups have the same array of properties as light points. The final value of each property used to display a given light point is the multiplication of the original light point property value with the value of the same property in the groups the light point is contained in. For example, a light point (A) is contained in group (B). Light point (A) has its visible range property set to 1000 meters. Group B has its visible range coefficient set to 2. The final visible range of the light point will be 2000 = 1000 x 2 meters. Obtaining and setting the value of group properties is done using the API functions: GetLightGroupAttrib () and SetLightGroupAttrib ().

Point Light System API

The function calls involved in the Point Light System API are:

TriD::PointLight::EnumLoadedLightGroups()
TriD::PointLight::SetLightGroupOnState()
TriD::PointLight::GetLightGroupOnState()
TriD::PointLight::SetLightGroupAttrib()
TriD::PointLight::GetLightGroupAttrib()

EnumLoadedLightGroups()

This function returns the current loaded light groups as defined in the terrain (as defined in the 3ds Max program). Note that the function only returns the loaded (shown) light groups and not all the light groups in the entire terrain.

The function uses a callback function which returns for each group its name and its position (depth) in the tree.

Parameters:

lpCallback – A pointer to the callback function through which the groups would be returned.

Return value:

zsOK if succeeded zsERR_BadParam if failed.

SetLightGroupOnState()

Sets a given group of point lights on or off (visible or hidden)

Parameters:

sGroupName – The name of the group for which to set the on off state. NULL to set the value of the default state (for all lights).
bIsOn – Specify True to state the group to an on state. False for as off state.

Return Value:

zsOK if succeeded. zsERR_BadParam if failed.

GetLightGroupOnState()

Returns whether a given group of point lights is in an on state or off state.

Parameters:

sGroupName – The name of the group for which to set the on off state. NULL to set the value of the default state (for all lights).
bIsOn – Specify True to state the group to an on state. False for as off state.

Return Value:

zsOK if succeeded. zsERR_BadParam if failed.

SetLightGroupAttrib()

Sets a specific attribute of a light group.

Parameters:

sGroupName – The name of the group for which to set the attribute. NULL to set the default attribute for all lights.
ePLAttribute – The type of attribute to set.
vValues ‐ An array containing the list of new values for the attribute. NULL to unset the value (reset to default).
nArraySize – the length of vValues array . 0 to unset the value (reset to default).

Return Value:

zsOK if succeeded. zsERR_BadParam if failed.

Note that most properties expect an array of size 1. The exceptions to that rule are the Light direction attribute which expects an array of 3 values (yaw,pitch,roll). and the Light Color attribute which expects an array of 3 or 4 values (red,green,blue[,alpha]).

GetLightGroupAttrib()

Returns a specific attribute of a light group.

Parameters:

sGroupName – The name of the group for which to set the attribute. NULL to set the default attribute for all lights.
ePLAttribute – The type of attribute to set.
vValues ‐ A pre‐allocated array into which the values of the attribute will be updated.
nArraySize – the length of vValues array . 0 reset the value to defualt.
io_IsSet – Returns true if the attribute is set false if not.

Return Value:

zsOK if succeeded. zsERR_BadParam if failed.

Note that most properties expect an array of size 1. The exceptions to that rule are the Light direction attribute which expects an array of 3 values (yaw,pitch,roll). and the Light Color attribute which expects an array of 3 or 4 values (red,green,blue[,alpha]).

Daylight Effect Over Point Light

It is worth mentioning that point light intensity may vary during the time of day dependent on the amount of light in the simulation. Lights may appear brighter during night time than during daytime. This is to simulate the fact that lights appear less clear when they are surrounded by ambient light.

There are 2 [Graphic_Engine_Settings| Graphic Engine Settings] which control this effect:

  • Environment\Spot Day Coef Controls how bright lights are during daytime.
  • Environment\Spot Night Coef Controls how bright lights are during nighttime.

Under both setting the accepted value should be between 0 and 1. Where a value of 1 indicates that lights are fully visible, And 0 indicates that the lights will not be visible at all.

Code Example

Refer to the accompanying file for an example of the code.

Nellis Lights