MFnLight Class Reference
[OpenMaya - API module for common classes, FunctionSet classes]

#include <MFnLight.h>

Inheritance diagram for MFnLight:

[legend]

Collaboration diagram for MFnLight:

[legend]

List of all members.

---

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.

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
MStatus	setColor (const MColor &col)
float	intensity (MStatus *ReturnStatus=NULL) const
MStatus	setIntensity (const float &intens)
bool	useRayTraceShadows (MStatus *ReturnStatus=NULL) const
MStatus	setUseRayTraceShadows (const bool &useRayTraceShadows)
MColor	shadowColor (MStatus *ReturnStatus=NULL) const
MStatus	setShadowColor (const MColor &shadow_color)
double	centerOfIllumination (MStatus *ReturnStatus=NULL) const
MStatus	setCenterOfIllumination (const double &dist)
short	numShadowSamples (MStatus *ReturnStatus=NULL) const
MStatus	setNumShadowSamples (const short &num_shadow_samples)
short	rayDepthLimit (MStatus *ReturnStatus=NULL) const
MStatus	setRayDepthLimit (const short &rayDepthLimit)
MColor	opticalFXvisibility (MStatus *ReturnStatus=NULL) const
MStatus	setOpticalFXvisibility (const MColor &visibility)
MColor	lightIntensity (MStatus *ReturnStatus=NULL) const
MFloatVector	lightDirection (int instance, MSpace::Space space=MSpace::kWorld, MStatus *ReturnStatus=NULL) const
MFloatVector	lightDirection (MStatus *ReturnStatus=NULL) const
bool	lightAmbient (MStatus *ReturnStatus=NULL) const
bool	lightDiffuse (MStatus *ReturnStatus=NULL) const
bool	lightSpecular (MStatus *ReturnStatus=NULL) const
	MFnLight (const MObject &object, MStatus *ret=NULL)
	Constructor.
Protected Member Functions
virtual const char *	className () const
	Class name.

---

Constructor & Destructor Documentation

MFnLight::~MFnLight

(

)

[virtual]

Destructor.

The class destructor.

MFnLight::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::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::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 MFnLight::type

(

)

const [virtual]

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 * MFnLight::className

(

)

const [protected, virtual]

Class name.

Return the class name : "MFnLight"

Reimplemented from MFnDagNode.

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

MColor MFnLight::color

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setColor

(

const MColor &

col

)

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 MFnLight::intensity

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setIntensity

(

const float &

intens

)

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 MFnLight::useRayTraceShadows

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setUseRayTraceShadows

(

const bool &

useRayTraceShadows

)

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 MFnLight::shadowColor

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setShadowColor

(

const MColor &

shadow_color

)

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 MFnLight::centerOfIllumination

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setCenterOfIllumination

(

const double &

dist

)

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 MFnLight::numShadowSamples

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setNumShadowSamples

(

const short &

num_shadow_samples

)

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 MFnLight::rayDepthLimit

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setRayDepthLimit

(

const short &

ray_depth_limit

)

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 MFnLight::opticalFXvisibility

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::setOpticalFXvisibility

(

const MColor &

visibility

)

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 MFnLight::lightIntensity

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::lightDirection	(	int	instance,
		MSpace::Space	space = MSpace::kWorld,
		MStatus *	ReturnStatus = NULL
	)			const

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 MFnLight::lightDirection

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::lightAmbient

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::lightDiffuse

(

MStatus *

ReturnStatus = NULL

)

const

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 MFnLight::lightSpecular

(

MStatus *

ReturnStatus = NULL

)

const

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.