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 Lights.
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 IDirect3DRM3::CreateLight or IDirect3DRM3::CreateLightRGB method.
IDirect3DRMLight::GetColor
IDirect3DRMLight
Retrieves the color of the current Direct3DRMLight object.
Syntax
D3DCOLOR GetColor( );
Return Value
Returns the color.
See Also
IDirect3DRMLight::GetConstantAttenuation
IDirect3DRMLight
Retrieves the constant attenuation factor for the Direct3DRMLight object.
Syntax
D3DVALUE GetConstantAttenuation( );
Return Value
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 light attenuation formula used depends on whether or not the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set. This flag is set in IDirect3DRMDevice3::SetRenderMode.
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set, the following formulae are used for light attenuation.
- The formula for the normalized distance is:
normalized_distance = (distance_from_light - light_range)/light_range
The default light_range value is 256 modeling-space units.
The formula for the total attenuation factor is:
constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is not set, the following formula is used for light attentuation.
- 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::GetEnableFrame
IDirect3DRMLight
Retrieves the enable frame for a light.
Syntax
HRESULT GetEnableFrame(
LPDIRECT3DRMFRAME *lplpEnableFrame
);
Parameters
- lplpEnableFrame
- Address of a pointer that will contain the enable frame for the current Direct3DRMFrame object.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMLight::GetLinearAttenuation
IDirect3DRMLight
Retrieves the linear attenuation factor for a light.
Syntax
D3DVALUE GetLinearAttenuation( );
Return Value
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 the distance from the light.
The light attenuation formula used depends on whether or not the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set. This flag is set in IDirect3DRMDevice3::SetRenderMode.
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set, the following formulae are used for light attenuation.
- The formula for the normalized distance is:
normalized_distance = (distance_from_light - light_range)/light_range
The default light_range value is 256 modeling-space units.
The formula for the total attenuation factor is:
constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is not set, the following formula is used for light attentuation.
- 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::GetPenumbra
IDirect3DRMLight
Retrieves the penumbra angle of a spotlight.
Syntax
D3DVALUE GetPenumbra( );
Return Value
Returns the penumbra value in radians.
Remarks
For more information see the Spotlight section of the Lights overview.
See Also
IDirect3DRMLight::GetQuadraticAttenuation
IDirect3DRMLight
Retrieves the quadratic attenuation factor for a light.
Syntax
D3DVALUE GetQuadraticAttenuation( );
Return Value
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 the distance from the light.
The light attenuation formula used depends on whether or not the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set. This flag is set in IDirect3DRMDevice3::SetRenderMode.
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set, the following formulae are used for light attenuation.
- The formula for the normalized distance is:
normalized_distance = (distance_from_light - light_range)/light_range
The default light_range value is 256 modeling-space units.
The formula for the total attenuation factor is:
constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is not set, the following formula is used for light attentuation.
- 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::GetRange
IDirect3DRMLight
Retrieves the range of the current Direct3DRMLight object.
Syntax
D3DVALUE GetRange( );
Return Value
Returns a value describing the range.
See Also
IDirect3DRMLight::GetType
IDirect3DRMLight
Retrieves the type of a given light.
Syntax
D3DRMLIGHTTYPE GetType( );
Return Value
Returns one of the members of the D3DRMLIGHTTYPE enumerated type.
See Also
IDirect3DRMLight::GetUmbra
IDirect3DRMLight
Retrieves the umbra angle of the Direct3DRMLight object. The default is 0.4 radians.
Syntax
D3DVALUE GetUmbra( );
Return Value
Returns the umbra angle in radians.
Remarks
For more information see the Spotlight section of the Lights overview.
See Also
IDirect3DRMLight::SetColor
IDirect3DRMLight
Sets the color of the given light.
Syntax
HRESULT SetColor(
D3DCOLOR rcColor
);
Parameters
- rcColor
- New color for the light. Be sure to set the alpha component as well as the red, green, and blue color components or your objects might not be visible. The RGBA_MAKE DirectX macro allows you to specify these values.
Return Value
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::SetColorRGB
IDirect3DRMLight
Sets the color of the given light.
Syntax
HRESULT SetColorRGB(
D3DVALUE rvRed,
D3DVALUE rvGreen,
D3DVALUE rvBlue
);
Parameters
- rvRed, rvGreen, and rvBlue
- New color for the light.
Return Value
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.
Syntax
HRESULT SetConstantAttenuation(
D3DVALUE rvAtt
);
Parameters
- rvAtt
- New constant attenuation factor.
Return Value
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 light attenuation formula used depends on whether or not the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set. This flag is set in IDirect3DRMDevice3::SetRenderMode.
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set, the following formulae are used for light attenuation.
- The formula for the normalized distance is:
normalized_distance = (distance_from_light - light_range)/light_range
The default light_range value is 256 modeling-space units.
The formula for the total attenuation factor is:
constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is not set, the following formula is used for light attentuation.
- 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::SetEnableFrame
IDirect3DRMLight
Sets the enable frame for a light.
Syntax
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 Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMLight::SetLinearAttenuation
IDirect3DRMLight
Sets the linear attenuation factor for a light.
Syntax
HRESULT SetLinearAttenuation(
D3DVALUE rvAtt
);
Parameters
- rvAtt
- New linear attenuation factor.
Return Value
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 light attenuation formula used depends on whether or not the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set. This flag is set in IDirect3DRMDevice3::SetRenderMode.
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set, the following formulae are used for light attenuation.
- The formula for the normalized distance is:
normalized_distance = (distance_from_light - light_range)/light_range
The default light_range value is 256 modeling-space units.
The formula for the total attenuation factor is:
constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is not set, the following formula is used for light attentuation.
- 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::SetPenumbra
IDirect3DRMLight
Sets the angle of the penumbra cone.
Syntax
HRESULT SetPenumbra(
D3DVALUE rvAngle
);
Parameters
- rvAngle
- New penumbra angle in radians. 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 Value
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.
For more information see the Spotlight section of the Lights overview.
See Also
IDirect3DRMLight::SetQuadraticAttenuation
IDirect3DRMLight
Sets the quadratic attenuation factor for a light.
Syntax
HRESULT SetQuadraticAttenuation(
D3DVALUE rvAtt
);
Parameters
- rvAtt
- New quadratic attenuation factor.
Return Value
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 light attenuation formula used depends on whether or not the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set. This flag is set in IDirect3DRMDevice3::SetRenderMode.
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is set, the following formulae are used for light attenuation.
- The formula for the normalized distance is:
normalized_distance = (distance_from_light - light_range)/light_range
The default light_range value is 256 modeling-space units.
The formula for the total attenuation factor is:
constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor
If the D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR flag is not set, the following formula is used for light attentuation.
- 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::SetRange
IDirect3DRMLight
Sets the range of a spotlight. The light affects objects that are within the range only.
Syntax
HRESULT SetRange(
D3DVALUE rvRange
);
Parameters
- rvRange
- New range. The default value is 256 modeling-space units.
Return Value
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::SetType
IDirect3DRMLight
Changes the light's type.
Syntax
HRESULT SetType(
D3DRMLIGHTTYPE d3drmtType
);
Parameters
- d3drmtType
- New light type specified by one of the members of the D3DRMLIGHTTYPE enumerated type.
Return Value
Returns D3DRM_OK if successful, or an error otherwise. For a list of possible errors, see Direct3D Retained Mode Return Values.
See Also
IDirect3DRMLight::SetUmbra
IDirect3DRMLight
Sets the angle of the umbra cone.
Syntax
HRESULT SetUmbra(
D3DVALUE rvAngle
);
Parameters
- rvAngle
- New umbra angle in radians. 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 Value
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.
For more information see the Spotlight section of the Lights overview.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.