Brief Index      Full Index      I.M. Reference

Insert_Local_Light


Functions

void Insert_Local_Light (double x, double y, double z)
HC_KEY KInsert_Local_Light (double x, double y, double z)
void QInsert_Local_Light (const char *segment, double x, double y, double z)
HC_KEY QKInsert_Local_Light (const char *segment, double x, double y, double z)
void DInsert_Local_Light (double x, double y, double z)
HC_KEY DKInsert_Local_Light (double x, double y, double z)
void DQInsert_Local_Light (const char *segment, double x, double y, double z)
HC_KEY DQKInsert_Local_Light (const char *segment, double x, double y, double z)

Function Documentation

void Insert_Local_Light ( double  x,
double  y,
double  z 
)

Inserts an omni-directional "point" source of light into your scene.

Parameters:
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.

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, and figuring out what color the face would appear to be at your camera's viewpoint in the "real world".

A local light is similar to a tiny light bulb. The "light bulb" in HOOPS is infinitely small---it occupies only a point in space and radiates in all directions equally (omni-directional). Important considerations are the light's location and color---not its direction. The location of the light is defined by Insert_Local_Light() . The light's location can be modified by the modelling transformations. The light's intensity is defined by the "lights" option of Set_Color() .

NOTES

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 may 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.

In the current version of HOOPS, the intensity of a local light does not decrease as you get further away from it.

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.

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

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

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

RESTRICTIONS

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

See also:
Insert_Spot_Light, Insert_Distant_Light, Renumber_Key, Rotate_Object, Rotate_Object_Offaxis, Set_Camera, Set_Color, Set_Driver_Options, Set_Rendering_Options, Set_Visibility, Show_Local_Light.

HC_KEY KInsert_Local_Light ( double  x,
double  y,
double  z 
)

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

Parameters:
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.
Returns:
key

DETAILS

See Insert_Local_Light(). Additionally, if there is an error the KInsert routine returns a -1.

void QInsert_Local_Light ( const char *  segment,
double  x,
double  y,
double  z 
)

Similar to Insert_Local_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.
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.

DETAILS

No additional details. See Insert_Local_Light()

HC_KEY QKInsert_Local_Light ( const char *  segment,
double  x,
double  y,
double  z 
)

Similar to Insert_Local_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.
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.
Returns:
key

DETAILS

See Insert_Local_Light(). Additionally, if there is an error the QKInsert routine returns a -1.

void DInsert_Local_Light ( double  x,
double  y,
double  z 
)

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

Parameters:
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.

DETAILS

No additional details. See Insert_Local_Light()

HC_KEY DKInsert_Local_Light ( double  x,
double  y,
double  z 
)

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

Parameters:
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.
Returns:
key

DETAILS

See Insert_Local_Light(). Additionally, if there is an error the DKInsert routine returns a -1.

void DQInsert_Local_Light ( const char *  segment,
double  x,
double  y,
double  z 
)

Similar to DInsert_Local_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.
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.

DETAILS

No additional details. See Insert_Local_Light()

HC_KEY DQKInsert_Local_Light ( const char *  segment,
double  x,
double  y,
double  z 
)

Similar to DInsert_Local_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.
x - The x-position of the point light in object space.
y - The y-position of the point light in object space.
z - The z-position of the point light in object space.
Returns:
key

DETAILS

See Insert_Local_Light(). Additionally, if there is an error the DQKInsert routine returns a -1.

Main Index
Brief Index      Full Index      I.M. Functions