IFXLightResource

IFXLightResource is the interface used to get and set light properties for a shared resource. Light Resources can be shared among many lights (IFXLight), where each IFXLight represents a single node in the scenegraph. Light Resources are managed by the scenegraph, and contained in the Light Resource Palette. IFXLightResource inherits the IFXMarker and IFXUnknown interfaces. It is supported by the CIFXLightResource component.

When to Use

IFXLightResource will be used whenever the parameters of a light resource need to be set or queried.

Interface Methods

Description

GetType

Retrieves the type of the light resource

SetType

Assigns a light type to the light resource

GetAttributes

Retrieves the attributes of the light resource

SetAttributes

Assigns light attributes to the resource

GetColor

Retrieves the RGB color of the resource

SetColor

Assigns an RGB color to the resource

GetSpotAngle

Retrieves the radial angle of a resource of type SPOT

SetSpotAngle

Assigns the radial angle of the resource, if it is of type SPOT

GetAttenuation

Retrieves a value that represents the distance attenuation factor of the light resource

SetAttenuation

Assigns a value that represents the distance attenuation factor of the light resource

GetLightGroups

Gets light groups

SetLightGroups

Sets light groups

GetExtent

Retrieves a distance value that represents the maximum distance that a light using this resource can be from an object and still contribute to its lighting

Render

Calls an IFXRenderLayer

RenderBound

Calls an IFXRenderLayer


IFXLightResource::GetType()

This method retrieves the light type of the light resource. The type can be one of the following: AMBIENT, DIRECTIONAL, POINT, SPOT.

Parameters:

None

Return Values:

LightType - The light type of the resource. AMBIENT, DIRECTIONAL, POINT, or SPOT.


IFXLightResource::SetType(LightType u8In)

This method assigns a light type to the resource. The type can be one of the following: AMBIENT, DIRECTIONAL, POINT, SPOT.

Parameters:

U8In

The specified light type. AMBIENT, DIRECTIONAL, POINT, or SPOT

Return Values:

None


IFXLightResource::GetAttributes()

This method retrieves the attributes of the light resource. The attributes consist of a bit field, 8 bits wide. Only the two least significant bits are currently used. 0x01 represents the Enabled bit (1=enabled, 0=not) and 0x02 represents the Specular field (1=specular, 0=not).

Parameters:

None

Return Values:

U8 - The 8-bit field of attribute flags.


IFXLightResource::SetAttributes(U8 uIn)

This method assigns a set of attributes to the light resource. The attributes consist of a bit field, 8 bits wide. Only the 2 least significant bits are currently used. 0x01 represents the Enabled bit (1=enabled, 0=not) and 0x02 represents the Specular field (1=specular, 0=not).

Parameters:

uIn

The 8-bit field of attribute flags

Return Values:

None


IFXLightResource::GetColor()

This method retrieves the color of the light resource in the form of a 4 component vector. The (x,y,z) or (R,G,B) components of the vector contain the red, green and blue color components respectively. The fourth component of the vector is not used.

Parameters:

None

Return Values:

IFXSGVector - The color of the light resource.


IFXLightResource::SetColor(IFXSGVector vIn)

This method assigns a color to the light resource in the form of a 4 component vector. The (x,y,z) or (R,G,B) components of the vector contain the red, green and blue color components respectively. The fourth component of the vector is not used.

Parameters:

vIn

The color assigned to the light resource

Return Values:

None


IFXLightResource::GetSpotAngle()

This method retrieves the radial angle of the light resource. This value is only relevant if the light type is SPOT.

Parameters:

None

Return Values:

F32 - The radial angle of the light resource.

Comments:

The spot angle is the half radial angle of the spot light, as is occasionally used in some graphics environments (such as OpenGL§).


IFXLightResource::SetSpotAngle(F32 fIn)

This method assigns a radial angle to the light resource. This value is only relevant if the light type is SPOT.

Parameters:

fIn

The radial angle assigned to the light resource

Return Values:

None

Comments:

The spot angle is the half radial angle of the spot light, as is occasionally used in some graphics environments (such as OpenGL).


IFXLightResource::GetAttenuation(F32* pOut)

This method retrieves the attenuation factor used with the light resource. This factor is used to alter the contribution of the light resource on an object based on the distance of the object from the light using the resource. Basically, the further away the object is from the light, the less the light contributes to that object's lighting.

Parameters:

pOut

The attenuation factor for the light resource. This factor is used to alter the contribution made by a light based on distance from the light's position.

Return Values

Comments:

Attenuation is relevant for resources of type AMBIENT, POINT, or SPOT.


IFXLightResource::SetAttenuation(F32* pIn)

This method assigns an attenuation factor for the light resource. This factor is used to alter the contribution of the light resource on an object based on the distance of the object from the light using the resource. Basically, the farther away the object is from the light, the less the light contributes to that object's lighting.

Attenuation is specified as an array of three F32 values: (c, l, q). These three values are the constants used in the DirectX§ or OpenGL lighting model, which represents light intensity as follows:

LightIntensity(d) = LightIntensity(d=0) * 1.0/(c + d*l + d*d*q)

Where:

In 3D Studio MAX§ the light intensity can go above its original value inside a radius called fDecayStart, using l=1/fDecayStart or q=1/(fDecayStart*fDecayStart). Use these values or use values from 0 to 1.0 for c, l, and q. Setting only one of these values to 1.0 and the other to 0.0 works well in reproducing the input lights.

Both OpenGL and DirectX allow the LightIntensity(d) to be larger than LightIntensity(d=0), so meaningful results are obtained if c, l, or q are larger than 1.0.

Parameters:

pIn

The attenuation factor for the light resource. This factor is used to alter the contribution made by a light based on distance from the light's position.

Return Values

Comments:

Attenuation is relevant for resources of type AMBIENT, POINT, or SPOT.


IFXLightResource::GetLightGroups()

Parameters:

None

Return Values:

U32


IFXLightResource::SetLightGroups(U32 uIn)

Parameters:

uIn

Return Values:

None


IFXLightResource::GetExtent()

This method retrieves a distance value that represents the maximum distance that a light using this resource can be from an object and still contribute to its lighting. In other words, if the distance between an object and a light is greater than the light's extent, the light will not contribute to the object's lighting.

Parameters:

None

Return Values:

F32 - If ppOutLightResource is NULL.

Comments:

Extent is relevant for all light types.


IFXLightResource::Render(IFXRenderLayer* pRenderLayer)

This method calls the IFXRenderLayer.

Parameters:

pRenderLayer

Pointer to the IFXRenderLayer

Return Values:

None


IFXLightResource::RenderBound(IFXRenderLayer* pRenderLayer)

This method calls the IFXRenderLayer.

Parameters:

pRenderLayer

Pointer to the IFXRenderLayer

Return Values:

None

§See asterisked (*) statement at Legal Information © 2001 Intel Corporation.