D3DLIGHT2

The D3DLIGHT2 structure defines the light type in calls to methods such as IDirect3DLight::SetLight and IDirect3DLight::GetLight.

For DirectX 5.0 and newer, this structure supersedes the D3DLIGHT structure. The D3DLIGHT2 structure is identical to D3DLIGHT except for the addition of the dwFlags member. In addition, the dvAttenuation members are interpreted differently in D3DLIGHT2 than they were for D3DLIGHT.

typedef struct _D3DLIGHT2 { 
    DWORD         dwSize; 
    D3DLIGHTTYPE  dltType; 
    D3DCOLORVALUE dcvColor; 
    D3DVECTOR     dvPosition; 
    D3DVECTOR     dvDirection; 
    D3DVALUE      dvRange; 
    D3DVALUE      dvFalloff; 
    D3DVALUE      dvAttenuation0; 
    D3DVALUE      dvAttenuation1; 
    D3DVALUE      dvAttenuation2; 
    D3DVALUE      dvTheta; 
    D3DVALUE      dvPhi; 
    DWORD         dwFlags; 
} D3DLIGHT2, *LPD3DLIGHT2; 
 

Members

dwSize

Size, in bytes, of this structure. You must specify a value for this member. Direct3D uses the specified size to determine whether this is a D3DLIGHT or a D3DLIGHT2 structure.

dltType

Type of the light source. This value is one of the members of the D3DLIGHTTYPE enumerated type.

dcvColor

Color of the light. This member is a D3DCOLORVALUE structure. In ramp mode, the color is converted to a gray scale.

dvPosition

Position of the light in world space. This member has no meaning for directional lights and is ignored in that case.

dvDirection

Direction the light is pointing in world space. This member only has meaning for directional and spotlights. This vector need not be normalized but it should have a nonzero length.

dvRange

Distance beyond which the light has no effect. The maximum allowable value for this member is D3DLIGHT_RANGE_MAX, which is defined as the square root of FLT_MAX. This member does not affect directional lights.

dvFalloff

Decrease in illumination between a spotlight's inner cone (the angle specified by the dvTheta member) and the outer edge of the outer cone (the angle specified by the dvPhi member). This feature was implemented for DirectX 5.0. For details on how dvFalloff values affect a spotlight, see Spotlight Falloff Model.

The effect of falloff on the lighting is subtle. Furthermore, a small performance penalty is incurred by shaping the falloff curve. For these reasons, most developers set this value to 1.0.

dvAttenuation0 through dvAttenuation2

Values specifying how a light's intensity changes over distance. (Attenuation does not affect directional lights.) In the D3DLIGHT2 structure these values are interpreted differently than they were for the D3DLIGHT structure. For information about how these attenuation values affect lighting in a scene, see Light Attenuation Over Distance.

dvTheta

Angle, in radians, of the spotlight's inner cone—that is, the fully illuminated spotlight cone. This value must be between 0 and the value specified by the dvPhi member.

dvPhi

Angle, in radians, defining the outer edge of the spotlight's outer cone. Points outside this cone are not lit by the spotlight. This value must be between 0 and pi.

dwFlags

A combination of the following performance-related flags. This member is new for DirectX 5.0.

D3DLIGHT_ACTIVE

Enables the light. This flag must be set to enable the light; if it is not set, the light is ignored.

D3DLIGHT_NO_SPECULAR

Turns off specular highlights for the light.

Remarks

In the D3DLIGHT structure, the affects of the attenuation settings were difficult to predict; developers were encouraged to experiment with the settings until they achieved the desired result. For D3DLIGHT2, it is much easier to work with lighting attenuation.

When you use this structure with the IDirect3DLight::GetLight or IDirect3DLight::SetLight, cast the pointer to this structure to the LPD3DLIGHT data type.

For more information about lights, see Lights and IDirect3DLight.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in d3dtypes.h.

See Also

D3DLIGHTTYPE