Insert_Spot_Light

Functions

HC_KEY DInsert_Spot_Light (const HCD_POINT *position, const HCD_POINT *target, const char *list)
 Similar to Insert_Spot_Light(), but accepts double-precision values for points. More...
 
HC_KEY Insert_Spot_Light (const HC_POINT *position, const HC_POINT *target, const char *list)
 Inserts a directional "point" source of light into your scene. More...
 

Detailed Description

Function Documentation

◆ DInsert_Spot_Light()

HC_KEY DInsert_Spot_Light ( const HCD_POINT *  position,
const HCD_POINT *  target,
const char *  list 
)

Similar to Insert_Spot_Light(), but accepts double-precision values for points.

Parameters
position- The location of the light source in object space or, optionally, in camera relative units. Passed by reference in all languages.
target- The target towards which the light source shines in user coordinates or, optionally, in camera relative units. Passed by reference in all languages.
list- A quoted string or a string variable containing a list of desired options for this specific light.
Returns
The key to the inserted geometry.

DETAILS

No additional details. See Insert_Spot_Light().

◆ Insert_Spot_Light()

HC_KEY Insert_Spot_Light ( const HC_POINT *  position,
const HC_POINT *  target,
const char *  list 
)

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

Parameters
position- The location of the light source in object space or, optionally, in camera relative units. Passed by reference in all languages.
target- The target towards which the light source shines in user coordinates or, optionally, in camera relative units. Passed by reference in all languages.
list- A quoted string or a string variable containing a list of desired options for this specific light.
Returns
The key to the inserted geometry, or -1 if an error occurred.
Supported Options:
camera relative, illumination cone, edge sharpness, outer cone, inner cone, concentration,

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. The lighting calculation also takes the color and orientation of each light, and figures out what color the face would appear to be at your camera's viewpoint in the "real world".

In HOOPS there are four possible sources of light:


The 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 spot light is the most general type of "point" light source in HOOPS; it can behave not only like a sharp-edged spotlight, but also like a variable-focus flashlight, or a fuzzy-edged floodlight. These characteristics are determined from the light's position, target, illumination cone, edge sharpness, and concentration parameters.

The light position and target points define a primary direction in which a spot light shines. Expanding in this direction from the light position is an infinite "cone of illumination" inside which surfaces are illuminated, and outside which surfaces are in complete shadow. A searchlight would have a very narrow illumination cone, compared to the wide cone of a floodlight.

The edge sharpness option "softens" the illumination or shadow edge by linearly decreasing the light intensity starting from an interior cone to zero intensity at the illumination cone. A theatre spotlight would have a very high edge sharpness when compared to a floodlight.

The concentration option allows a nonlinear (cosine power) roll-off in light intensity as you travel away (in angular measure) from the light's direction vector. Both a theatre spotlight and a floodlight would have little brightness variation throughout their illumination cones (ignoring the edges) and thus would be unconcentrated—a flashlight shines brighter along its direction vector, and is therefore more concentrated.

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, the light 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 that you can use Rotate_Object() on it in order to make the light orbit around your scene.

The options specified in the string list are characteristics for one specific light; and are not inherited like normal attributes. The following choices for list are recognized:

[no] camera relative [= on/off]

Normally the light position and target points you specify are in user space—this allows you to reposition your lights with modelling transformations such as Rotate_Object() . Specifying "camera relative" tells the system the light should be attached to the camera in effect at the light's segment—thus the light is repositioned along with the camera by routines like Orbit_Camera() .

With "camera relative", the specified light position is based on a coordinate system relative to the camera's position. The light target is based on a separate coordinate system relative to the camera's target point. For example, to have a spotlight located at the camera's position and pointed towards the camera's target you would specify a light position of (0, 0, 0) and light target of (0, 0, 0).

The camera relative coordinate systems are described as follows: the "Y" axes of the systems are parallel to the camera's up-vector; the "Z" axes are parallel to the camera's view-direction-vector (defined by the camera position and target points); and the "X" axes are perpendicular to both the "Y" and "Z" axes. Normally you would set the light target to (0, 0, 0) when using "camera relative" mode so both the camera and light point at the same thing.

The default is "camera relative = off", which means both the light position and target points are defined in the same user coordinate space as all other forms of geometry (independent of cameras).

illumination cone = size-spec

