lmdef(3G)
lmdef - defines or modifies a material, light source, or lighting model
As shipped in IRIX 6.5. First release of IRIX 6.5.
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 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.