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.
Sponsored Link
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.

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.

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 youfll 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 -
int lightID,
int red, int green, int blue, int alpha
)
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 );
}
SphereWithLight.vcssl
When you run this program, youfll see a sphere properly lit by your custom light sources. The output looks the same as the earlier example, but this time youfre 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(...).

- 3D Computer Graphics
- Setting Up the Foundation
- Mouse Control and Animation
- Using the Framework
- Creating and Placing Light Sources (and Adjusting Their Properties)
- Creating and Placing Models / Standard Models
- Creating and Placing Polygons, and Various Types of Polygons
- Moving 3D Objects
- Rotating 3D Objects
- Scaling 3D Objects
- Flipping 3D Objects
- Setting Colors for 3D Objects
- Configuring the Shape of 3D Objects
- Fill Settings for 3D Objects
- Material Settings for 3D Objects
- Understanding Coordinate Systems: Concepts, Creation, and Placement
- Moving Coordinate Systems
- Walking Coordinate Systems
- Controlling the Origin Position of a Coordinate System
- Rotating Coordinate Systems
- Spinning a Coordinate System
- Euler Angle-Based Attitude Control of Coordinate Systems
- Camera Work
- Creating, Placing, and Performing Basic Operations on Vectors
- Coordinate Transformations
- Screen Projection
- Collision Detection