Setting Light Properties

[C++]

You set lighting properties in a C++ application by preparing a D3DLIGHT7 structure and then calling the IDirect3DDevice7::SetLight method. The 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 D3DLIGHT7 structure that defines those properties. You can call 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 SetLight method with an index that has never been assigned properties. Applications can set a very large number of lights, with only a subset of the assigned lights enabled at a time. Check the dwMaxActiveLights member of the D3DDEVICEDESC7 structure when you retrieve device capabilities to determine the maximum number of active lights supported by that device. If you do not need to use a particular light anymore, you can disable it, or overwrite it with a new set of light properties.

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

    /*
     * For the purposes of this example, the g_lpd3dDev variable
     * is a valid pointer to an IDirect3DDevice7 interface.
     */
    D3DLIGHT7 d3dLight;
    HRESULT   hr;
 
    // Initialize the structure.
    ZeroMemory(&d3dLight, sizeof(D3DLIGHT7));
 
    // Set up for a white point light.
    d3dLight.dltType = D3DLIGHT_POINT;
    d3dLight.dcvDiffuse.r = 1.0f;
    d3dLight.dcvDiffuse.g = 1.0f;
    d3dLight.dcvDiffuse.b = 1.0f;
    d3dLight.dcvAmbient.r = 1.0f;
    d3dLight.dcvAmbient.g = 1.0f;
    d3dLight.dcvAmbient.b = 1.0f;
    d3dLight.dcvSpecular.r = 1.0f;
    d3dLight.dcvSpecular.g = 1.0f;
    d3dLight.dcvSpecular.b = 1.0f;
 
    // Position it high in the scene, and behind the viewer.
    // (Remember, these coordinates are in world space, so
    //  the "viewer" could be anywhere in world space, too. 
    //  For the purposes of this example, assume the viewer
    //  is at the origin of world space.)
    d3dLight.dvPosition.x = 0.0f;
    d3dLight.dvPosition.y = 1000.0f;
    d3dLight.dvPosition.z = -100.0f;
 
    // Don't attenuate.
    d3dLight.dvAttenuation0 = 1.0f; 
    d3dLight.dvRange = D3DLIGHT_RANGE_MAX;

    // Set the property information for the first light.
    hr = g_lpd3dDev->SetLight(0, d3dLight);
    if (FAILED(hr))
    {
// Code to handle the error goes here.
    }

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

Note Assigning a set of light properties to the device does not enable the light source whose properties are being added. Enable a light source by calling the IDirect3DDevice7::LightEnable method for the device.

[Visual Basic]

Your Visual Basic application sets lighting properties by preparing a D3DLIGHT7 type and then calling the Direct3DDevice7.SetLight method. The 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 D3DLIGHT7 type that defines those properties. You can call 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 SetLight method with an index that has never been assigned properties. Applications can set a very large number of lights, with only a subset of the assigned lights enabled at a time. Check the lMaxActiveLights member of the D3DDEVICEDESC7 type when you retrieve device capabilities to determine the maximum number of active lights supported by that device. If you do not need to use a particular light anymore, you can disable it, or overwrite it with a new set of light properties.

The following code, written in Visual Basic, prepares and sets properties for a white point-light whose emitted light will not attenuate over distance.

'
' For this example, the d3dDevice variable contains a valid reference
' to a Direct3DDevice7 object.
'
Dim LightDesc As D3DLIGHT7
Dim c As D3DCOLORVALUE
Dim vPos As D3DVECTOR

' Use the same color settings for all emitted light color.
With c
    .r = 1#: .g = 1#: .b = 1#
    .a = 1# ' The alpha component isn't used for lights.
End With

With vPos
    .x = 0: .y = 1000: .z = -100
End With

With LightDesc
    .dltType = D3DLIGHT_POINT
    .position = vPos
    .Ambient = c: .diffuse = c: .specular = c
    .attenuation0 = 1# ' Don't attenuate the light
End With

d3dDevice.SetLight 0, LightDesc

Note Assigning a set of light properties to the device does not enable the light source whose properties are being added. Enable a light source by calling the Direct3DDevice7.LightEnable method for the device.