"Illumination cone" specifies the size of a conic region of space inside which surfaces will be illuminated by this light. Outside the specified region surfaces receive no illumination, no matter what the edge sharpness value.

Size-spec is a floating-point number followed by zero or more blanks followed by a "units specifier". The units specifier can be any of the following:

fru or field radius units

Defines the size of the cone based on the radius of a circular area (field) centered in the light's target plane (a plane perpendicular to the light-direction-vector passing through the light target point). The resultant cone size depends not only on the size-spec radius, but also on the distance of the light target point from the light position. The specified radius is measured in world coordinate units. Compare with Set_Camera_Field() .

deg or degrees

The cone size is defined by an angle measured from one edge of the cone—through the light-direction-vector—to the opposite cone edge.

A limitation of "field radius units" is that the light can't shine "behind" itself—an infinite field results in a cone angle of only 180 degrees. By specifying the cone size via angular measure, size-spec can be as large as 360 degrees (a light that shines in all directions). The cone size must be larger than 0 degrees.

The default is "illumination cone = 30 degrees".

edge sharpness = size-spec

Defines a second (interior) cone at which the light intensity starts to decrease linearly as you travel towards the illumination cone's edge (at which the intensity has decreased to zero) from the light-direction-vector.

Size-spec is a floating-point number followed by zero or more blanks followed by a "units specifier". The units specifier can be any of the following:

fru or field radius units
Same as above. "Edge sharpness" must be equal to (for a perfectly sharp edge) or less than (for a softer edge) the value given for "illumination cone".

deg or degrees
Same as above. "Edge sharpness" must be equal to (for a perfectly sharp edge) or less than (for a softer edge) the value given for "illumination cone".

%
Specifies the size of the inner (edge sharpness) cone as a percentage of the illumination cone size. A sharpness of 100 percent means there is an abrupt change in brightness at the illumination cone's edge. A 0 percent sharpness means the edge has been "softened" all the way in to the light-direction-vector.

The default is "edge sharpness = 80%".

outer cone = size-spec

"Outer cone" is a convenience synonym for "illumination cone".

inner cone = size-spec

"Inner cone" is a convenience synonym for "edge sharpness".

concentration = value

Changes the rate at which the light intensity decreases with increasing distance (in angular measure) from the light-direction-vector. Note the effect of concentration is in addition to the effect of edge sharpness. Edge sharpness applies only to the region between an inner cone and the illumination cone. Concentration effects the entire illuminated region.

Specifically, the light intensity falls off as the cosine of q raised to the power concentration, where q is the angle between the light-direction-vector and the point being shaded. "Concentration = 0.0" indicates all regions of the illumination cone (except the edge region) receive the same intensity. Higher concentration values indicate more of the light energy is being concentrated along the light-direction-vector.

When a non-zero concentration is specified, the light will have no illumination beyond 90 degrees from the light direction vector.
The default is "concentration = 1.0". Concentration must be equal to or greater than zero.

NOTES

The light target point must not be coincident with the light position. To generate an omni-directional light you would normally use Insert_Local_Light() , unless you wanted it camera mounted—in which case you should insert a spot light with any target point and specify "camera relative, illumination cone = 360 deg, edge sharpness = 100%, concentration = 0.0".

In the current version of HOOPS, the intensity of a spotlight 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, then 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.

Since setting "lighting interpolation = Phong" computes the shading of a surface at each pixel, it can accurately represent the intensity variations of a spotlight. However, "lighting interpolation = Gouraud" computes shading only at the face vertices, "no lighting interpolation" computes shading only once for the entire surface. With insufficient shading computations, scenes with spotlights might become heavily aliased.

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. See the "light scaling" driver option for a means of overriding this calculation.

The "fixed colors" driver option may also be of interest to you when using lights.

In the current implementation, lights only affect faces—lines and edges are 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 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 prevents a light placed elsewhere in the segment tree (but within the same window) from shining onto the local geometry. This can be useful for inserting things that don't need to be or shouldn't be lighted, such as annotations, into a lighted window.

Of the four 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, just insert a distant light that happens to be black.

RESTRICTIONS

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

See also
Insert_Local_Light, Insert_Distant_Light, Renumber_Key, Rotate_Object, Rotate_Object_Offaxis, Set_Camera, Set_Color, Set_Driver_Options, Set_Rendering_Options, Set_Visibility, Show_Spot_Light.