## IDirect3DRMLight

Applications use the methods of the IDirect3DRMLight interface to interact with light objects. This section is a reference to the methods of this interface. For a conceptual overview, see IDirect3DRMLight and IDirect3DRMLightArray Interfaces.

The methods of the IDirect3DRMLight interface can be organized into the following groups:

Attenuation | GetConstantAttenuation
| GetLinearAttenuation
| GetQuadraticAttenuation
| SetConstantAttenuation
| SetLinearAttenuation
| SetQuadraticAttenuation
Color | GetColor
| SetColor
| SetColorRGB
Enable frames | GetEnableFrame
| SetEnableFrame
Light types | GetType
| SetType
Range | GetRange
| SetRange
Spotlight options | GetPenumbra
| GetUmbra
| SetPenumbra
| SetUmbra

The IDirect3DRMLight interface, like all Component Object Model (COM) interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

AddRef
QueryInterface
Release

In addition, the IDirect3DRMLight interface inherits the following methods from the IDirect3DRMObject interface:

AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

The Direct3DRMLight object is obtained by using the IDirect3DRM::CreateLight or IDirect3DRM::CreateLightRGB method.

###

IDirect3DRMLight::GetColor

IDirect3DRMLight

Retrieves the color of the current Direct3DRMLight object.

D3DCOLOR GetColor( );

##### Return Values

Returns the color.

##### See Also

IDirect3DRMLight::SetColor

###

IDirect3DRMLight::GetConstantAttenuation

IDirect3DRMLight

Retrieves the constant attenuation factor for the Direct3DRMLight object.

D3DVALUE GetConstantAttenuation( );

##### Return Values

Returns the constant attenuation value.

##### Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on the distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

##### See Also

IDirect3DRMLight::SetConstantAttenuation

###

IDirect3DRMLight::GetEnableFrame

IDirect3DRMLight

Retrieves the enable frame for a light.

HRESULT GetEnableFrame(
LPDIRECT3DRMFRAME * lplpEnableFrame
);

##### Parameters

lplpEnableFrame
  Address of a pointer that will contain the enable frame for the current Direct3DRMFrame object.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### See Also

IDirect3DRMLight::SetEnableFrame

###

IDirect3DRMLight::GetLinearAttenuation

IDirect3DRMLight

Retrieves the linear attenuation factor for a light.

D3DVALUE GetLinearAttenuation( );

##### Return Values

Returns the linear attenuation value.

##### Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

##### See Also

IDirect3DRMLight::SetLinearAttenuation

###

IDirect3DRMLight::GetPenumbra

IDirect3DRMLight

Retrieves the penumbra angle of a spotlight.

D3DVALUE GetPenumbra( );

##### Return Values

Returns the penumbra value.

##### See Also

IDirect3DRMLight::SetPenumbra

###

IDirect3DRMLight::GetQuadraticAttenuation

IDirect3DRMLight

Retrieves the quadratic attenuation factor for a light.

D3DVALUE GetQuadraticAttenuation( );

##### Return Values

Returns the quadratic attenuation value.

##### Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

##### See Also

IDirect3DRMLight::SetQuadraticAttenuation

###

IDirect3DRMLight::GetRange

IDirect3DRMLight

Retrieves the range of the current Direct3DRMLight object.

D3DVALUE GetRange( );

##### Return Values

Returns a value describing the range.

##### See Also

IDirect3DRMLight::SetRange

###

IDirect3DRMLight::GetType

IDirect3DRMLight

Retrieves the type of a given light.

D3DRMLIGHTTYPE GetType( );

##### Return Values

Returns one of the members of the D3DRMLIGHTTYPE enumerated type.

##### See Also

IDirect3DRMLight::SetType

###

IDirect3DRMLight::GetUmbra

IDirect3DRMLight

Retrieves the umbra angle of the Direct3DRMLight object.

D3DVALUE GetUmbra( );

##### Return Values

Returns the umbra angle.

##### See Also

IDirect3DRMLight::SetUmbra

###

IDirect3DRMLight::SetColor

IDirect3DRMLight

Sets the color of the given light.

HRESULT SetColor(
D3DCOLOR rcColor
);

##### Parameters

rcColor
  New color for the light.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

This method is also used to add a color key to a Direct3DRMLightInterpolator object.

##### See Also

IDirect3DRMLight::GetColor

###

IDirect3DRMLight::SetColorRGB

