C++ API Reference
Public Types | Public Member Functions | Protected Member Functions | List of all members
MLightParameterInformation Class Reference
OpenMayaRender - API module for rendering

A class for providing lighting information that may be used with Viewport 2.0. More...

#include <MDrawContext.h>

Public Types

enum  ParameterType {
  kInvalid, kBoolean, kInteger, kFloat,
  kFloat2, kFloat3, kFloat4, kFloat4x4Row,
  kFloat4x4Col, kTexture2, kSampler, kTextureCube
}
 Specifies light parameter data types. More...
 
enum  StockParameterSemantic {
  kNoSemantic, kLightEnabled, kWorldPosition, kWorldDirection,
  kIntensity, kColor, kEmitsDiffuse, kEmitsSpecular,
  kDecayRate, kDropoff, kCosConeAngle, kStartShadowParameters ,
  kShadowMap, kShadowSamp, kShadowBias, kShadowMapSize,
  kShadowViewProj, kShadowColor, kGlobalShadowOn, kShadowOn,
  kShadowDirty, kDepthRange
}
 Specifies semantic meanings for predefined names for common or "stock" light parameters. More...
 

Public Member Functions

void parameterList (MStringArray &list) const
 Get the names of all light parameters that are accessible. More...
 
ParameterType parameterType (const MString &parameterName) const
 Get the type of the named parameter, returns kInvalid if parameter is not found. More...
 
StockParameterSemantic parameterSemantic (const MString &parameterName) const
 Get the stock semantic for a named parameter. More...
 
void parameterNames (StockParameterSemantic semantic, MStringArray &list) const
 Get the name of all parameters on the light which are tagged with the stock semantic. More...
 
unsigned int arrayParameterCount (const MString &parameterName) const
 Return the array size of a parameter. More...
 
MStatus getParameter (const MString &parameterName, MIntArray &value)
 Get a named boolean or integer parameter. More...
 
MStatus getParameter (const MString &parameterName, MFloatArray &value)
 Get a named float parameter. More...
 
MStatus getParameter (const MString &parameterName, MMatrix &value)
 Get a named matrix parameter. More...
 
MStatus getParameter (const MString &parameterName, MSamplerStateDesc &samplerDesc)
 Get a description of a sampler parameter. More...
 
void * getParameterTextureHandle (const MString &parameterName)
 Get a resource handle for a texture parameter. More...
 
MStatus getParameter (const MString &parameterName, MTextureAssignment &value)
 Get a named texture parameter. More...
 
MStatus getParameter (StockParameterSemantic semantic, MIntArray &value)
 Get a boolean or integer parameter by semantic. More...
 
MStatus getParameter (StockParameterSemantic semantic, MFloatArray &value)
 Get a float parameter by semantic. More...
 
MStatus getParameter (StockParameterSemantic semantic, MMatrix &value)
 Get a matrix parameter by semantic. More...
 
MStatus getParameter (StockParameterSemantic semantic, MSamplerStateDesc &samplerDesc)
 Get a sampler parameter by semantic. More...
 
void * getParameterTextureHandle (StockParameterSemantic semantic)
 Get a resource handle for a texture parameter by semantic. More...
 
MStatus getParameter (StockParameterSemantic semantic, MTextureAssignment &value)
 Get a texture parameter by semantic. More...
 
MString lightType () const
 Get the classification of the light node. More...
 
MDagPath lightPath (MStatus *ReturnStatus=NULL) const
 Returns the DagPath to the scene light. More...
 

Protected Member Functions

 ~MLightParameterInformation ()
 Destructor.
 

Detailed Description

A class for providing lighting information that may be used with Viewport 2.0.

This class allows for access to various per-light information accessible via the MDrawContext class in Viewport 2.0.

Examples:
dx11Shader/dx11Shader.cpp, dx11Shader/dx11Shader.h, glslShader/GLSLShader.cpp, glslShader/GLSLShader.h, hwPhongShader/hwPhongShader.cpp, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, and viewRenderOverrideShadows/viewRenderOverrideShadows.cpp.

Member Enumeration Documentation

enum ParameterType

Specifies light parameter data types.

Enumerator
kInvalid 

Invalid element type (default value)

kBoolean 

Boolean.

kInteger 

Signed 32-bit integer.

kFloat 

IEEE single precision floating point.

kFloat2 

IEEE single precision floating point (x2)

kFloat3 

IEEE single precision floating point (x3)

kFloat4 

IEEE single precision floating point (x4)

kFloat4x4Row 

IEEE single precision floating point row-major matrix (4x4)

