2.00
WINDOWS
kbprg kbfile kbhowto
The information in this article applies to:
- Microsoft DirectX 2 Software Development Kit for Windows 95,
version 2.0 on the following platforms: NT, Win95
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.
Download D3DLIGHT.EXE, a self-extracting file, from the following services:
- Microsoft's World Wide Web site on the Internet
On the www.microsoft.com home page, click the Support icon
Click Knowledge Base, and select the product
Enter kbfile D3DLIGHT.EXE (size: 84998 bytes)
, and click GO!
Open the article, and click the button to download the file
- Internet (anonymous FTP)
ftp ftp.microsoft.com
Change to the Softlib/Mslfiles folder
Get D3DLIGHT.EXE (size: 84998 bytes)
- Microsoft Download Service (MSDL)
Dial (206) 936-6735 to connect to MSDL
Download D3DLIGHT.EXE (size: 84998 bytes)
For additional information about downloading, please see the following
article in the Microsoft Knowledge Base:
ARTICLE-ID: Q119591
TITLE : How to Obtain Microsoft Support Files from Online
Services
MORE INFORMATION
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 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’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 from which you can modify
the current lighting parameters. This dialog appears directly over the
intensity graph and may need to be moved to view the full graph. The
controls of this dialog 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’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 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’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’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’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’s procedure. These actions are
performed in the CreateDevice(), DestroyDevice(), CreateView(), and
DestroyView() functions, respectively.