lmbind(3G)

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

FORTRAN 77 SPECIFICATION
     subroutine lmbind(target, index)
     integer*4 target, index

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

     index    expects the name of a material (if target is MATERI or BACKMA),
              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 MATERI or BACKMA, a light source
     definition if target is LIGHT0 through LIGHT7, or a lighting model
     definition if target is LMODEL.

     Two of these resources, MATERI 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 MATERI, and a lighting model definition other than
     model 0 is bound to LMODEL.  When either MATERI 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(DEFMATL,1,0,nullarray)
          lmdef(DEFLMOL,1,0,nullarray)
          lmbind(MATERI,1)
          lmbind(LMODEL,1)

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

          lmbind(MATERI,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 MATERI.  Likewise, when a lighting
     model with TWOSID specified is bound, MATERI is used for both front and
     back facing polygons if BACKMA is bound to material definition 0.
     However, if a material definition other than 0 is bound to BACKMA, two-
     sided lighting uses MATERI for frontfacing polygons and BACKMA for
     backfacing polygons.  In all cases points, lines, and characters are
     lighted using MATERI.

     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
     lmcolo, lmdef, mmode, n, nmode

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

     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 BACKMA.

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