{{tag>lighting ies}}
<WRAP youarehere>
[[:start|Start Page]] >> [[:gamedev|Game Development with the Drag[en]gine]] >> [[:gamedev:lighting|Lighting System]] >> **IES Light Profiles**
</WRAP>

====== IES Image Module ======

The Drag[en]gine Game Engine includes by default the **IES Image Module**. This module allows loading IES Photometric files for use with [[gamedev:lighting|Lighting System]]. These files are created by measuring real world luminaires. By using such files complex and realistic light patterns can be simulated which improves the overall credibility of rendered scenes.

IES Files can be found on various pages of light fixture manufactures. There exists a large collection of free to use IES files here: [[https://ieslibrary.com/en/home|IES Library]].

The IES Image Module loads *.ies files as 16-bit, equirectangular omni-direction textures with normalized values. IES files contains candela values. By normalizing them into the range from 0 to 1 the loaded images can be used with light sources as light skin to shape the light while still using the light intensity to alter the overall intensity.

<WRAP center round info 60%>
IES profiles contain linear candela values. To use them with lighting the values would have to be gamma corrected by 1/2.2 . To avoid having to add the [[gamedev:textureproperties:color_gamma|color.gamma]] texture property to all light skins the IES Image Module applies gamma correction while rendering the profile as image object. This way loaded profiles can be used as drop-in replacement for existing omni-direction light skins.

If you want to access profile data in game scripts you have to reverse the gamma by using "pow(pixel, 2.2)".
</WRAP>

<WRAP center 100%>
<WRAP center box 450px>
{{youtube>LGBZLfGvm6M?medium}}
<WRAP centeralign>IES file handling</WRAP>
</WRAP>
</WRAP>

====== Usage ======

To use IES profiles as light skins you need to create a skin with one texture and one texture property of type [[gamedev:textureproperties:color_omnidir_equirect|color.omnidir.equirect]]. You can do this using the [[gamedev:deigde:editors:skin|IGDE Skin Editor]] or by creating a "*.deskin" file manually. A typical skin file looks like this:

<code xml><?xml version="1.0" encoding="ISO-8859-1"?>
<skin>
  <texture name='material'>
    <image property='color.omnidir.equirect'>/shareddata/materials/light/profiles/display.ies</image>
    <color property='omnidir.rotate.spot' r='0.25'/>
  </texture>
</skin>
</code>

The path to the IES file can be relative (to the directory the *.deskin is located in) or absolute. Using relative path makes skins easy to move between directories or game projects. The name of the texture is not important. Lights always use the first texture defined in a skin file.

If you want to use IES profiles for spot and projector type light sources you have to rotate the image first. This is required because IES profiles typically have the image shining down the Y-Axis. Spot and projector type light sources on the other hand shine along the Z-Axis. The image has to be rotated by 90° around the X-Axis to line them up. This example above contains such a rotation using [[gamedev:textureproperties:omnidir_rotate_spot|omnidir.rotate.spot]]. The texture property expects values in the range from 0 (0°) to 1 (360°). Hence 0.25 represents a 90° rotation. The components map to axes like this: red -> X-Axis, green -> Y-Axis, blue -> Z-Axis. Not set components are 0 hence no rotation.

As note there exist two rotation properties: [[gamedev:textureproperties:omnidir_rotate|omnidir.rotate]] and [[gamedev:textureproperties:omnidir_rotate_spot|omnidir.rotate.spot]]. The difference is that [[gamedev:textureproperties:omnidir_rotate|omnidir.rotate]] applies to all light sources including point lights whereas [[gamedev:textureproperties:omnidir_rotate_spot|omnidir.rotate.spot]] applies only to spot and projector type light resources. Using this property allows to create light skins which are compatible for all light sources.

====== Drag[en]gine IES Pack ======

The Drag[en]gine ships with a pack of 30 IES profiles ready to be used in your project. This pack is guaranteed to exist on all game engine installation (as shared DragonScript Module files). You do not need to copy them to your project. The IES images can be found at the in-game path <wrap hi>/shareddata/materials/light/profiles</wrap> with their respective skin files found at in-game path <wrap hi>/shareddata/materials/light</wrap>. This is an overview of the included profiles (click for larger image):

{{gallery> :gamedev:iesprofiles?0&200x200&lightbox&showname&titlesort }}

You can find them under the Skin Browser in the [[gamedev:deigde:editors:world|IGDE World Editor]]:
{{ :gamedev:ies_browsing.jpg |World Editor Light Skin Browsing}}

To apply the light skin to a light source either add the appropriate Object Property (typically "light.lightSkin") or right click on the light skin in the browser and click the desired "Active Object Set Property" menu entry.