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.
Retrieves the color of the current Direct3DRMLight object.
D3DCOLOR GetColor( );
Returns the color.
Retrieves the constant attenuation factor for the Direct3DRMLight object.
D3DVALUE GetConstantAttenuation( );
Returns the constant attenuation value.
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.
IDirect3DRMLight::SetConstantAttenuation
Retrieves the enable frame for a light.
HRESULT GetEnableFrame(
LPDIRECT3DRMFRAME * lplpEnableFrame
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMLight::SetEnableFrame
Retrieves the linear attenuation factor for a light.
D3DVALUE GetLinearAttenuation( );
Returns the linear attenuation value.
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.
IDirect3DRMLight::SetLinearAttenuation
Retrieves the penumbra angle of a spotlight.
D3DVALUE GetPenumbra( );
Returns the penumbra value.
Retrieves the quadratic attenuation factor for a light.
D3DVALUE GetQuadraticAttenuation( );
Returns the quadratic attenuation value.
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.
IDirect3DRMLight::SetQuadraticAttenuation
Retrieves the range of the current Direct3DRMLight object.
D3DVALUE GetRange( );
Returns a value describing the range.
Retrieves the type of a given light.
D3DRMLIGHTTYPE GetType( );
Returns one of the members of the D3DRMLIGHTTYPE enumerated type.
Retrieves the umbra angle of the Direct3DRMLight object.
D3DVALUE GetUmbra( );
Returns the umbra angle.
Sets the color of the given light.
HRESULT SetColor(
D3DCOLOR rcColor
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a color key to a Direct3DRMLightInterpolator object.
Sets the color of the given light.
HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add an RGB color key to a Direct3DRMLightInterpolator object.
Sets the constant attenuation factor for a light.
HRESULT SetConstantAttenuation(
D3DVALUE rvAtt
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMLight::GetConstantAttenuation
Sets the enable frame for a light.
HRESULT SetEnableFrame(
LPDIRECT3DRMFRAME lpEnableFrame
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
IDirect3DRMLight::GetEnableFrame
Sets the linear attenuation factor for a light.
HRESULT SetLinearAttenuation(
D3DVALUE rvAtt
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMLight::GetLinearAttenuation
Sets the angle of the penumbra cone.
HRESULT SetPenumbra(
D3DVALUE rvAngle
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add a penumbra angle key to a Direct3DRMLightInterpolator object.
Sets the quadratic attenuation factor for a light.
HRESULT SetQuadraticAttenuation(
D3DVALUE rvAtt
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
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.
IDirect3DRMLight::GetQuadraticAttenuation
Sets the range of a spotlight. The light affects objects that are within the range only.
HRESULT SetRange(
D3DVALUE rvRange
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
The range property is for spotlights only. This method is also used to add a range key to a Direct3DRMLightInterpolator object.
Changes the light's type.
HRESULT SetType(
D3DRMLIGHTTYPE d3drmtType
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
Sets the angle of the umbra cone.
HRESULT SetUmbra(
D3DVALUE rvAngle
);
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
This method is also used to add an umbra angle key to a Direct3DRMLightInterpolator object.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.