Using Lights

Setting and Retrieving Light Properties

You set lighting properties in a C++ application by preparing a D3DLIGHT9 structure and then calling the IDirect3DDevice9::SetLight method. The IDirect3DDevice9::SetLight method accepts the index at which the device should place the set of light properties to its internal list of light properties, and the address of a prepared D3DLIGHT9 structure that defines those properties. You can call IDirect3DDevice9::SetLight with new information as needed to update the light's illumination properties.

The system allocates memory to accommodate a set of lighting properties each time you call the IDirect3DDevice9::SetLight method with an index that has never been assigned properties. Applications can set a number of lights, with only a subset of the assigned lights enabled at a time. Check the MaxActiveLights member of the D3DCAPS9 structure when you retrieve device capabilities to determine the maximum number of active lights supported by that device. If you no longer need a light, you can disable it or overwrite it with a new set of light properties.

The following C++ code example prepares and sets properties for a white point-light whose emitted light will not attenuate over distance.

// Assume d3dDevice is a valid pointer to an IDirect3DDevice9 interface.
D3DLIGHT9 d3dLight;
HRESULT   hr;

// Initialize the structure.
ZeroMemory(&d3dLight, sizeof(d3dLight));

// Set up a white point light.
d3dLight.Type = D3DLIGHT_POINT;
d3dLight.Diffuse.r  = 1.0f;
d3dLight.Diffuse.g  = 1.0f;
d3dLight.Diffuse.b  = 1.0f;
d3dLight.Ambient.r  = 1.0f;
d3dLight.Ambient.g  = 1.0f;
d3dLight.Ambient.b  = 1.0f;
d3dLight.Specular.r = 1.0f;
d3dLight.Specular.g = 1.0f;
d3dLight.Specular.b = 1.0f;

// Position it high in the scene and behind the user.
// Remember, these coordinates are in world space, so
// the user could be anywhere in world space, too. 
// For the purposes of this example, assume the user
// is at the origin of world space.
d3dLight.Position.x = 0.0f;
d3dLight.Position.y = 1000.0f;
d3dLight.Position.z = -100.0f;

// Don't attenuate.
d3dLight.Attenuation0 = 1.0f; 
d3dLight.Range        = 1000.0f;

// Set the property information for the first light.
hr = d3dDevice->SetLight(0, &d3dLight);
if (SUCCEEDED(hr))
	// Handle Success
else
	// Handle failure

You can update a set of light properties with another call to IDirect3DDevice9::SetLight at any time. Just specify the index of the set of light properties to update and the address of the D3DLIGHT9 structure that contains the new properties.

You can retrieve all the properties for an existing light source from C++ by calling the IDirect3DDevice9::GetLight method for the device. When calling the IDirect3DDevice9::GetLight method, pass in the first parameter the zero-based index of the light source for which the properties will be retrieved, and supply the address of a D3DLIGHT9 structure in the second parameter. The device fills the D3DLIGHT9 structure to describe the lighting properties it uses for the light source at that index.

The following code example illustrates this process.

// Assume d3dDevice is a valid pointer to an IDirect3DDevice9 interface.
HRESULT hr;
D3DLIGHT9 light;

// Get the property information for the first light.
hr = pd3dDevice->GetLight(0, &light);
if (SUCCEEDED(hr))
	// Handle Success
else
	// Handle failure

If you supply an index outside the range of the light sources assigned in the device, the IDirect3DDevice9::GetLight method fails, returning D3DERR_INVALIDCALL.

Enabling and Disabling Lights

When you assign a set of light properties for a light source in a scene, the light source can be activated by calling the IDirect3DDevice9::LightEnable method for the device. New light sources are disabled by default. The IDirect3DDevice9::LightEnable method accepts two parameters. Set the first parameter to the zero-based index of the light source to be affected by the method, and set the second parameter to TRUE to enable the light or FALSE to disable it.

The following code example illustrates the use of this method by enabling the first light source in the device's list of light source properties.

// Assume d3dDevice is a valid pointer to an IDirect3DDevice9 interface.
HRESULT hr;

hr = pd3dDevice->LightEnable(0, TRUE);
if (SUCCEEDED(hr))
	// Handle Success
else
	// Handle failure

Check the MaxActiveLights member of the D3DCAPS9 structure when you retrieve device capabilities to determine the maximum number of active lights supported by that device.

If you enable or disable a light that has no properties that are set with IDirect3DDevice9::SetLight, the IDirect3DDevice9::LightEnable method creates a light source with the properties listed in following table and enables or disables it.