Brief Index      Full Index      I.M. Reference

Insert_Distant_Light


Functions

void Insert_Distant_Light (double di, double dj, double dk)
HC_KEY KInsert_Distant_Light (double di, double dj, double dk)
void QInsert_Distant_Light (const char *segment, double di, double dj, double dk)
HC_KEY QKInsert_Distant_Light (const char *segment, double di, double dj, double dk)
void DInsert_Distant_Light (double di, double dj, double dk)
HC_KEY DKInsert_Distant_Light (double di, double dj, double dk)
void DQInsert_Distant_Light (const char *segment, double di, double dj, double dk)
HC_KEY DQKInsert_Distant_Light (const char *segment, double di, double dj, double dk)

Function Documentation

void Insert_Distant_Light ( double  di,
double  dj,
double  dk 
)

Inserts a "distant" point source of light into your scene.

Parameters:
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.

DETAILS

Normally, when you set the color of a surface (a polygon, mesh, or shell face) HOOPS draws the surface in the specified color. When HOOPS sees that a window is going to have one or more lights in it, it switches gears and performs what is known as a "lighting calculation". The lighting calculation consists of taking the color and orientation of each face, and the color and orientation of each light. Then the lighting calculation figures out what color the face would appear to be at your camera's viewpoint in the "real world".

In HOOPS there are five possible sources of light. A scene's ambient light intensity defined by Set_Color() . Individual distant (point) lights created by Insert_Distant_Light() . Individual local (point) lights created by Insert_Local_Light() . Individual directional local (point) lights created by Insert_Spot_Light() .


A distant light is similar to the sun: it's so far away that all the light rays arriving from it are parallel. The only important considerations are the light's color and direction---not its position. The direction specified by Insert_Distant_Light() can later be modified by the modelling transformations. The color is defined by the "lights" option of Set_Color() . Unlike local, spot, and area lights, distant lights illuminate all surfaces in a scene with equal intensity (the intensity defined by Set_Color() ).

The scope of a light is always its containing window. Even if the light is many levels down from the window in the segment tree, it still "shines light" on everything in the scene --- i.e., everything in the window (except as noted below, under "light visibility"). In fact, if you want to have several lights of different colors you'll have to put them in different lower-level segments in order to set the different color attributes. You might also want to put a light in its own subsegment so you can use Rotate_Object() on it in order to make the light orbit your scene.

NOTES

If the light is shining on one side of a given face and you're looking at the other side, the side you're looking at is in the shadow of the face and is not lit by the light. Beyond this effect, shadows are not computed by the standard shaders ("no lighting interpolation", Gouraud, and Phong). If you request shadows in your scene via advanced radiosity or ray-trace computations (see Set_Rendering_Options() ), shadows generated from a specific light can be turned off with Set_Visibility() ("shadows = no emitting").

The number of lights you can have in a scene is almost unlimited. Since the screen isn't able to keep getting brighter and brighter as additional lights are inserted, HOOPS scales the total brightness by the total brightness of all the light sources. Please see the "light scaling" Driver Option for a means of overriding this calculation.

The "fixed colors" Driver Option might also be of interest when using lights.

In the current implementation, lights only affect faces. Lines and edges are still drawn in the standard way, with static colors. (Warning: this might change in a future release.)

Turning off the visibility of a light makes that light cease to exist for the purpose of performing, a lighting calculation. This may be a convenient way to enter and leave "lighted" mode in your program.

Turning off the light visibility also prevents a light placed elsewhere in the segment tree (but within the same window) from shining through the local geometry. This might be useful for inserting geometries that don't need to be or shouldn't be lit, such as annotations, into a lighted window.

Of the five types of possible light sources listed above, an ambient light is not sufficient to trigger the HOOPS "lighted" mode. If you only want to display the effect of the ambient light, and you need to trigger the system to go into "lighted" mode, insert a distant light that happens to be black.

If there is an error, the KInsert routine will return a-1.

RESTRICTIONS

In OpenGL, the maximum number of supported lights is 8. For DX9, the maximum number of lights is 15.

See also:
Insert_Local_Light, Insert_Spot_Light, Renumber_Key, Rotate_Object, Rotate_Object_Offaxis, Set_Color, Set_Driver_Options, Set_Rendering_Options, Set_Visibility, Show_Distant_Light, Move_Distant_Light.

HC_KEY KInsert_Distant_Light ( double  di,
double  dj,
double  dk 
)

Similar to Insert_Distant_Light(), but returns an HC_KEY to the object.

Parameters:
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.
Returns:
key

DETAILS

No additional details. See Insert_Distant_Light()

void QInsert_Distant_Light ( const char *  segment,
double  di,
double  dj,
double  dk 
)

Similar to Insert_Distant_Light(), but operates on a given segment rather than the currently open one.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.

DETAILS

No additional details. See Insert_Distant_Light()

HC_KEY QKInsert_Distant_Light ( const char *  segment,
double  di,
double  dj,
double  dk 
)

Similar to Insert_Distant_Light(), but operates on a given segment and returns an HC_KEY to the object.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.
Returns:
key

DETAILS

No additional details. See Insert_Distant_Light()

void DInsert_Distant_Light ( double  di,
double  dj,
double  dk 
)

Similar to Insert_Distant_Light(), but accepts and/or returns double-precision values. This command can only be used if the application code includes the HOOPS double-precision header, hcd.h.

Parameters:
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.

DETAILS

No additional details. See Insert_Distant_Light().

HC_KEY DKInsert_Distant_Light ( double  di,
double  dj,
double  dk 
)

Similar to DInsert_Distant_Light(), but returns an HC_KEY to the object.

Parameters:
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.
Returns:
key

DETAILS

No additional details. See Insert_Distant_Light()

void DQInsert_Distant_Light ( const char *  segment,
double  di,
double  dj,
double  dk 
)

Similar to DInsert_Distant_Light(), but operates on a given segment rather than the currently open one.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.

DETAILS

No additional details. See Insert_Distant_Light()

HC_KEY DQKInsert_Distant_Light ( const char *  segment,
double  di,
double  dj,
double  dk 
)

Similar to DInsert_Distant_Light(), but operates on a given segment and returns an HC_KEY to the object.

Parameters:
segment - Segment(s) to be inserted into, if other than the currently- open segment.
di - Vector describing the direction in which the light lies, infinitely far away.
dj - As above.
dk - As above.
Returns:
key

DETAILS

No additional details. See Insert_Distant_Light()

Main Index
Brief Index      Full Index      I.M. Functions