[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
GL3.2 for AIX: Graphics Library (GL) Technical Reference

lmdef Subroutine

Purpose

Defines a new material, light, or lighting model.

Libraries

Graphics Library

C (libgl.a)

FORTRAN (libfgl.a)

C Syntax

void lmdef
(Int16 deftype, Int32 index, 
Int16 numpoints, Float32 properties[ ])

FORTRAN Syntax

SUBROUTINE LMDEF(deftype, index, numpoints, properties)
INTEGER*4 deftype, numpoints, index
REAL properties(numpoints)
Note: For FORTRAN users, this subroutine accepts long integer parameters (INTEGER*4) when started from a FORTRAN program, although it accepts short integers when started from a C program. The C and FORTRAN syntax shown here reflect this difference.

Description

The lmdef subroutine defines a new material, light, or lighting model.

The type of definition (material, light, or lighting model) is specified by the deftype parameter. The definition is read from the properties array and stored in the appropriate definition table at the index specified by the index parameter.

You can make incremental changes to a material, light, or lighting model definition. Each call to the lmdef subroutine changes only the properties specified in the properties array.

Any property of any definition can be changed regardless of whether that definition is currently bound. Changes made to a definition that is currently bound by the lmbind subroutine are effective immediately.

Index 0 (zero) of the material, light, and lighting model definition tables contains predefined definitions. These predefined definitions have set all properties to their default values and cannot be changed. Their values are as follows:

Value Function
DEFMATERIAL Turns off lighting. Most efficient way to disable calculations. Equivalent to lighting model 0.
DEFLIGHT Turns off lighting. Binding light 0 to a light turns off that light.
DEFLMODEL Turns off lighting.

To turn off lighting, bind material 0 as the current material. You can also turn off lighting by binding lighting model 0 as the current lighting model, but this method is less efficient than binding material 0. To turn off a light, but not all lighting calculations, bind light definition 0 to the light you want to turn off.

There is a unique properties table for each category of definition created by this routine (materials, light sources, or lighting models). Indexes within each of these categories are independent. Valid entries for this parameter range from 1 to 65535. In each category, index 0 is reserved.

For maximum efficiency, use the default values for all properties. Lighting model performance is best if relatively few properties are changed from the default. A definition can be reset to all default values by calling the lmdef subroutine with the symbolic constant LMNULL as the first command token in the properties array.

The default material values are as follows:
EMISSION 0.0, 0.0, 0.0
AMBIENT 0.2, 0.2, 0.2
DIFFUSE 0.8, 0.8, 0.8
SPECULAR 0.0, 0.0, 0.0
SHININESS 0.0
ALPHA 1.0
COLORINDEXES 0.0, 127.5, 255.0
The default light values are as follows:
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
SPOTLIGHT 0.0, 180.0

The default lighting model values are as follows:

AMBIENT 0.2, 0.2, 0.2
LOCALVIEWER 0.0
ATTENUATION 1.0, 0.0
Notes:
  1. The operation of this subroutine for the Supergraphics Processor Subsystem is modified. (See "Hardware Considerations".)
  2. This subroutine cannot be used to add to a display list.

Parameters

deftype Category in which you want to create a new definition. There are three categories:
Constant
C FORTRAN Description
DEFMATERIAL DEFMAT Indicates that this routine defines the properties of a material.
DEFLIGHT DEFLIG Indicates that this routine defines the properties of a light source.
DEFLMODEL DEFLMO Indicates that this routine defines the properties of a lighting model.
index Specifies the index into the table of stored definitions.
numpoints Specifies the number of floating-point values contained within the properties array.
properties Specifies an array that contains the definition to store at the index parameter. A definition is a grouping of properties and values ended by the symbolic constant LMNULL. There is a total of 13 defined symbolic constants (command tokens) that identify the properties of a definition. The valid symbolic constants for the properties parameter are shown in the following table.
Constant

C FORTRAN Description
EMISSION EMISSI Assigns an emission color to a material. Following this symbolic constant, enter the red, green, and blue color component values for the desired emission color. Valid color component values range from 0.0 to 1.0 inclusive.
AMBIENT AMBIEN Can be a property of a material, a light, or a lighting model. Following this symbolic constant, enter the red, green, and blue color values for the desired ambient color. Valid color component values range from 0.0 to 1.0 inclusive. For each definition type, AMBIENT assigns the following: DEFMATERIAL - The ambient reflectance of the material. DEFLIGHT - The ambient light associated with the light source. DEFLMODEL - The ambient light present in the scene. The properties of a lighting model apply to an entire scene.
DIFFUSE DIFFUS Assigns the diffuse reflectance of a material. Following this symbolic constant, enter the red, green, and blue color component values for the desired diffuse reflectance color. Valid color component values range from 0.0 to 1.0 inclusive.
SPECULAR SPECUL Assigns the specular reflectance of a material. Following this symbolic constant, enter the red, green, and blue color component values for the desired specular reflectance color. Valid color component values range from 0.0 to 1.0 inclusive.
SHININESS SHININ Assigns the material specular scattering exponent of the material. Following this symbolic constant, enter a number between 0.0 and 128.0 inclusive. The higher the value, the smoother the surface appearance and the more focused the specular highlight. Note: The 3-D Color Graphics Processor rounds the SHININESS symbolic constant to the nearest whole integer. The POWER Gt4 and POWER Gt4x adapters accept fractional SHININESS values.
ALPHA ALPHA Assigns the transparency of the material. Following the ALPHA symbolic constant, enter a value between 0.0 and 1.0, inclusive. (Systems without alpha bitplanes cannot use this property.)
LCOLOR LCOLOR Assigns the color of a light source. Following this symbolic constant, enter the red, green, and blue color component values for the desired color of the light. Valid color component values range from 0.0 to 1.0 inclusive.
POSITION POSITI Assigns the position of a light source. Following this symbolic constant, enter the x, y, z, and w coordinates of the light source. If w is zero, the light source is infinitely distant and the x, y, and z values specify the direction of the light. Locating all light sources at infinity = 0 improves performance.
SPOTDIRECTION SPOTDI Assigns the direction (axis) in which a spotlight source emits. Following this symbolic constant, enter the x, y, and z components of the direction vector. You can specify any values for x, y, and z; the system normalizes the direction before employing it in the lighting equation. The default direction points down the negative z-axis, direction (0.0, 0.0, -1.0). The direction is transformed by the current modeling/viewing matrix when the light is bound. The direction is ignored unless the light is a spotlight. Note: This token is not supported on the 3-D Color Graphics Processor.
LOCALVIEWER LOCALV Assigns the local viewer status for a lighting model. If you want the viewer (eye position) to be local, enter 1.0 after this constant, and the lighting calculations assume that the viewer is located at (0,0,0). If you do not want the viewer to be local, then enter 0.0 after this constant, and the lighting calculations assume that the viewer is at positive infinity along the z axis. There is a performance penalty when you request a local viewer.
ATTENUATION ATTENU Assigns the light attenuation factor for the lighting model (scene). Following this symbolic constant, enter two attenuation factor values to specify: k-off - Attenuation offset factor. k-rate - Attenuation rate factor.
COLORINDEXES COLORI Specifies the material properties used when lighting in color map mode. This property is ignored while the current frame buffer is in RGB mode, as are most other material properties when the current frame buffer 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 indexes.

Example

The example C language program cylinder2.c uses the lmdef subroutine to define the properties of two materials and two lights, and to define a lighting model.

Implementation Specifics

This subroutine is part of GL in the AIXwindows Environment/6000 Version 1, Release 2 with AIXwindows/3D Feature.

On the POWERstation 730 and POWERgraphics GTO, the specular reflection exponent (as set with the SHININESS symbolic constant of the lmdef subroutine properties parameter) is truncated to the nearest power of 2 before computing lighting. The only valid values for the specular exponent are 1, 2, 4, 8, 16, 32, 64, and 128.

The POWERstation 730 and POWERgraphics GTO do not support lighting in color index mode.

Materials with different material properties on each side are supported on the POWER Gt4 class of graphics adapters. Support for two-sided lighting is accomplished with the following token:

Type DEFLMODEL
Property TWOSIDE
Function The TWOSIDE token followed by 0.0 disables two-sided lighting; followed by 1.0 enables two-sided lighting.

When two-sided lighting is disabled, the direction of the normal vector solely affects how a material is lit. When the normal vector points towards the viewer, there will typically be a positive contribution to the ambient, diffuse and specular terms of the lighting equation (based, of course, on the material properties, the light positions and colors) When the normal points away from the viewer, there will only be a contribution from the ambient term, and the surface will not appear shiny and reflective (This is because all terms in the lighting equation involving a dot product with the normal vector are clamped to zero, and are not allowed to go negative. If the normal points away from the user, such dot product terms will be clamped to zero, no mater what the light positions might be.)

When two-sided lighting is enabled, the manner in which lighting is performed depends on whether the polygon being lit is front-facing or back-facing. If the polygon is front-facing (the polygon vertices were specified in counter-clockwise order in screen coordinates), then lighting is performed as usual. If the polygon is backfacing, then the direction of the normal vector is reversed before it is used in the lighting equation (that is, it is multiplied by -1 before being used.). Thus, if two-sided lighting is enabled, and if the normal vectors were specified consistently with the handedness of the polygon, then both sides of the polygon will have diffuse and specular contributions,

If a material has been bound to the BACKMATERIAL token, then this material will be used when the back-side lighting is being computed. Otherwise, both front and back-facing polygons will be lit with the MATERIAL properties.

Two-sided lighting can only be enabled for, and affects only polygons and triangle strips. Points, lines and characters are always lit as if two-sided lighting were disabled.

The default lighting model is:
AMBIENT 0.2, 0.2, 0.2
ATTENUATION 1.0, 0.0
LOCALVIEWER 0.0
TWOSIDE 0.0
Note: To obtain the desired lighting effect with two-sided lighting, one must be careful that the direction of the normal vector is consistent with the handedness of the polygon. If the direction of the normal vector is accidentally reversed, then both sides of the polygon will appear dark.

Files

/usr/include/gl/gl.h Contains C language constant and variable type definitions for GL.
/usr/include/gl/fgl.h Contains FORTRAN constant and variable type definitions for GL.

Related Information

Setting the current color in RGB mode with the c subroutine.

Setting the current color as a single packed 32-bit integer with the cpack subroutine.

Making a new material, light, or lighting model definition active with the lmbind subroutine.

Changing the target of the color commands with the lmcolor subroutine.

Specifying a normal vector with the n3f subroutine.

Updating the current normal vector with the normal subroutine.

Setting the current color in RGB mode with the RGBcolor subroutine.

AIX Graphics Library Overview, Creating Lighting Effects, Setting Pipeline Options, and Working in Color Map and RGB Modes.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]