kFloat4x4Col 

IEEE single precision floating point column-major matrix (4x4)

kTexture2 

2D texture

kSampler 

Sampler.

kTextureCube 

Cube texture.

enum StockParameterSemantic

Specifies semantic meanings for predefined names for common or "stock" light parameters.

The semantic is provided to aid in the determination of the appropriate mapping of parameter values to programmable shader or fixed function lighting inputs.

Note that not all parameters exist on all lights so there may be no match for a given stock name. For example a directional light will have no position parameter.

Enumerator
kNoSemantic 

No semantic.

kLightEnabled 

Light is enabled.

kWorldPosition 

World space position.

kWorldDirection 

World space direction.

kIntensity 

Intensity.

kColor 

Color.

kEmitsDiffuse 

Emits diffuse lighting.

kEmitsSpecular 

Emits specular lighting.

kDecayRate 

Decay rate (0=No Decay, 1=Linear, 2=Quadratic, 3=Cubic)

kDropoff 

Dropoff.

kCosConeAngle 

Cosine of the cone angle.

kStartShadowParameters 

Incoming irradiance. Also marks the beginning of enums for shadowing.

kShadowMap 

Shadow map.

kShadowSamp 

Shadow map sampler.

kShadowBias 

Shadow map bias.

kShadowMapSize 

Shadow map size.

kShadowViewProj 

Shadow map view projection matrix.

kShadowColor 

Shadow color.

kGlobalShadowOn 

Global toggle for whether shadows are enabled or not.

kShadowOn 

Local toggle per light for whether shadows are enabled or not.

kShadowDirty 

Indicates if the contents of the shadow map are out-of-date or uninitialized.

kDepthRange 

Used for point light shadow to indicate far and near clip of point light camera.

Member Function Documentation

void parameterList ( MStringArray &  list) const

Get the names of all light parameters that are accessible.

Parameters
[out]listThe list to populate parameter names
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, hwPhongShader/hwPhongShader.cpp, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, and viewRenderOverrideShadows/viewRenderOverrideShadows.cpp.
MLightParameterInformation::ParameterType parameterType ( const MString &  parameterName) const

Get the type of the named parameter, returns kInvalid if parameter is not found.

Parameters
[in]parameterNameName of the parameter to query
Returns
The type of the named parameter
Examples:
hwPhongShader/hwPhongShader.cpp, and viewRenderOverride/viewRenderOverrideOperations.cpp.
MLightParameterInformation::StockParameterSemantic parameterSemantic ( const MString &  parameterName) const

Get the stock semantic for a named parameter.

Parameters
[in]parameterNameName of the parameter to query
Returns
The semantic of the named parameter
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, hwPhongShader/hwPhongShader.cpp, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, and viewRenderOverrideShadows/viewRenderOverrideShadows.cpp.
void parameterNames ( MLightParameterInformation::StockParameterSemantic  semantic,
MStringArray &  list 
) const

Get the name of all parameters on the light which are tagged with the stock semantic.

Parameters
[in]semanticThe semantic to query
[out]listThe list to populate with parameter names, will be empty if light has no parameters matching semantic.
Examples:
viewRenderOverride/viewRenderOverrideOperations.cpp.
unsigned int arrayParameterCount ( const MString &  parameterName) const

Return the array size of a parameter.

If the parameter is not an array then a value of 0 is returned.

Parameters
[in]parameterNameName of the parameter to query
Returns
Array size of a parameter.
MStatus getParameter ( const MString &  parameterName,
MIntArray &  value 
)

Get a named boolean or integer parameter.

Parameters
[in]parameterNameName of the parameter to retrieve
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter The named parameter is not a boolean or integer parameter.
  • MS::kUnknownParameter The named parameter does not exist.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, hwPhongShader/hwPhongShader.cpp, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, and viewRenderOverrideShadows/viewRenderOverrideShadows.cpp.
MStatus getParameter ( const MString &  parameterName,
MFloatArray &  value 
)

Get a named float parameter.

Parameters
[in]parameterNameName of the parameter to retrieve
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter The named parameter is not a float parameter.
  • MS::kUnknownParameter The named parameter does not exist.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
MStatus getParameter ( const MString &  parameterName,
MMatrix &  value 
)

Get a named matrix parameter.

Parameters
[in]parameterNameName of the parameter to retrieve
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter The named parameter is not a matrix parameter.
  • MS::kUnknownParameter The named parameter does not exist.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
MStatus getParameter ( const MString &  parameterName,
MSamplerStateDesc &  samplerDesc 
)

