Working with Lights

3DS Max Plug-In SDK

Working with Lights

See Also: Class LightObject, Class GenLight, Class Light, Class DefaultLight, Structure LightState, Class LightDesc, Class LightRayTraversal, Class ObjLightDesc, Class ShadeContext.

Overview

This topic provides information on working with lights. Covered are the main classes used when dealing with lights and a description of how these relate to one another. Also discussed are the types of lights, and how the parameters that define their characteristics may be retrieve and assigned.

There are several tasks lights are responsible for accomplishing. One is to provide an interface so the user can adjust their properties. Another is to provide access to these same parameters so other plug-ins (utilities, exporters, renderers, etc.) can get and set them. Another one is the actual llumination objects in the scene. Also, certain lights need to work with the 3ds max atmosphere system (such as fog and volume lighting).

Overview of the Principal Classes

The following classes are the main ones used when dealing with lights in the SDK.

Class LightObject

This is a base class for plug-in lights. It has a method used to retrieve the light's properties at a certain time, a method to create an ObjLightDesc object (described below). It also has methods that allow the many properties of the light to be read and altered.

Class GenLight

This is also a possible candidate for plug-in lights to sub-class from. This class, sub-classed from LightObject, provides a set of additional methods (for example access to the controllers handling the animation of the light's properties).

Class Light

This class describes the properties of the lights used in the interactive renderer. See Light methods in Class GraphicsWindow for methods which use this class.

Class DefaultLight

An array of these objects is passed in the Open() method of a renderer plug-in. This class contains the transformation matrix of the light and a LightState object (described below) that describes the characteristics of the light.

Structure LightState

This structure describes the properties of a light. When the LightObject method EvalLightState() is called, LightState is the structure that is updated. This is used, for example, by many of the file format export plug-ins to grab data about the lights they are exporting.

Class LightDesc

This class has a single method Illuminate() used to determine the color and direction of the light striking a point. It has two public data members that indicate if the diffuse and/or specular color of objects should be affected by the light.

Class ObjLightDesc

This class is sub-classed from LightDesc (described above). There is an instance of this class for every instance of a light in the scene. The renderer asks each light in the scene to create one of these objects by calling LightObject::CreateLightDesc() and passing it the light node. This class has data members that provide information such as a pointer to the node for the light, a LightState object, various transformation matrices that provide conversions between the light's space and world and camera space. It has a method to retrive the lights exclusion list, and a method to update the light's data members in this class once per render. It also has a method used in computing volume lighting effects, TraverseVolume().

Accessing Light Parameters

There are several approaches developers may use to access the parameters that define the properties of a light. One way is to call the EvalLightState() method of the light. This method updates the LightState structure passed to it. This structure contains basic information about the light such as its type, color, attenuation ranges, etc.). The structure is valid for a single point in time for animated lights.

Another approach is to call the individual Get/Set methods of the light directly. Since lights are sub-classed from LightObject or GenLight, the methods of these classes may be called to get and set additional properties. This provides not only read access but also the ability to change the lights properties. If animate mode is set to on, a developer may animate the lights in this way.

Finally, developers may access the controllers that handle the animation of lights. This can be used to determine exactly what type of interpolation is being done by the lights when they are animated (by looking at the Controller's Class_ID). Also, the GetValue() and SetValue() method of the controller may be used to access the lights properties.

Global Light Scaling and Tinting

In 3ds max 2.0 a new area, called 'Global Lighting' has been added to the Environment dialog. It contains two new controls that globally affect all lights in the scene, except the Ambient light. The two new controls are as follows:

A Level spinner control: The value in this spinner acts as a multiplier to all lights in the scene, except ambient light. Thus, a level of 1 (default) preserves the normal light settings, while higher numbers raise the lighting, and lower numbers reduce the lighting.

A Tint color swatch: The user may use this for to tint all lights in the scene by that color.

Both of these new controls can be animated. Developers that retrieve light color values from the Get/Set methods of the lights themselves do not have this global lighting factor applied. There are several methods of the Interface class that provide access to these properties. See Interface -- Environment Access.