IDirect3DRMLight

Sets the color of the given light.

HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);

##### Parameters

rvRed, rvGreen, and rvBlue
  New color for the light.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

This method is also used to add an RGB color key to a Direct3DRMLightInterpolator object.

###

IDirect3DRMLight::SetConstantAttenuation

IDirect3DRMLight

Sets the constant attenuation factor for a light.

HRESULT SetConstantAttenuation(
D3DVALUE rvAtt
);

##### Parameters

rvAtt
  New constant attenuation factor.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on the distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

This method is also used to add a constant attenuation key to a Direct3DRMLightInterpolator object.

##### See Also

IDirect3DRMLight::GetConstantAttenuation

###

IDirect3DRMLight::SetEnableFrame

IDirect3DRMLight

Sets the enable frame for a light.

HRESULT SetEnableFrame(
LPDIRECT3DRMFRAME lpEnableFrame
);

##### Parameters

lpEnableFrame
  Address of the light's enable frame. Child frames of this frame are also enabled for this light source.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### See Also

IDirect3DRMLight::GetEnableFrame

###

IDirect3DRMLight::SetLinearAttenuation

IDirect3DRMLight

Sets the linear attenuation factor for a light.

HRESULT SetLinearAttenuation(
D3DVALUE rvAtt
);

##### Parameters

rvAtt
  New linear attenuation factor.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

This method is also used to add a linear attenuation key to a Direct3DRMLightInterpolator object.

##### See Also

IDirect3DRMLight::GetLinearAttenuation

###

IDirect3DRMLight::SetPenumbra

IDirect3DRMLight

Sets the angle of the penumbra cone.

HRESULT SetPenumbra(
D3DVALUE rvAngle
);

##### Parameters

rvAngle
  New penumbra angle. This angle must be greater than or equal to the angle of the umbra. If you set the penumbra angle to less than the umbra angle, the umbra angle will be set equal to the penumbra angle. The default value is 0.5 radians.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

This method is also used to add a penumbra angle key to a Direct3DRMLightInterpolator object.

##### See Also

IDirect3DRMLight::GetPenumbra

###

IDirect3DRMLight::SetQuadraticAttenuation

IDirect3DRMLight

Sets the quadratic attenuation factor for a light.

HRESULT SetQuadraticAttenuation(
D3DVALUE rvAtt
);

##### Parameters

rvAtt
  New quadratic attenuation factor.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

Lights that have a location (those that are not infinitely far away) can have attenuation factors to calculate the attenuation of the light based on distance from the light.

The formula for the total attenuation factor is:

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

The total attenuation factor cannot be greater than 1. When attenuation factors are not provided, the default values are 1.0 for the constant attenuation factor, 0.0 for the linear attenuation factor, and 0.0 for the quadratic attenuation factor.

This method is also used to add a quadratic attenuation key to a Direct3DRMLightInterpolator object.

##### See Also

IDirect3DRMLight::GetQuadraticAttenuation

###

IDirect3DRMLight::SetRange

IDirect3DRMLight

Sets the range of a spotlight. The light affects objects that are within the range only.

HRESULT SetRange(
D3DVALUE rvRange
);

##### Parameters

rvRange
  New range. The default value is 256 modeling-space units.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

The range property is for spotlights only. This method is also used to add a range key to a Direct3DRMLightInterpolator object.

##### See Also

IDirect3DRMLight::GetRange

###

IDirect3DRMLight::SetType

IDirect3DRMLight

Changes the light's type.

HRESULT SetType(
D3DRMLIGHTTYPE d3drmtType
);

##### Parameters

d3drmtType
  New light type specified by one of the members of the D3DRMLIGHTTYPE enumerated type.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### See Also

IDirect3DRMLight::GetType

###

IDirect3DRMLight::SetUmbra

IDirect3DRMLight

Sets the angle of the umbra cone.

HRESULT SetUmbra(
D3DVALUE rvAngle
);

##### Parameters

rvAngle
  New umbra angle. This angle must be less than or equal to the angle of the penumbra. If you set the umbra angle to greater than the penumbra angle, the penumbra angle will be set equal to the umbra angle. The default value is 0.4 radians.

##### Return Values

Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.

##### Remarks

This method is also used to add an umbra angle key to a Direct3DRMLightInterpolator object.

##### See Also

IDirect3DRMLight::GetUmbra

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.