Lighting

Scenes you draw with the functions above look rather flat because there is no light. The color if the faces is equal, independent of their orientation. To create more realistically looking scenes you must enable lighting and place lights at the correct places. Creating correctly lit scenes is not easy but the effect is very good.

To enable lighting you can use the following function;

d3d_set_lighting(enable) Enables or disables the use of lighting.

When using lighting, for each vertex of a polygon the color is determined. Next, the color of internal pixels is based on the color of these vertices. There are two ways this can be done: Either the whole polygon gets the same color, or the color is smoothly interpolated over the polygon. Default smooth shading is used. This can be changed using the following function:

d3d_set_shading(smooth) Set whether to use smooth shading or not.

To use lighting you obviously need to define lights. Two different lights exist: directional lights (like the sun), and positional lights. Lights have a color. (We only support diffuse light, not specular reflection.) There are usually only 8 hardware lights available, so you should use the functions below to define and manage "active" lights, not just all lights in the scene. The following functions exist to define and use lights:

d3d_light_define_direction(ind,dx,dy,dz,col) Defines a directed light. ind is the index of the light (use a small positive number). (dx,dy,dz) is the direction of the light. col is the color of the light (often you want to use c_white. This function does not turn the light on.
d3d_light_define_point(ind,x,y,z,range,col) Defines a point light. ind is the index of the light use a small positive number). (x,y,z) is the position of the light. range indicates till how far the light shines. The intensity of the light will decrease over this range. col is the color of the light. This function does not turn the light on.
d3d_light_enable(ind,enable) Enables (true) or disables (false) light number ind.

The last function, is for controlling what is called ambient light. Ambient light is the light that you get when there is no light. It's effectively the colour and brightness of the darknes of a scene. To control this light you use the command below:

d3d_light_define_ambient( colour ) The default colour is $000000  (black)

The way an object reflects light depends on the angle between the light direction and the normal of the surface, that is, the vector pointing away from the surface. Hence, to create lighted objects you need not only provide the position of the vertices but also their normals. For this four additional functions are avaliable to define the vertices of primitives:

d3d_vertex_normal(x,y,z,nx,ny,nz) Add vertex (x,y,z) to the primitive, with normal vector (nx,ny,nz).
d3d_vertex_normal_color(x,y,z,nx,ny,nz,col,alpha) Add vertex (x,y,z) to the primitive, with normal vector (nx,ny,nz), and with its own color and alpha value.
d3d_vertex_normal_texture(x,y,z,nx,ny,nz,xtex,ytex) Add vertex (x,y,z) to the primitive, with normal vector (nx,ny,nz), and with position (xtex,ytex) in the texture, blending with the color and alpha value set before.
d3d_vertex_normal_texture_color(x,y,z,nx,ny,nz,xtex,ytex,col,alpha) Add vertex (x,y,z) to the primitive, with normal vector (nx,ny,nz), and with position (xtex,ytex) in the texture, blending with its own color and alpha value.

Note that for the basic shapes that you can draw the normals are automatically set correctly.