MFnLight Class Reference

Search for all occurrences

---

Detailed Description

Manage dependency graph nodes representing lights.

MFnLight allows the creation and manipulation of dependency graph nodes representing lights. This is the top level of a hierarchy of light node function sets. It permits manipulation of the attributes common to all types of lights.

Examples:

D3DResourceManager.cpp, D3DViewportRenderer.cpp, hwAnisotropicShader_NV20.cpp, hwToonShader_NV20.cpp, scanDagCmd.cpp, and scanDagSyntax.cpp.

#include <MFnLight.h>

Inheritance diagram for MFnLight:

List of all members.

Public Member Functions
virtual MFn::Type	type () const
	Function set type.
virtual	~MFnLight ()
	Destructor.
	MFnLight ()
	Default constructor.
	MFnLight (MObject &object, MStatus *ReturnStatus=NULL)
	Constructor.
	MFnLight (const MDagPath &object, MStatus *ret=NULL)
	Constructor.
MColor	color (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "color" attribute of a light node.
MStatus	setColor (const MColor &col)
	Sets the value of the "color" attribute of a light node.
float	intensity (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "intensity" attribute of a light node.
MStatus	setIntensity (const float &intens)
	Sets the value of the "intensity" attribute of a light node.
bool	useRayTraceShadows (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "useRayTraceShadows" attribute of a light node.
MStatus	setUseRayTraceShadows (const bool &useRayTraceShadows)
	Sets the value of the "useRayTraceShadows" attribute of a light node.
MColor	shadowColor (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "shadowColor" attribute of a light node.
MStatus	setShadowColor (const MColor &shadow_color)
	Sets the value of the "shadowColor" attribute of a light node.
double	centerOfIllumination (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "centerOfIllumination" attribute of a light node.
MStatus	setCenterOfIllumination (const double &dist)
	Sets the value of the "centerOfIllumination" attribute of a light node.
short	numShadowSamples (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "numShadowSamples" attribute of a light node.
MStatus	setNumShadowSamples (const short &num_shadow_samples)
	Sets the value of the "numShadowSamples" attribute of a light node.
short	rayDepthLimit (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "rayDepthLimit" attribute of a light node.
MStatus	setRayDepthLimit (const short &rayDepthLimit)
	Sets the value of the "rayDepthLimit" attribute of a light node.
MColor	opticalFXvisibility (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "opticalFXvisibility" attribute of a light node.
MStatus	setOpticalFXvisibility (const MColor &visibility)
	Sets the value of the "opticalFXvisibility" attribute of a light node.
MColor	lightIntensity (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "lightIntensity" attribute of a light node.
MFloatVector	lightDirection (int instance, MSpace::Space space=MSpace::kWorld, MStatus *ReturnStatus=NULL) const
	Returns the direction in which the light is pointing.
MFloatVector	lightDirection (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "lightDirection" attribute of a light node.
bool	lightAmbient (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "lightAmbient" attribute of a light node.
bool	lightDiffuse (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "lightDiffuse" attribute of a light node.
bool	lightSpecular (MStatus *ReturnStatus=NULL) const
	Retrieves the value of the "lightSpecular" attribute of a light node.
	MFnLight (const MObject &object, MStatus *ret=NULL)
	Constructor.
Protected Member Functions
virtual const char *	className () const
	Class name.

---

Constructor & Destructor Documentation

~MFnLight

(

)

[virtual]

Destructor.

The class destructor.

MFnLight	(	MObject &	object,
		MStatus *	ReturnStatus = NULL
	)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:

[in]	object	The MObject to attach the function set to
[out]	ReturnStatus	the return status

Status Codes:

• MS::kSuccess if the function set is successfully attached
• MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

MFnLight	(	const MDagPath &	object,
		MStatus *	ReturnStatus = NULL
	)

Constructor.

Class constructor that initializes the function set to the given constant MDagPath object.

Parameters:

[in]	object	The const MDagPath to attach the function set to
[out]	ReturnStatus	The return status

Status Codes:

• MS::kSuccess if the function set is successfully attached
• MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

MFnLight	(	const MObject &	object,
		MStatus *	ReturnStatus = NULL
	)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:

[in]	object	The MObject to attach the function set to
[out]	ReturnStatus	the return status

Status Codes:

• MS::kSuccess if the function set is successfully attached
• MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

---

Member Function Documentation

MFn::Type type

(

)

const [virtual]

Search for all occurrences

Function set type.

Return the class type : MFn::kLight.

Reimplemented from MFnDagNode.

Reimplemented in MFnAmbientLight, MFnAreaLight, MFnDirectionalLight, MFnNonAmbientLight, MFnNonExtendedLight, MFnPointLight, MFnSpotLight, and MFnVolumeLight.

const char * className

(

)

const [protected, virtual]

Search for all occurrences

Class name.

Return the class name : "MFnLight".

Reimplemented from MFnDagNode.

Reimplemented in MFnAmbientLight, MFnAreaLight, MFnDirectionalLight, MFnNonAmbientLight, MFnNonExtendedLight, MFnPointLight, MFnSpotLight, and MFnVolumeLight.

MColor color

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "color" attribute of a light node.

This attribute represents the color of the light emitted by the light node.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "color" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

MStatus setColor

(

const MColor &

col

)

Search for all occurrences

Sets the value of the "color" attribute of a light node.

Parameters:

[in]

col

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object,

float intensity

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "intensity" attribute of a light node.

This attribute represents a uniform scaling factor applied to the light color.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "intensity" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

MStatus setIntensity

(

const float &

intens

)

Search for all occurrences

Sets the value of the "intensity" attribute of a light node.

Parameters:

[in]

intens

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object,

bool useRayTraceShadows

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "useRayTraceShadows" attribute of a light node.

This attribute determines whether or not the light should raytrace it's shadows.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "useRayTraceShadows" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

MStatus setUseRayTraceShadows

(

const bool &

useRayTraceShadows

)

Search for all occurrences

Sets the value of the "useRayTraceShadows" attribute of a light node.

Parameters:

[in]

useRayTraceShadows

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object,

MColor shadowColor

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "shadowColor" attribute of a light node.

This attribute represents the color of the shadows cast by the light.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "shadowColor" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object.

MStatus setShadowColor

(

const MColor &

shadow_color

)

Search for all occurrences

Sets the value of the "shadowColor" attribute of a light node.

Parameters:

[in]

shadow_color

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object,

double centerOfIllumination

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "centerOfIllumination" attribute of a light node.

This attribute represents the distance to the center of illumination of the light.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "centerOfIllumination" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object.

MStatus setCenterOfIllumination

(

const double &

dist

)

Search for all occurrences

Sets the value of the "centerOfIllumination" attribute of a light node.

Parameters:

[in]

dist

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object,

short numShadowSamples

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "numShadowSamples" attribute of a light node.

This attribute represents the number of shadow samples per point used in occulusion testing.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "numShadowSamples" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object.

MStatus setNumShadowSamples

(

const short &

num_shadow_samples

)

Search for all occurrences

Sets the value of the "numShadowSamples" attribute of a light node.

Parameters:

[in]

num_shadow_samples

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object,

short rayDepthLimit

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "rayDepthLimit" attribute of a light node.

This attribute determines a cutoff point for shadow calculations related to the light. Rays whose depth is higher than the value of this attribute will not trigger a shadow calculation for the light.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "rayDepthLimit" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object.

MStatus setRayDepthLimit

(

const short &

ray_depth_limit

)

Search for all occurrences

Sets the value of the "rayDepthLimit" attribute of a light node.

Parameters:

[in]

ray_depth_limit

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object,

MColor opticalFXvisibility

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "opticalFXvisibility" attribute of a light node.

This attribute represents an occlusion scaling factor for light glow effects on this light.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "opticalFXvisibility" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object.

MStatus setOpticalFXvisibility

(

const MColor &

visibility

)

Search for all occurrences

Sets the value of the "opticalFXvisibility" attribute of a light node.

Parameters:

[in]

visibility

value to which the attribute will be set.

Returns:

Return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set doesn not have a valid object,

MColor lightIntensity

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "lightIntensity" attribute of a light node.

This attribute represents the intensity of the light specified as a color.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "lightIntensity" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

MFloatVector lightDirection	(	int	instance,
		MSpace::Space	space = MSpace::kWorld,
		MStatus *	ReturnStatus = NULL
	)		const

Search for all occurrences

Returns the direction in which the light is pointing.

This is only valid for lights which are associated with a direction, such as area, directional or spot lights. The vector returned is not normalized.

Parameters:

[in]	instance	The instance of the light for which to return the direction.
[in]	space	The coordinate space for which the direction vector is returned. If MSpace::kWorld is passed in the vector will be in the lights world space. If any other MSpace::Space value in pass in the vector will be returned in object (or local) space.
[out]	ReturnStatus	return status

Returns:

A vector containing the direction of the light is the specified coordinate system.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

Examples:

intersectCmd.cpp.

MFloatVector lightDirection

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "lightDirection" attribute of a light node.

This attribute represents the direction from the light to the point being shading.

NOTE: This value is only valid during the rendering phase. See lightDirection method above for actual light direction.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "lightDirection" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

bool lightAmbient

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "lightAmbient" attribute of a light node.

This attribute indicates if the light has an ambient component.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "lightAmbient" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

bool lightDiffuse

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "lightDiffuse" attribute of a light node.

This attribute indicates if the light has a diffuse component.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "lightDiffuse" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.

bool lightSpecular

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Retrieves the value of the "lightSpecular" attribute of a light node.

This attribute indicates if the light has a specular component.

Parameters:

[out]

ReturnStatus

return status

Returns:

The value of the "lightSpecular" attribute of the light node.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure function set does not have a valid object.