D3DLIGHT.EXE Previews Direct3D Retained Mode Lighting Effects

ID: Q159999

The information in this article applies to:

Microsoft DirectX Software Development Kit, version 2.0, used with:
- Microsoft Windows 95

SUMMARY

The DirectX SDK provides sophisticated lighting effects of scenes rendered by the Direct3D component. Although the documentation is specific about the API, it can be difficult to conceptualize and visualize the potential of these effects. This sample provides a visual interaction with the Direct3D lighting module and offers sample code using the Retained Mode interfaces to manipulate the lighting module.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

~ D3DLIGHT.EXE

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

The Lighting sample requires the DirectX SDK version 2.0 or later and a 32-bit C compiler. Once the files have been extracted from the archive, follow the steps given below to use the sample.

Sample Code

Ensure that the DirectX SDK is properly installed by building one of the sample programs provided with the SDK.

Compile the project using the makefile provided.

Run the resulting executable.

Alter the lighting parameters in the modeless dialog box and observe their effects on the sample scene in the applications Window.

Understanding the Sample Application

The Lighting application contains a child Window within the application[ASCII 146]s main Window in which Direct3D renders a scene of seven blue spheres. These spheres are lit by an ambient light source and by one point light source. Above the child window is a graph of the light and fog intensities produced by the current lighting parameters. The application defaults to lighting parameters that produce no special effects.

The Lighting sample displays a modeless dialog box from which you can modify the current lighting parameters. This dialog box appears directly over the intensity graph and may need to be moved to view the full graph. The controls of this dialog box provide access to the following lighting parameters:

LIGHT ATTENUATION: Attenuation is an intensity function that characterizes the strength of a light source as a function of distance from the light. In the dialog, the edit controls for Light Attenuation 0, 1, and 2 correspond directly to the constants in the quadratic attenuation equation given in the Lighting Module[ASCII 146]s overview documentation for Direct3D. Note that the attenuation factor given by this equation is applied inversely to the light's initial intensity to give the final attenuated intensity at a distance d.

LIGHT RANGE: The Light Range edit control provides access to the effective range parameter of a light source. The range value defines the distance beyond which a light source does not illuminate an object. Unfortunately, due to bugs in DirectX versions 2.0 and 3.0, this value has no effect.

RAMP MODE: The Ramp Mode check box toggles the color model that the Lighting sample uses to render the scene. When checked, the sample is using the Ramp or Mono color model. When cleared, the sample uses the RGB color model. For a description of the color model differences, refer to the online documents for Direct3D.

FOG: The Fog check box toggles the use of Fog in the scene. Note that Fog is documented as not working properly in Ramp Mode unless the scene is unlit and the Fog is black. This sample uses a scene that is always lit so turning Fog on when in the Ramp mode does not work properly.

FOG START: The value in the Fog Start edit control defines the point at which the fog will begin to have an effect on the scene. The opaque effect of fog on the rendered scene will increase linearly from this point to the end of the fog.

FOG END: The value in the Fog End edit control defines the end point of the fog in the scene.

FOG DENSITY: Fog density is used to determine the exponential effect of fog in a scene when exponential fog is used. Note that this value has no effect on fog since linear Fog is the only supported fog type in Direct3D included with DirectX 3.0 or earlier versions.

As these lighting parameters are altered, you can observe their effects on the rendered scene in the Window. Qualitative observations can be made on the rendered scene while quantitative observations can be compared in the graphs above the scene.

Two graphs may appear. The first and always-present graph will be the intensity of the directional light source as expressed relative to the distance from the source. This can be compared to the positions of each of the seven spheres. The second graph is of Fog intensity that is overlaid on the first graph when Fog is enabled. It, too, may be compared on this graph to the relative positions of each of the seven spheres.

Understanding the Sample Code

Most of the interesting action for this sample occurs in the UpdateParameters() function. This function retrieves the values from the controls of the modeless dialog box and calls various Direct3D interface functions to make these changes in the rendering of the scene. All of the functions responsible for the rendering and demonstration of Direct3D[ASCII 146]s lighting effects are located in the Scene.C file. Light.C contains the Windows functions to create an application while Plot.C contains the functions used to create the graph.

In addition to lighting effects, this sample also demonstrates the following general Direct3D programming techniques:

How to display a Direct3D Scene in only part of a Window[ASCII 146]s client area.

How to create and call the methods of the Direct3D COM interfaces in C.

The parameters exposed through the modeless dialog are characteristics of three different Direct3D objects created and used by the sample program:

Lighting attenuation and range are set by the SetConstantAttenuation(), SetLinearAttenuation(), SetQuadraticAttenuation(), and SetRange() functions. All of these functions are methods of the Direct3DRMLight object. Direct3D light objects are contained in Direct3D frame objects that make up scenes. For this reason, the sample maintains a global pointer to the light object so you can make adjustments to it directly.

The Fog settings are changed with calls to the SetSceneFogParams() and SetSceneFogEnable() functions. These functions are methods of the Direct3DRMFrame object that defines the global scene for rendering. This Scene and all of the objects it contains, including the aforementioned light, are created in the sample[ASCII 146]s CreateScene() function.

The color model used to render the scene in the sample is a characteristic of the Direct3DRMDevice object that is used by the Direct3DRMViewport object that actually performs the rendering. Because of this dependency, both the Device and Viewport objects have to be destroyed and recreated each time the sample is switched between the RGB color model and the Ramp color model. The UpdateParameters() function merely sets a global variable that defines the color model. Later, this change is detected and triggers the rebuilding of the Device and Viewport objects in the modeless dialog[ASCII 146]s procedure. These actions are performed in the CreateDevice(), DestroyDevice(), CreateView(), and DestroyView() functions, respectively.

Additional query words: Retained Mode


Keywords          : kbfile kbsample kbSDKWin32 kbWinOS95 kbDirectX200 
Version           : WINDOWS:2.0,95
Platform          : WINDOWS 
Issue type        : kbinfo

Last Reviewed: June 17, 1999