From Kraytracing Wiki

Contents 1 General 1.1 Defining lights 1.2 Naming lights 2 Light types 2.1 Directional Light 2.2 Point Light 2.3 Point Light with inverse square falloff 2.4 Spot Lights (sharp edge) 2.5 Soft Edge Spot Lights 2.6 Linear light 2.7 Area light 3 Light properties 3.1 Photon multipliers 3.2 Light Emitting Material 3.3 Light quality settings 3.3.1 Linear lights 3.3.2 Area lights 3.3.3 Light Emitting Materials

General

Kray supports a number of different types of lights. The most common are:-

• Point lights
• Spot lights
• Light emitting materials

However there are also:-

• Area lights
• Parallel lights
• Projector lights

These can all be defined within scripts, these can be in a single script file defining the scene, materials and render parameters, or in a separate file referenced with the script:-

include file_name;

All lights require their coordinates and colour defining. Coordinates are defined by vectors in the following format:-

(x_coord,y_coord,z_coord)

Colours are defined in terms of RGB values from 0 to 1. Therefore to convert RGB255 values for use in kray scripts, you need to divide the value by 255. So for example a colour defined with a red value of 200, a green value of 220 and a blue value of 250 would be expressed as:-

(0.784,0.862,0.98)

Defining lights

Light command creates light and adds it to the scene. Sometimes we need to define light with a name we can refer later. This is done with

lightname light_name,...light definition...;

where ...light definition... is same light description as used with light command. Most common use of lightdefine is adding distance falloff to lights. Example:

lightdefine my_light,(0,-5,10),(1,1,1);    // define light
light fade,my_light;                       // add to scene

Lightdefine command does not add light to scene, it only creates light which can be altered before adding to scene.

Naming lights

There is also a way to give a name to light added to scene. Syntax is similar.

lightname my_light,(0,-5,10),(1,1,1);

Light names are needed to refer skyportals (connect skyportal with light). Commands that modifies properties of lights already added to scene also uses those names.

Light types

Directional Light

To define directional light use:

light parallel,direction,color;

Example:

light parallel,(0,1,0),(1,1,1);

Point Light

These are added in script with the code:

light point,position,color;

Example:

light point,(0,-5,10),(1,1,1);

Point Light with inverse square falloff

Similar to point, but with physically correct falloff. Only inverse square falloff light can cast photons. They are required for correct global illumination.

Syntax:

light fadepoint,position,color;

Example:

light fadepoint,(0,-5,10),(1000,1000,1000);

Color value is (1000,1000,1000). This is to compensate light falloff.

The light fade parameter configures the light falloff over distance so that it is a physically accurate representation.

Spot Lights (sharp edge)

There are 2 types of spot lights, sharp spots and soft spots. The difference is the softness of the shadows. There are some additional parameters compared with point lights. These are the spotlight target and the beam angle. The spotlight target is expressed as a vector in terms of x,y and z coordinates. This means that the target coordinates must be subtracted from the location coordinates like this:-

direction=(target_x_coord-position_x_coord,target_y_coord-position_y_coord,target_z_coord-position_z_coord)

The light strength is a real number and the beam angle is expressed in radians.

They are added in script with the code:-

light sharpspot,position,direction,color,beam_angle;

Example:

light sharpspot,(0,-5,10),(0,1,0),(0,1,0),0.1;

Soft Edge Spot Lights

Script

light softspot,position,direction,color,beam_angle1,beam_angle2;

creates light with soft edge (between beam_angle1 and beam_angle2)

Example:

light softspot,(0,-5,10),(0,1,0),(0,1,0),0.1,0.11;

Linear light

Linear light is a light emmiting line. Code

light linear,position,direction_and_length,light_color;

adds light emitting line which one end is in position and another and is position+direction_and_length. Note that linear lights have a build in inverse square falloff. They are physically correct and can be added to GI scene without additional falloff filters.

Example:

light linear,(0,-5,10),(0,1,0),(1000,1000,1000);

Area light

Area light is a rectangle that emits light. Code

light adaptive,position,dx,dy,light_texture,noise_tolerance,min_subdivide_lvl,max_subdivide_lvl;

adds area light to the scene. dx and dy are rectangle sides vectors. noise_tolerance,min_subdivide_lvl and max_subdivide_lvl controls quality of area light sampling.

Example:

texture my_texture,color,(1000,1000,1000);
light adaptive,(0,-5,10),(1,0,0),(0,0,1),my_texture,0.01,0,4;

Light properties

Photon multipliers

Photon multipliers are used to alter number and power of photons emitted by lights. Self explaing example below:

lightphotonmultiplier <scene_light_name>,<photon_number_multiplier>,<photon_power_multiplier>;

Light Emitting Material

These are defined in the material properties.

Light quality settings

Linear lights

Controlled with

linadaptive noise_tolerance,min_recursion_level,max_recursion_level

Each recurson level multiplies number of ray samples by 2. Kray samples light until noise gets lower then noise_tolerance or when max_recursion_level is reached, but recursion is never lower then min_recursion_level.

Example:

linadaptive 0.002,1,4;

Area lights

Controlled with

squareplanar noise_tolerance,min_recursion_level,max_recursion_level

Similar to linear lights above, but each recursion level multiplies number of samples by 4.

Example:

squareplanar 0.002,1,4;

Light Emitting Materials

Controlled with

planar noise_tolerance,min_sample_rays,max_sample_rays

This settings are similar to noise level controlls used by reflection and refraction blur.

Example:

planar 0.002,100,1000;