Light Info

The light info global returns functions for getting light-specific information about any of the lights in a scene. Use the Item Info global to get the light list and for generic item information. The information returned by these functions is read-only, but you can use commands to set many of the parameters.

Global Call

   LWLightInfo *lightinfo;
   lightinfo = global( LWLIGHTINFO_GLOBAL, GFUSE_TRANSIENT );

   typedef struct st_LWLightInfo {
      void         (*ambient)     (LWTime, LWDVector color);
      int          (*type)        (LWItemID);
      void         (*color)       (LWItemID, LWTime, LWDVector color);
      int          (*shadowType)  (LWItemID);
      void         (*coneAngles)  (LWItemID, LWTime, double *radius,
                                     double *edge);
      unsigned int (*flags)       (LWItemID);
      double       (*range)       (LWItemID, LWTime);
      int          (*falloff)     (LWItemID);
      LWImageID    (*projImage)   (LWItemID);
      int          (*shadMapSize) (LWItemID);
      double       (*shadMapAngle)(LWItemID, LWTime);
      double       (*shadMapFuzz) (LWItemID, LWTime);
      int          (*quality)     (LWItemID, LWTime);
      void         (*rawColor)    (LWItemID, LWTime, LWDVector color);
      double       (*intensity)   (LWItemID, LWTime);
      void         (*shadowColor)  (LWItemID, LWTime, LWDVector color);
      double       (*ambientIntensity)  (LWTime);
      void         (*ambientRaw)     (LWTime, LWDVector color);

   } LWLightInfo;

ambient( time, color )

Returns the color of the global ambient light for the scene at the given time. The RGB levels include the effect of the user's intensity setting for the ambient light.

lighttype = type( light )

Returns the type of the light as one of the following values. 

LWLIGHT_DISTANT
LWLIGHT_POINT
LWLIGHT_SPOT
LWLIGHT_LINEAR
LWLIGHT_AREA

color( light, time, rgb )

Sets the rgb argument to the color of the light (with intensity factored in) at the given time. Use the rawColor and intensity functions for separate access to these settings.

shadowtype = shadowType( light )

Returns the shadow type for the light as one of the following values. 

LWLSHAD_OFF
LWLSHAD_RAYTRACE
LWLSHAD_MAP

coneAngles( light, time, radius, edge )

Returns the cone angles for spotlights. radius receives an angle that is half the total light cone angle, and edge receives the angular width of the soft edge. Both angles are in radians.

settings = flags( light )

Returns flag bits for settings related to the light. 

LWLFL_LIMITED_RANGE
LWLFL_NO_DIFFUSE
LWLFL_NO_SPECULAR
LWLFL_NO_CAUSTICS
LWLFL_LENS_FLARE
LWLFL_VOLUMETRIC
LWLFL_NO_OPENGL
LWLFL_FIT_CONE
LWLFL_CACHE_SHAD_MAP

The FIT_CONE flag indicates that the shadow map angle is set to the light's spotlight cone angle. 

dist = range( light, time )

Returns the range or nominal distance for the light. The interpretation of this value depends on the falloff type. If falloff is linear, the value is the distance at which the intensity of the light falls to 0. For inverse distance falloff types, the value is the distance at which the intensity equals the user's intensity setting for the light. When there's no falloff (the falloff function returns LWLFALL_OFF, or the LWLFL_LIMITED_RANGE flag bit is clear), the return value is undefined.

falloff_type = falloff( light )

Returns the falloff type. Falloff scales the intensity of a light as a function of d (distance from the light) and r (the value returned by the range function).

LWLFALL_OFF	1 (no falloff)
LWLFALL_LINEAR	1 - d / r (or 0 when d > r)
LWFALL_INV_DIST	r / d
LWFALL_INV_DIST_2	(r / d)2

image = projImage( light )

Returns the image ID of the projection image. Use the Image List global to get information about the image.

size = shadMapSize( light )

The size of the shadow map. Shadow maps are square arrays of pixels, so the amount of memory used by a shadow map is proportional to the square of the size.

angle = shadMapAngle( light, time )

The angle subtended by the shadow map, in radians.

fuzziness = shadMapFuzz( light, time )

The amount of fuzziness at the edges of shadows in the shadow map.

index = quality( light )
index = quality( light, time ) (rev.4+)

The quality level of an extended (linear or area) light source, proportional to the number of sample points on the light.

rawColor( light, time, rgb )
level = intensity( light, time )

These return the separate components of the light color returned by the color function.

shadowColor( light, time, rgb ) (LW7.5+)

Returns the shadow color for the light in rgb.

intensity = ambientIntensity( time ) (LW9.6+)

Returns the ambient intensity at time

intensity = ambientRaw( time ) (LW9.6+)

Returns the raw ambient value at time

Global Call

   LWLightEvaluationFuncs *lightfuncs;
   lightfuncs = global( LWLIGHTEVALUATIONFUNCS_GLOBAL, GFUSE_TRANSIENT );

   typedef struct st_LWLightEvaluationFuncs {
      LWLightEvaluatorID (*create) (LWItemID light);
      void    (*destroy)    (LWLightEvaluatorID);
      unsigned int (*flags) (LWLightEvaluatorID);
      LWError (*init)       (LWLightEvaluatorID, int mode);
      void    (*cleanUp)    (LWLightEvaluatorID);
      LWError (*newTime)    (LWLightEvaluatorID, LWFrame frame, LWTime time);
      LWError (*newFrame)   (LWLightEvaluatorID, const LWFrameInfo* frameinfo,
                             unsigned int* maxilluminations,
                             const LWLightAccess* lightaccess);
      int     (*evaluate)   (LWLightEvaluatorID, const LWDVector spot,
                             double fractime, LWIllumination illumination[],
                             const LWLightAccess* lightaccess);
      unsigned int (*getPhotons) (LWLightEvaluatorID, unsigned int maxphotons,
                                  LWPhoton photons[],
                                  const LWLightAccess* lightaccess);
      unsigned int (*getRayIlluminations) (LWLightEvaluatorID,
                                           LWDVector raystart, LWDVector raydir,
                                           double farclip,
                                           unsigned int maxrayilluminations,
                                           LWRayIllumination rayilluminations[],
                                           const LWLightAccess* lightaccess);
   } LWLightEvaluationFuncs;

Example

This code fragment collects information about the first light.

   #include <lwserver.h>
   #include <lwrender.h>

   LWItemInfo *iteminfo;
   LWLightInfo *ltinfo;
   LWItemID id;
   LWTime t = 3.0;          /* seconds */
   LWDVector color;
   double range, radius, edge;
   int lighttype, shadowtype;
   unsigned int flags;

   iteminfo = global( LWITEMINFO_GLOBAL, GFUSE_TRANSIENT );
   ltinfo   = global( LWLIGHTINFO_GLOBAL, GFUSE_TRANSIENT );

   if ( iteminfo && ltinfo ) {
      id = iteminfo->first( LWI_LIGHT, NULL );
      lighttype  = ltinfo->type( id );
      shadowtype = ltinfo->shadowType( id );
      flags      = ltinfo->flags( id );
      ltinfo->color( id, t, color );

      if ( type == LWLIGHT_SPOT )
         ltinfo->coneAngles( id, &radius, &edge );
      if ( flags & LWLFL_LIMITED_RANGE )
         range = ltinfo->range( id );
   }