Keeping TechPubs alive!
| Hardware | IRIX 5.3 | IRIX 6.2 | IRIX 6.3 | IRIX 6.4 | IRIX 6.5 | Linux | Windows |
| Admin | Developer | End User | Manual Pages |
TechPubs » IRIX 5.3 » Manual Pages
lmdef(3G)
NAME
lmdef - defines or modifies a material, light source, or lighting model
FORTRAN 77 SPECIFICATION
subroutine lmdef(deftype, index, np, props)
integer*4 deftype, index, np
real props(np)
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:
DEFMAT indicates that a material is being defined or modified.
DEFLIG indicates that a light source is being defined or
modified.
DEFLMO 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 DEFMAT 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.
AMBIEN 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.
COLORI 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 SHININ 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.
DIFFUS 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.
EMISSI 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.
SHININ 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.
SPECUL 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 DEFLIG are:
AMBIEN 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.
POSITI 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
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).
SPOTDI 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).
SPOTLI 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 DEFLMO are:
AMBIEN 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. AMBIEN 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.
ATTENU 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.
ATTEN2 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.
LOCALV 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.
TWOSID 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 TWOSID 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 BACKMA,
this material is used to light backfacing polygons (see lmbind).
Otherwise, both frontfacing and backfacing polygons are lighted
using MATERI.
Lighting calculations for all primitives other than polygons, such
as points, lines, and characters, are unaffected by the TWOSID flag.
By default two-sided lighting is disabled.
DESCRIPTION
lmdef 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
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
AMBIEN 0.2, 0.2, 0.2
COLORI 0.0, 127.5, 255.0
DIFFUS 0.8, 0.8, 0.8
EMISSI 0.0, 0.0, 0.0
SHININ 0.0
SPECUL 0.0, 0.0, 0.0
The default light source is defined as:
AMBIEN 0.0, 0.0, 0.0
LCOLOR 1.0, 1.0, 1.0
POSITI 0.0, 0.0, 1.0, 0.0
SPOTDI 0.0, 0.0, -1.0
SPOTLI 0.0, 180.0
The default lighting model is defined as:
AMBIEN 0.2, 0.2, 0.2
ATTENU 1.0, 0.0
ATTEN2 0.0
LOCALV 0.0
TWOSID 0.0
SEE ALSO
lmbind, lmcolo, 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 MSINGL.
IRIS-4D G, GT, and GTX models, and the Personal Iris, do not support
light source attributes SPOTLI or SPOTDI, or lighting model attributes
ATTEN2 or TWOSID. Use getgde to determine which lighting model attri-
butes 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 attri-
butes 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.