This section explains how to create and place light sources in a 3DCG scene, as well as how to configure their color and brightness.
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.
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:
Arguments:
These functions return a unique light ID for each created light source, which youfll use for placing and configuring them.
To place a light source into the scene, use the mountLight(...) function.
- Basic Function Format -
Arguments:
You can also place a light within a specific coordinate system by adding one more argument:
- Extended Function Format -
Arguments:
To set the color of a light source, use the setLightColor(...) function.
- Function Format -
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.
To change the position or direction of a light source, use the setLightLocation(...) function.
- Function Format -
Arguments:
To change the brightness of a light source, use the setLightBrightness(...) function.
- Function Format -
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.
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.)
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.