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.

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 );
}

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

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 );  
	
	...

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

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:

• x, y, z: Specify the direction or position vector of the light source.
• power: Brightness of the light, from 0.0 (off) to 1.0 (max). A typical value is around 0.5 when using a single light source for the entire scene.

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 -

Arguments:

• lightID: The ID of the light source.
• rendererID: The ID of the renderer to which the light should be applied.

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

- Extended Function Format -

Arguments:

• lightID: The ID of the light source.
• rendererID: The ID of the renderer.
• coordinateID: The ID of the coordinate system where the light should be placed.

Setting Light Color

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

- Function Format -

Arguments:

• lightID: The ID of the light source to configure.
• red, green, blue, alpha: The RGBA components of the light's color. Each value should be between 0 and 255. For a review of how color components work and how they are blended, see the Base Setup section.

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 -

Arguments:

• lightID: The ID of the light source to move.
• x, y, z: The directional or positional vector of the light source.

Setting Light Brightness

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

- Function Format -

Arguments:

• lightID: The ID of the light source to configure.
• power: Brightness value, ranging from 0.0 (off) to 1.0 (max). A typical value is around 0.5 if you're using one light source to illuminate the entire scene.

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 );
}

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.

• The overall brightness is determined by the directional light created with newLight(...).
• The brightness of shaded areas is influenced by the ambient light created with newAmbientLight(...).

Execution Result

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