lmdef(3G)lmdef(3G)NAMElmdef - defines or modifies a material, light source, or lighting model
C SPECIFICATION
void lmdef(deftype, index, np, props)
short deftype, index, np;
float props[];
PARAMETERS
deftype expects the category in which to create a new definition, or
the category of the definition to be modified. There are three
categories, each with its own symbolic constants:
DEFMATERIAL indicates that a material is being defined or
modified.
DEFLIGHT indicates that a light source is being defined or
modified.
DEFLMODEL indicates that a lighting model is being defined or
modified.
index expects the index into the table of stored definitions. There
is a unique definitions table for each category of definition
created by this routine (materials, light sources, or lighting
models). Indexes within each of these categories are
independent. In each category, index 0 is reserved as a null
definition, and cannot be redefined.
np expects the number of symbols and floating point values in
props, including the termination symbol LMNULL. If np is zero,
it is ignored. Operation over network connections is more
efficient when np is correctly specified, however.
props expects the array of floating point symbols and values that
define, or modify the definition of, the material, light
source, or lighting model named index. props must contain a
sequence of lighting symbols, each followed by the appropriate
number of floating point values. The last symbol must be
LMNULL, which is itself not followed by any values.
Different symbols are used to define materials, light sources, and
lighting models. The symbols used when deftype is DEFMATERIAL are:
ALPHA specifies the transparency of the material. It is followed by
a single floating point value in the range 0.0 through 1.0. This
alpha value is assigned to all RGB triples generated by the lighting
model. Alpha is ignored by systems that do not support blending,
and is always valid in systems that do, regardless of whether alpha
bitplanes are installed in the system. The default alpha value is
1.0.
Page 1
lmdef(3G)lmdef(3G)
AMBIENT specifies the ambient reflectance of the material. It is
followed by three floating point values, typically in the range 0.0
through 1.0, specifying red, green, and blue reflectances. The
default ambient reflectances are 0.2, 0.2, and 0.2.
COLORINDEXES specifies the material properties used when lighting in
color map mode. This property is ignored while the current
framebuffer is in RGB mode, as are most other material properties
when the current framebuffer is in color map mode. (Material
property SHININESS is used in color map mode.) It is followed by
three floating point values, assigning the ambient, diffuse, and
specular material color indices. The default color indices are 0.0,
127.5, and 255.0.
DIFFUSE specifies the diffuse reflectance of the material. It is
followed by three floating point values, typically in the range 0.0
through 1.0, specifying red, green, and blue diffuse reflectances.
The default diffuse reflectances are 0.8, 0.8, and 0.8.
EMISSION specifies the color of light emitted by the material. It
is followed by three floating point values, typically in the range
0.0 through 1.0, specifying red, green, and blue emitted light
levels. The default emission levels are 0.0, 0.0, and 0.0.
SHININESS specifies the specular scattering exponent, or the
shininess, of the material. It is followed by a single floating
point value in the range 0.0 through 128.0. Higher values result in
smaller, hence more shiny, specular highlights. The default
shininess is 0.0, which effectively disables specular reflection.
SPECULAR specifies the specular reflectance of the material. It is
followed by three floating point values, typically in the range 0.0
through 1.0, specifying red, green, and blue specular reflectances.
The default specular reflectances are 0.0, 0.0, and 0.0.
The symbols used when deftype is DEFLIGHT are:
AMBIENT specifies the ambient light associated with the light
source. It is followed by three floating point values, typically in
the range 0.0 through 1.0, specifying red, green, and blue ambient
light levels. The default ambient levels are 0.0, 0.0, and 0.0.
LCOLOR specifies the color and intensity of the light that is
emitted from the light source. It is followed by three floating
point values, typically in the range 0.0 through 1.0, specifying the
levels of red, green, and blue light emitted from the light source.
The default light colors are 1.0, 1.0, and 1.0.
POSITION specifies the position of the light source in the scene.
It is followed by four floating point values, specifying x, y, z,
and w of the light source position in object-coordinates. If w is
specified as 0.0, the light source is taken to be infinitely distant
Page 2
lmdef(3G)lmdef(3G)
from the origin of the coordinate system. In this case x, y, and z
specify the direction from the origin to the infinitely distant
light source. There is typically a performance penalty associated
with light sources that are not infinitely distant. The default
light source position is at infinity directly behind the viewpoint,
location (0.0, 0.0, 1.0, 0.0). The location of the light source is
transformed by the current ModelView matrix when the source is bound
(see lmbind).
SPOTDIRECTION specifies the direction that a spot light source emits
its light. It is followed by three floating point values,
specifying x, y, and z direction vectors in object-coordinates.
These vectors are normalized automatically. The direction is
ignored if the light source is not a spot light. By default the
spot light points down the negative z axis, direction (0.0, 0.0, -
1.0). The direction is transformed by the current ModelView matrix
when the light source is bound (see lmbind).
SPOTLIGHT indicates that the light source is to be treated as a spot
light. (The light source must not be positioned at infinity.) It
is followed by two floating point values, specifying the exponent
and the spread of the light cone. exponent controls intensity as a
function of angle from the spot light direction. Its range is 0.0
through 128.0, where 0.0 results in constant intensity throughout
the cone, and 128.0 results in the sharpest dropoff of intensity as
angle from spot direction increases. spread is the angle in
degrees, measured from the spot light direction, beyond which the
cone is attenuated to zero intensity. Currently only spread values
in the range 0.0 through 90.0, and the special value 180.0, are
supported. By default exponent is 0.0 and spread is 180.0,
effectively disabling spot lighting.
The symbols used when deftype is DEFLMODEL are:
AMBIENT specifies an additional ambient light level that is
associated with the entire scene, rather than with a light source.
This light is added to the ambient light associated with each light
source to yield the total ambient light in the scene. AMBIENT is
followed by three floating point values, typically in the range 0.0
through 1.0, specifying red, green, and blue ambient light levels.
The default lighting model ambient light levels are 0.2, 0.2, and
0.2.
ATTENUATION specifies the constant and linear attenuation factors
associated with all non-infinite light sources. It is followed by
two floating point values in the range 0.0 through positive
infinity. The first attenuation factor is used to directly reduce
the effect of a light source on objects in the scene. The second
factor specifies attenuation that is proportional to the distance of
the light source from the object being lighted. The default
constant and linear attenuations are 1.0 and 0.0, effectively
disabling constant and linear attenuation.
Page 3
lmdef(3G)lmdef(3G)
ATTENUATION2 specifies the second-order attenuation factor
associated with all non-infinite light sources. It is followed by a
single floating point value in the range 0.0 through positive
infinity. This factor specifies attenuation that is proportional to
the square of the distance of the light source from the object being
lighted. The default second-order attenuation is 0.0, effectively
disabling second-order attenuation.
LOCALVIEWER specifies whether reflection calculations are done based
on a local or infinitely distant viewpoint. It is followed by a
single floating point value, which must be either 0.0 or 1.0. The
value 0.0 indicates that the viewpoint is to be (0.0, 0.0, infinity)
in eye-coordinates, hence infinitely distant from all objects in the
scene. The value 1.0 indicates that the viewpoint is to be
(0.0, 0.0, 0.0) in eye-coordinates, hence local. There is typically
a performance penalty associated with a local viewpoint. By default
the viewpoint is infinitely distant.
TWOSIDE specifies whether lighting calculations are done assuming
that only frontfacing polygons are visible, or are corrected for
each polygon based on whether it is frontfacing or backfacing. It
is followed by a single floating point value, which must be either
0.0 or 1.0. The value 0.0 specifies a lighting model that is
correct only for polygons whose visible face is the facet for which
normals have been provided. The value 1.0 specifies a lighting
model that is correct for both frontfacing and backfacing polygons.
When TWOSIDE is 1.0, vertex normals are reversed (all components
multiplied by -1.0) for all vertices of backfacing polygons. Thus,
for two-sided lighting to operate correctly, normals must be
specified for the facet whose screen rotation is counter-clockwise
(i.e. for frontfacing facets). If a material is bound to
BACKMATERIAL, this material is used to light backfacing polygons
(see lmbind). Otherwise, both frontfacing and backfacing polygons
are lighted using MATERIAL.
Lighting calculations for all primitives other than polygons, such
as points, lines, and characters, are unaffected by the TWOSIDE
flag. By default two-sided lighting is disabled.
DESCRIPTIONlmdef either defines a new material, light source, or lighting model, or
modifies the definition of a currently defined material, light source, or
lighting model. deftype specifies whether a material, light source, or
lighting model is being defined or modified. index is the name of the
material, light source, or lighting model. props is a list of attribute
tokens, each followed by one or more floating point values, that
initializes or modifies the definition. The last attribute token in the
array must be LMNULL.
When lmdef is first called with a particular deftype/index combination,
the material, light source, or lighting model of name index is created
with the attributes specified in props, and with default values for all
Page 4
lmdef(3G)lmdef(3G)
attributes that are not included in props. Subsequent lmdef calls with a
deftype/index combination modify only the attributes included in props.
Prior to the first lmdef call, deftype/index combinations are undefined,
and cannot be bound (see lmbind). A definition can be reset to all
default attributes by passing its deftype and index to lmdef with a null
attribute list (props contains only LMNULL). Changes made to a currently
bound definition are effective immediately.
Lighting calculations are done in a numeric space where 0.0 is black (no
light) and 1.0 is white (the brightest displayable light). Color
attributes are specified in this numeric space, although values outside
the range 0.0 through 1.0 are allowed. Lighting specified using lmdef
occurs only at the vertices of points, lines, polygons, and at the origin
of text strings. At each vertex the contributions of each light source
are summed with the material emitted light and the lighting model ambient
(scaled by the material ambient reflectance) to yield the vertex color.
After each lighting calculation is completed, the computed color
components are clamped to a maximum value of 1.0, then scaled by 255.0
prior to interpolation in the framebuffer.
The contribution of each light source is the sum of:
light source ambient color, scaled by material ambient reflectance,
light source color, scaled by material diffuse reflectance and the
dot product of the vertex normal and the vertex-to-light source
vector, and
light source color, scaled by material specular reflectance and a
function of the angle between the vertex-to-viewpoint vector and the
vertex-to-light source vector.
Material 0, light source 0, and lighting model 0 are null definitions
that cannot be changed.
The default material is defined as:
ALPHA 1.0
AMBIENT 0.2, 0.2, 0.2
COLORINDEXES 0.0, 127.5, 255.0
DIFFUSE 0.8, 0.8, 0.8
EMISSION 0.0, 0.0, 0.0
SHININESS 0.0
SPECULAR 0.0, 0.0, 0.0
The default light source is defined as:
AMBIENT 0.0, 0.0, 0.0
LCOLOR 1.0, 1.0, 1.0
POSITION 0.0, 0.0, 1.0, 0.0
SPOTDIRECTION 0.0, 0.0, -1.0
Page 5
lmdef(3G)lmdef(3G)
SPOTLIGHT 0.0, 180.0
The default lighting model is defined as:
AMBIENT 0.2, 0.2, 0.2
ATTENUATION 1.0, 0.0
ATTENUATION2 0.0
LOCALVIEWER 0.0
TWOSIDE 0.0
SEE ALSO
lmbind, lmcolor, mmode, n, nmode
NOTES
This routine is available only in immediate mode.
Lighting requires that the matrix mode be multi-matrix. It does not
operate correctly while mmode is MSINGLE.
IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support
light source attributes SPOTLIGHT or SPOTDIRECTION, or lighting model
attributes ATTENUATION2 or TWOSIDE. Use getgdesc to determine which
lighting model attributes are supported.
BUGS
The results of lighting calculations are clamped to a maximum value of
1.0, but not to a minimum value of 0.0. If only positive color
attributes are specified in the active material, light sources, and
lighting model, the computed color cannot have negative components.
However, if negative attributes are specified, care must be taken to not
produce negative results.
Many attributes are not used by the current color map lighting model.
Some may be used in future releases.
Page 6