Get a description of a sampler parameter.

Parameters
[in]parameterNameName of the parameter to retrieve
[out]samplerDescSampler state description retrieved
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter The named parameter is not a sampler parameter.
  • MS::kUnknownParameter The named parameter is not an existing parameter.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
void * getParameterTextureHandle ( const MString &  parameterName)

Get a resource handle for a texture parameter.

Parameters
[in]parameterNameName of the parameter to query
Returns
Resource handle for a texture parameter
Examples:
dx11Shader/dx11Shader.cpp, hwPhongShader/hwPhongShader.cpp, and viewRenderOverride/viewRenderOverrideOperations.cpp.
MStatus getParameter ( const MString &  parameterName,
MHWRender::MTextureAssignment &  value 
)

Get a named texture parameter.

Parameters
[in]parameterNameName of the parameter to query
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter The named parameter is not a texture parameter.
  • MS::kUnknownParameter The named parameter does not exist.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
MStatus getParameter ( MLightParameterInformation::StockParameterSemantic  semantic,
MIntArray &  value 
)

Get a boolean or integer parameter by semantic.

If more than one parameter matches the semantic, the value of the first matching boolean or integer parameter found will be returned.

Parameters
[in]semanticSemantic of the parameter to retrieve
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter No parameter for the semantic is a boolean or integer parameter.
  • MS::kUnknownParameter No parameter matching the semantic exists.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
MStatus getParameter ( MLightParameterInformation::StockParameterSemantic  semantic,
MFloatArray &  value 
)

Get a float parameter by semantic.

If more than one parameter matches the semantic, the value of the first matching float parameter found will be returned.

Parameters
[in]semanticSemantic of the parameter to retrieve
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter No parameter for the semantic is a float parameter.
  • MS::kUnknownParameter No parameter matching the semantic exists.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
MStatus getParameter ( MLightParameterInformation::StockParameterSemantic  semantic,
MMatrix &  value 
)

Get a matrix parameter by semantic.

If more than one parameter matches the semantic, the value of the first matching matrix parameter found will be returned.

Parameters
[in]semanticSemantic of the parameter to retrieve
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter No parameter for the semantic is a matrix parameter.
  • MS::kUnknownParameter No parameter matching the semantic exists.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
MStatus getParameter ( MLightParameterInformation::StockParameterSemantic  semantic,
MSamplerStateDesc &  samplerDesc 
)

Get a sampler parameter by semantic.

If more than one parameter matches the semantic, the value of the first matching sampler parameter found will be returned.

Parameters
[in]semanticSemantic of the parameter to retrieve
[out]samplerDescValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter No parameter for the semantic is a sampler parameter.
  • MS::kUnknownParameter No parameter matching the semantic exists.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
void * getParameterTextureHandle ( MLightParameterInformation::StockParameterSemantic  semantic)

Get a resource handle for a texture parameter by semantic.

Parameters
[in]semanticSemantic of the parameter to retrieve
Returns
Resource handle for a texture parameter
MStatus getParameter ( MLightParameterInformation::StockParameterSemantic  semantic,
MHWRender::MTextureAssignment &  value 
)

Get a texture parameter by semantic.

If more than one parameter matches the semantic, the value of the first matching texture parameter found will be returned.

Parameters
[in]semanticSemantic of the parameter to retrieve
[out]valueValue of the parameter
Returns
Status code
Status Codes:
  • MS::kSuccess The parameter was retrieved.
  • MS::kInvalidParameter No parameter for the semantic is a texture parameter.
  • MS::kUnknownParameter No parameter matching the semantic exists.
  • MS::kFailure An internal error prevented the parameter from being retrieved.
MString lightType ( ) const

Get the classification of the light node.

Returns
Classification
  • ambientLight Ambient Light
  • areaLight Area Light
  • directionalLight Directional Light
  • pointLight Point Light
  • spotLight Spot Light
  • volumeLight Volume Light
Examples:
dx11Shader/dx11Shader.cpp, and glslShader/GLSLShader.cpp.
MDagPath lightPath ( MStatus *  ReturnStatus = NULL) const

Returns the DagPath to the scene light.

Will return an unitialized DagPath for default lights.

Parameters
[out]ReturnStatusStatus code.
Returns
An MDagPath that references the object to which the Function Set is attached. If the function set is not attached to a dag path an uninitialized MDagPath will be returned.
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Function set does not have a valid object
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, and viewRenderOverrideShadows/viewRenderOverrideShadows.cpp.
The documentation for this class was generated from the following files: