lmbind(3G)

NAME
     lmbind - selects a new material, light source, or lighting model

C SPECIFICATION
     void lmbind(target, index)
     short target, index;

PARAMETERS
     target  expects one of these symbolic constants:  MATERIAL, BACKMATERIAL,
             LIGHT0, LIGHT1, LIGHT2, LIGHT3, LIGHT4, LIGHT5, LIGHT6, LIGHT7,
             or LMODEL.

     index    expects the name of a material (if target is MATERIAL or
              BACKMATERIAL), a light source (if target is one of LIGHT0
              through LIGHT7), or a lighting model (if target is LMODEL).
              Name is the index passed to lmdef when the material, light
              source, or lighting model was defined.

DESCRIPTION
     Lighting operation is controlled by eleven lighting resources, each of
     which has a symbolic constant as a name.  lmbind binds a material, light
     source, or lighting model definition to one of these eleven lighting
     resources.  Its first argument, target, takes the symbolic name of a
     lighting resource.  Its second argument, index, takes the name of a
     lighting definition to be bound to that resource.  index specifies a
     material definition if target is MATERIAL or BACKMATERIAL, a light source
     definition if target is LIGHT0 through LIGHT7, or a lighting model
     definition if target is LMODEL.

     Two of these resources, MATERIAL and LMODEL, are special, in that they
     together determine whether lighting calculations are made or not.
     Lighting calculations are enabled when a material definition other than
     material 0 is bound to MATERIAL, and a lighting model definition other
     than model 0 is bound to LMODEL.  When either MATERIAL is bound to
     material definition 0, or LMODEL is bound to lighting model definition 0,
     all lighting calculations are disabled.

     Thus, for example, lighting is defined and enabled in the most primitive
     way by the following code sequence:

          lmdef(DEFMATERIAL,1,0,nullarray);
          lmdef(DEFLMODEL,1,0,nullarray);
          lmbind(MATERIAL,1);
          lmbind(LMODEL,1);

     This primitive lighting model is disabled efficiently by simple binding
     material 0 to MATERIAL.

          lmbind(MATERIAL,0);
     A lighting definition is unbound from a lighting resource only when
     another definition is bound to that resource.  Changes made to a lighting
     definition while it is bound are effective immediately.  By default all
     eleven lighting resources are bound to definition 0.  If lmbind is passed
     a name that is not defined, definition 0 is bound to the specified
     lighting resource.

     The eight light sources, named LIGHT0 through LIGHT7, are enabled when
     bound to a light source definition other than 0.  Light source positions
     are transformed by the current ModelView matrix when the source is bound.
     The object-coordinate position of the light source is maintained in the
     definition so that subsequent bindings are transformed from it, rather
     than from the previously transformed position.  A light source definition
     cannot be bound to more than one lighting resource in a single window.

     The default lighting model uses only a single material, namely the
     material definition that is bound to MATERIAL.  Likewise, when a lighting
     model with TWOSIDE specified is bound, MATERIAL is used for both front
     and back facing polygons if BACKMATERIAL is bound to material definition
     0.  However, if a material definition other than 0 is bound to
     BACKMATERIAL, two-sided lighting uses MATERIAL for frontfacing polygons
     and BACKMATERIAL for backfacing polygons.  In all cases points, lines,
     and characters are lighted using MATERIAL.

     Lighting models use only material and light properties that are
     appropriate to them.  Other properties, such as color map mode properties
     while the current framebuffer is in RGB mode, are ignored.

SEE ALSO
     lmcolor, lmdef, mmode, n, nmode

NOTES
     Lighting requires that the matrix mode be multi-matrix.  It does not
     operate correctly while mmode is MSINGLE.

     Indigo ELAN, XS, XS-24 and XZ family requires a gconfig call before
     lmbind is called, this is especially true to render in RGBmode.  IRIS-4D
     G, GT, and GTX models, and the Personal Iris, do not support two-sided
     lighting, and therefore do not support light resource BACKMATERIAL.

     It is a common error to bind a light source when an inappropriate
     ModelView matrix is on the stack.  Be careful!