Creating and Placing Light Sources (and Adjusting Their Properties)

This section explains how to create and place light sources in a 3DCG scene, as well as how to configure their color and brightness.

- Table of Contents -

Placing a Sphere Model

Let's begin with a bit of setup.

To visualize how lighting affects 3D objects, we'll start by placing a simple sphere model. We'll go into more detail about model creation and placement in the next chapter, so for now just run the following code:


import graphics3d.Graphics3DFramework;
import Graphics3D;

// Called at the start of the program
void onStart ( int rendererID ) {
	
	// Optional: Set window size and background color
	setWindowSize( 800, 600 );
	setBackgroundColor( 0, 0, 0, 255 );
	
	// Create and place a sphere model
	int sphere = newSphereModel( 2.0, 2.0, 2.0, 12, 8 );
	mountModel( sphere, rendererID );
}
MountSphereDefaultLight.vcssl

When you run this program, a sphere will appear at the center of the screen. You'll notice that it has proper shading and appears three-dimensional. This is because the Graphics3DFramework automatically provides and places a default light source for you.

Execution Result
Execution Result
The sphere is rendered with shading, giving it a realistic, three-dimensional appearance.

Without a light source, the sphere would not be illuminated and would appear completely black. Let's try turning off the default light sources to confirm this. Add the following three lines somewhere in your onStart function:


...

// Called at the start of the program
void onStart ( int rendererID ) {
	
	// Turn off the default lights
	setDirectionalLightBrightness( 0.0 );
	setAmbientLightBrightness( 0.0 );  
	
	...
MountSphereNoLight.vcssl

Now when you run the program, the sphere will appear completely black -- because no light is hitting it.

Execution Result
Execution Result
With all light sources disabled, the sphere is rendered completely black.

Creating Light Sources

If you want finer control over lighting, you can disable the default light sources and manually create and place your own.

There are three functions for creating different types of lights:

int newLight ( int x, int y, int z, float power )
Creates a directional light that illuminates the entire scene from a specific direction.
int newLight ( int x, int y, int z, float power )
Creates a point light that emits light radially from a specific point.
int newAmbientLight ( int x, int y, int z, float power )
Creates an ambient light that uniformly lights objects regardless of direction (simulating environmental lighting).

Arguments:

These functions return a unique light ID for each created light source, which youfll use for placing and configuring them.

Placing Light Sources

To place a light source into the scene, use the mountLight(...) function.

- Basic Function Format -

void mountLight ( int lightID, int rendererID )

Arguments:

You can also place a light within a specific coordinate system by adding one more argument:

- Extended Function Format -

void mountLight ( int lightID, int rendererID, int coordinateID )

Arguments:

Setting Light Color

To set the color of a light source, use the setLightColor(...) function.

- Function Format -

void setLightColor (
  int lightID,
  int red, int green, int blue, int alpha
)

Arguments:

When you illuminate a model with colored light, each component of the light only affects the matching component of the model's color.

For example, the blue component of the light affects only the blue component of the model -- it doesn't affect the red or green.

This means that a white model illuminated by blue light will appear blue. But green or red models illuminated by blue light will remain mostly dark.

Setting Light Position

To change the position or direction of a light source, use the setLightLocation(...) function.

- Function Format -

void setLightLocation ( int lightID, float x, float y, float z )

Arguments:

Setting Light Brightness

To change the brightness of a light source, use the setLightBrightness(...) function.

- Function Format -

void setLightBrightness ( int lightID, float power )

Arguments:

If you use multiple light sources, you'll need to reduce the brightness of each one accordingly.

Also, if you set all lights to the same brightness and position them evenly around the object, the shading may become too uniform and lose depth. To avoid this, consider assigning slightly different brightness values to each light source.

Note: No Distance-Based Light Attenuation

VCSSL light sources do not reduce brightness based on distance. Whether the object is near or far, it will be lit with the same intensity.

If you want a distant light to appear dimmer, you'll need to manually reduce its brightness using setLightBrightness(...).

(There are future plans to add distance-based attenuation as a separate setting.)

Example Program

Now let's update the previous program to place custom light sources. Try running the code below:


import graphics3d.Graphics3DFramework;
import Graphics3D;

// Called at the start of the program
void onStart ( int rendererID ) {
	
	// Optional: set window size and background color
	setWindowSize( 800, 600 ) ;
	setBackgroundColor( 0, 0, 0, 255 );
	
	// Turn off the default light sources
	setDirectionalLightBrightness( 0.0 );
	setAmbientLightBrightness( 0.0 );
	
	// (1.2, 1.5, 1.0): Place a directional light with brightness 0.5
	int light = newLight( 1.2, 1.5, 1.0, 0.5 );
	mountLight( light, rendererID );
	
	// (0.0, 0.0, 0.0): Place an ambient light at the origin with brightness 0.5
	int ambientLight = newAmbientLight( 0.0, 0.0, 0.0, 0.5 );
	mountLight( ambientLight, rendererID );
	
	// Create and place a sphere model
	int sphere = newSphereModel( 2.0, 2.0, 2.0, 12, 8 );
	mountModel( sphere, rendererID );
}
SphereWithLight.vcssl

When you run this program, youfll see a sphere properly lit by your custom light sources. The output looks the same as the earlier example, but this time youfre using your own light setup, instead of the default lights provided by the framework.

Execution Result
Execution Result
The sphere is lit properly, with realistic shading and depth.