Lights Introduction

In this case you will get high level understanding of Lights interface in SkyRenderer. You will learn what common
methods different types of lights share. A code example will be done based on a Point Light, however interface is
similar for most of the lights implemented in SkyRenderer. Feel free to return to this introduction tutorial as
you progress throughout light tutorials, since things will become clearer the more you know.

Agenda:

• Light types in SkyRenderer
• Light parameters
• How to set up lights in SkyRenderer?
• Manipulation of existing lights

Light Types

In SkyRenderer we have implemented multiple types of lights:

Parameters

We can modify behaviour of lights with different parameters.
Parameters can be divided into two main groups:

1. Coordinate space specific parameters
   Changes are done on the node level. Imagine it as moving/scaling/rotating the object in the space.
   Parameters:

   • translation - (X, Y, Z) position.

2. Light specific parameters
   Changes concern light type specific behaviour e.g., color, strength, size, shape etc.
   Even though light specific parameters differ for different types of lights, changes to these parameters are done
   via the same interface. All lights have implemented ParameterProvider method that is used to pass custom values
   for light parameters. If it's not clear - do not worry, we will elaborate more in code usage section further in
   the tutorial.
   A few exemplary light specific parameters:

   • color - 3 channel (Red, Green, Blue) color tuple - (R, G, B),
   • illuminance - light strength, illuminance in candelas,
   • sample density - sample angular density (number of rays per 1 degree).
     Bear in mind that above parameters do not exist in all light types. For available light parameters and their
     default values check light specific classes and their documentation e.g., PointLight, SphereLight etc.

Test scene setup

Let's use custom scene composer to set up other aspects of the scene.

Scene consists of:

• shaderball - location: (0, 0, 0)
• plane - location: (0, 0, 0)
• camera - location: (4, 2, 2)

When we try to render the scene, everything is black.

Why is that? There are no lights defined in the scene, so everything looks dark. In order to display colors on
the objects and shade them in proper way, we have to add lights to the scene.

Light setup process

Even though the lights differ, process of set up is similar for all of them.

High level description of flow is as follows:

1. Create / use already existing point (node) in the coordinate space that will be used as a light origin.
2. Create Light object in the aforementioned point.
3. Register light node in the scene.

As an example we will use one of the most common type of lights - Point Light.
We will create basic Light with line by line explanation, afterward we will modify its parameters values using
ParameterProvider. Do not focus right now on Point Light properties, but overall process of the light setup.

Create light node

To create a Light we need to define its location in a coordinate system.

Let's create a node a few units to the left from camera origin (reminder: (4, 2, 2)).

Create light object

Let's create a Point Light object in the location of a newly created node. To do so we must pass to PointLight
class two arguments:

• context - renderer context object storing all information about scene,
• origin_name - name of the origin of the light (node that we created).

Most of the lights usually require only these two arguments, however there may be some specific lights that need
more. In case of issues check particular Light class init and check if there are more arguments required.

Register light

Afterward we have to register light node in the renderer_context by set_light() method.

Let's visualize the output. As you can see we have basic, white light shining from the left side.

Light manipulation

We can modify light in render by modifying parameters of the light.

Location

By modification of origin's location, we get different render results. Imagine tiny light bulb that changes
location in the space.

Let's move light source further from the shaderball. Shaderball should be lit way weaker.

Let's move light source now extremely close to the shaderball. Shaderball should be lit extremely strong.

For the rest of the tutorial, we will change back to initial light position.

Light specific parameters

These changes are done via ParameterProvider. To change light specific parameter values we have to create
ParameterProvider object. All types of lights have implemented create_parameter_provider() method. Mandatory
argument for that method is renderer_context.

In method's documentation you can see what parameters can be passed to PointLight's create_parameter_provider()
method.
For Point Light these are:

• color
• illuminance
• sample_density
  Check a few other methods:

For Sphere Light these are:

• color
• illuminance
• radius
• sample_densitiy
• visibility

For Constant Light these are:

• color
• illuminance
• visibility

As you can see arguments passed to create_parameter_provider() method vary for different types of lights.
Let's see how we can use this Parameter Provider method to change the color of the light in the current scene.

Color

Let's modify values of color channels for light (R, G, B) channels and make the light red.
Keep in mind that change of the light with a new ParameterProvider has to be registered in the renderer_context
with set_light() method.

Let's visualize the output. As we can see red_light_parameter_provider enabled us creation of red_light Light
object, that has a color parameter value set to (1, 0.2, 0.2). Registering red_light node in renderer_context
saves the change of the light.

With create_parameter_provider() method you can change values of a few arguments at the same time, just pass into
the method values for a few arguments:

As you will see, our light becomes stronger this way.

Extra

What is more, when you create ParameterProvider, it can be passed to the other light instances, as long as it is
the same type of light. If you have in the scene two PointLights they can share the same ParameterProvider.
However, if you pass to SphereLight instance PointLight's ParameterProvider, you will encounter errors.

As mentioned in the Introduction we can also create lights in the location of already existing nodes.

Let's create in the location of camera (camera_CAM_NUL) a new light node using the same parameter provider as
already existing light_LIGHT_NUL.

As you can see, the shaderball is brighter and the shadow of it is weaker. It is due to the fact that currently
two light sources are shining in the scene.

For mor information about specific Lights check classes documentation or Light specific tutorials.

Summary

In this section you have learnt:

• The main flow for light creation.
• Common interface for lights.
• Modification of coordinate specific parameters.
• Modification of light specific parameters.
• Usage of ParameterProvider method.
• Mandatory and optional parameters of Light classes can be checked in the code.