C++ API Reference

Common API rendering functions. More...

#include <MRenderUtil.h>

Public Types

enum  MRenderState {
  kNotRendering, kBatchRender, kInteractiveRender, kIprRender,
  kHardwareRender
}
 Defines the current rendering state of Maya. More...
 
enum  MRenderPass {
  kAll, kColorOnly, kShadowOnly, kAmbientOnly,
  kDiffuseOnly, kSpecularOnly
}
 Defines the current pass of Maya. More...
 

Static Public Member Functions

static MRenderState mayaRenderState ()
 Returns an enumerated type specifying the current state of the Maya renderer. More...
 
static MStatus raytrace (const MFloatVector &rayOrigin, const MFloatVector &rayDirection, const void *objectId, const void *raySampler, const short rayDepth, MFloatVector &resultColor, MFloatVector &resultTransparency, const bool isReflectedRays=true)
 This utility method provides functionality to raytrace from within a shader plug-in. More...
 
static MStatus raytrace (const MFloatVectorArray &rayOrigins, const MFloatVectorArray &rayDirections, const void *objectId, const void *raySampler, const short rayDepth, MFloatVectorArray &resultColors, MFloatVectorArray &resultTransparencies, const bool isReflectedRays=true)
 This utility method provides functionality to raytrace from within a shader plug-in. More...
 
static MStatus raytraceFirstGeometryIntersections (const MFloatVectorArray &rayOrigins, const MFloatVectorArray &rayDirections, const void *objectId, const void *raySampler, MFloatVectorArray &resultIntersections, MIntArray &resultIntersected)
 This utility method provides functionality to find the location of the first geometry intersected by a ray from within a shader plug-in. More...
 
static MStatus sampleShadingNetwork (MString shadingNodeName, int numSamples, bool useShadowMaps, bool reuseMaps, MFloatMatrix &cameraMatrix, MFloatPointArray *points, MFloatArray *uCoords, MFloatArray *vCoords, MFloatVectorArray *normals, MFloatPointArray *refPoints, MFloatVectorArray *tangentUs, MFloatVectorArray *tangentVs, MFloatArray *filterSizes, MFloatVectorArray &resultColors, MFloatVectorArray &resultTransparencies)
 This utility method allows you to sample a shading node/shading engine. More...
 
static bool generatingIprFile ()
 Returns true if an IPR file is being created. More...
 
static MString relativeFileName (const MString &absFileName, MStatus *ReturnStatus=NULL)
 Extract relative file name from the given (absolute) file name. More...
 
static bool exactFileTextureName (const MObject &fileNode, MString &texturePath, MStatus *ReturnStatus=NULL)
 Attempts to resolve the file texture name specified on a file texture node into an absolute path to an image file on disk. More...
 
static bool exactFileTextureName (const MString &baseName, bool useFrameExt, const MString &currentFrameExt, MString &exactName, MStatus *ReturnStatus=NULL)
 This method is obsolete. More...
 
static bool exactFileTextureName (const MString &baseName, bool useFrameExt, const MString &currentFrameExt, const MString &contextNodeFullName, MString &exactName, MStatus *ReturnStatus=NULL)
 Attempts to resolve the file name specified into an absolute path to a file on disk. More...
 
static bool exactFileTextureUvTileData (const MObject &fileNode, MStringArray &tilePaths, MFloatArray &tilePositions, MStatus *ReturnStatus=NULL)
 Attempts to resolve all the paths to UV tiles for the given file texture node into absolute paths to image files on disk. More...
 
static bool convertPsdFile (const MObject &fileNode, MString &texturePath, const bool &forExport=false, MStatus *ReturnStatus=NULL)
 Internal use only. More...
 
static bool exactImagePlaneFileName (const MObject &imagePlaneNode, MString &texturePath, MStatus *ReturnStatus=NULL)
 Attempts to resolve the file texture name specified on an image plane node into an absolute path to an image file on disk. More...
 
static MString exactFileTextureName (const MObject &fileNode, MStatus *ReturnStatus=NULL)
 Attempts to resolve the file texture name specified on a file texture node into an absolute path to an image file on disk. More...
 
static MString exactFileTextureName (const MString &baseName, bool useFrameExt, const MString &currentFrameExt, MStatus *ReturnStatus=NULL)
 This method is obsolete. More...
 
static MString exactFileTextureName (const MString &baseName, bool useFrameExt, const MString &currentFrameExt, const MString &contextNodeFullName, MStatus *ReturnStatus=NULL)
 Attempts to resolve the file name specified into an absolute path to a file on disk. More...
 
static MString convertPsdFile (const MObject &fileNode, const bool &forExport=false, MStatus *ReturnStatus=NULL)
 Internal use only. More...
 
static MString exactImagePlaneFileName (const MObject &imagePlaneNode, MStatus *ReturnStatus=NULL)
 Attempts to resolve the file texture name specified on an image plane node into an absolute path to an image file on disk. More...
 
static bool inCurrentRenderLayer (const MDagPath &objectPath, MStatus *ReturnStatus=NULL)
 Returns true if the specified path is in the current render layer. More...
 
static MRenderPass renderPass (void)
 Returns an enumerated type specifying the current pass the Maya renderer is executing. More...
 
static MString mainBeautyPassCustomTokenString ()
 Returns the custom token string of the main beauty pass for use by renderers in file naming. More...
 
static MString mainBeautyPassName ()
 Returns the name of the main beauty pass for use by renderers for token substitution. More...
 
static float diffuseReflectance (const void *lightBlindData, const MFloatVector &lightDirection, const MFloatVector &pointCamera, const MFloatVector &normal, bool lightBackFace, MStatus *ReturnStatus=NULL)
 This utility function computes and returns the diffuse or lambertian reflectance for a given light source and surface. More...
 
static MFloatVector maximumSpecularReflection (const void *lightBlindData, const MFloatVector &lightDirection, const MFloatVector &pointCamera, const MFloatVector &normal, const MFloatVector &rayDirection, MStatus *ReturnStatus=NULL)
 This utility function computes and returns the vector corresponding to the point on the light source that provides the maximum specular reflection. More...
 
static float lightAttenuation (const void *lightBlindData, const MFloatVector &pointCamera, const MFloatVector &normal, bool lightBackFace, MStatus *ReturnStatus=NULL)
 This utility function computes and returns light attentuation factor of a light. More...
 
static float hemisphereCoverage (const void *lightBlindData, const MFloatVector &lightDirection, const MFloatVector &pointCamera, const MFloatVector &rayDirection, bool lightBackFace, MStatus *ReturnStatus=NULL)
 This utility function computes and returns the fraction of the light that is transmitted by an object. More...
 
static void sendRenderProgressInfo (const MString &pixFile, int percentageDone)
 This utility function sends batch rendering status to Maya. More...
 
static void getCommonRenderSettings (MCommonRenderSettingsData &rgData)
 Fill the set of common render setting values. More...
 
static MStatus renderObjectItem (const void *objectId, MSelectionList &item)
 Procedure to look up a selection item for a given sample object id. More...
 
static const char * className ()
 Returns the name of this class. More...
 
static MStatus eval2dTexture (const MObject &texNode, MDoubleArray &uCoords, MDoubleArray &vCoords, MVectorArray *resultColors, MDoubleArray *resultAlphas)
 If a supported texture node is given, this method can be called to evaluate that texture at a number of (u,v) texture coordinate values. More...
 
static unsigned int noiseTableSize ()
 Access the size of Maya's noise table. More...
 
static unsigned int noiseTableCubeSide ()
 The size of Maya's noise table is a perfect cube. More...
 
static float valueInNoiseTable (unsigned int index)
 Returns a raw value from Maya's noise table at the given index. More...
 
static float noise1 (float x)
 Generates continous non-repeating one dimensional noise based on Maya's internal noise table. More...
 
static float noise2 (float x, float y)
 Generates continous non-repeating two dimensional noise based on Maya's internal noise table. More...
 
static float noise3 (float x, float y, float z)
 Generates continous non-repeating three dimensional noise based on Maya's internal noise table. More...
 
static float noise4 (float x, float y, float z, float t, unsigned short numTimeSteps)
 Generates continous four dimensional (space + time) noise based on Maya's internal noise table. More...
 

Detailed Description

Common API rendering functions.

MRenderUtil is a class which provides static API methods to access Maya's rendering functionalities.

Member Enumeration Documentation

Defines the current rendering state of Maya.

Enumerator
kNotRendering 

Not rendering.

kBatchRender 

Performing a batch render.

kInteractiveRender 

Performing an interactive render.

kIprRender 

Performing an IPR render.

kHardwareRender 

Performing a hardware render.

Defines the current pass of Maya.

Enumerator
kAll 

Default case, compute everything.

kColorOnly 

Compute only color information, no shadows.

kShadowOnly 

Compute only shadow information, no color.

kAmbientOnly 

Compute only ambient information.

kDiffuseOnly 

Compute only diffuse information.

kSpecularOnly 

Compute only specular information.

Member Function Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MRenderUtil::MRenderState mayaRenderState ( )
static

Returns an enumerated type specifying the current state of the Maya renderer.

Returns
MStatus raytrace ( const MFloatVector rayOrigin,
const MFloatVector rayDirection,
const void *  notUsed,
const void *  raySampler,
const short  rayDepth,
MFloatVector resultColor,
MFloatVector resultTransparency,
const bool  isReflectedRays = true 
)
static

This utility method provides functionality to raytrace from within a shader plug-in.

This method shoots a single ray given a ray origin and a ray direction, and returns the color and transparency of the result.

In order for a shader plug-in to raytrace, the following steps are necessary:

raySampler is needed from the renderer. This can be obtained by creating an input attribute named 'raySampler' (rtr).

rayDepth is needed from the renderer. This can be obtained by creating an input attribute named 'rayDepth' (rd).

The "Enable Raytracing" flag needs to be turned on in renderGlobal-> renderQuality->raytracing.

isReflectedRays tells if these rays are for reflection or refraction. This allows the raytracer to check the corresponding ray depth limit under renderGlobal->renderQuality for terminating the rays.

All objects to be seen by the raytracer need to have their "Visible In Reflections" or "Visible In Refraction" flags turned on.

This method only works in the software renderer.

Parameters
[in]rayOriginOrigin of the ray to shoot from in camera space
[in]rayDirectionDirection of the ray to shoot at in camera space
[in]notUsedunused argument left for compatibility
[in]raySamplerPointer to the raytracer from the renderer
[in]rayDepthCurrent ray depth from the renderer
[in]resultColorStorage for the result color
[in]resultTransparencyStorage for the result transparency
[in]isReflectedRaystrue for reflected rays (default), false for refracted rays
Returns
Status Code
  • MS::kSuccess Return is valid
  • MS::kInvalidParameter Raytracing failed due to bad raySampler pointer passed in.
Examples:
phongShader/phongShader.cpp.
MStatus raytrace ( const MFloatVectorArray rayOrigins,
const MFloatVectorArray rayDirections,
const void *  notUsed,
const void *  raySampler,
const short  rayDepth,
MFloatVectorArray resultColors,
MFloatVectorArray resultTransparencies,
const bool  isReflectedRays = true 
)
static

This utility method provides functionality to raytrace from within a shader plug-in.

This method shoots a number of rays given ray origins and ray directions, and returns the colors and transparencies of the results.

The size of rayOrigins, rayDirections, colors, and transparencies arrays must be the same.

In order for a shader plug-in to raytrace, the following steps are necessary:

raySampler is needed from the renderer. This can be obtained by creating an input attribute named 'raySampler' (rtr).

rayDepth is needed from the renderer. This can be obtained by creating an input attribute named 'rayDepth' (rd).

The "Enable Raytracing" flag needs to be turned on in renderGlobal-> renderQuality->raytracing.

isReflectedRays tells if these rays are for reflection or refraction. This allows the raytracer to check the corresponding ray depth limit under renderGlobal->renderQuality for terminating the rays.

All objects to be seen by the raytracer need to have their "Visible In Reflections" or "Visible In Refraction" flags turned on.

This method only works in the software renderer.

Parameters
[in]rayOriginsOrigins of the ray to shoot from in camera space
[in]rayDirectionsDirections of the ray to shoot at in camera space
[in]notUsedunused argument left for compatability
[in]raySamplerPointer to the raytracer from the renderer
[in]rayDepthCurrent ray depth from the renderer
[in]resultColorsStorage for the result colors
[in]resultTransparenciesStorage for the result transparencies
[in]isReflectedRaystrue for reflected rays (default), false for refracted rays
Returns
Status Code
  • MS::kSuccess Return is valid
  • MS::kIndexOutOfRange Array size do not match.
  • MS::kInvalidParameter Raytracing failed due to bad raySampler pointer passed in.
MStatus raytraceFirstGeometryIntersections ( const MFloatVectorArray rayOrigins,
const MFloatVectorArray rayDirections,
const void *  notUsed,
const void *  raySampler,
MFloatVectorArray resultIntersections,
MIntArray resultIntersected 
)
static

This utility method provides functionality to find the location of the first geometry intersected by a ray from within a shader plug-in.

This method shoots a number of rays given ray origins and ray directions, and returns whether the rays intersected anything, and if so, the locations of the first geometry intersected in camera space. The plug-in should check the resultIntersected values to see if a ray has intersected any geometry (0 = no geometry intersected, 1 = geometry intersected).

The size of rayOrigins, rayDirections, resultIntersections, and resultIntersected arrays must be the same.

In order for a shader plug-in to raytrace, the following steps are necessary:

raySampler is needed from the renderer. This can be obtained by creating an input attribute named 'raySampler' (rtr).

The "Enable Raytracing" flag needs to be turned on in renderGlobal-> renderQuality->raytracing.

All objects to be seen by the raytracer need to have their "Visible In Reflections" flags turned on.

This method only works in the software renderer.

Parameters
[in]rayOriginsOrigins of the ray to shoot from in camera space
[in]rayDirectionsDirections of the ray to shoot at in camera space
[in]notUsedunused argument left for compatability
[in]raySamplerPointer to the raytracer from the renderer
[in]resultIntersectionsStorage for the result intersection locations in camera space
[in]resultIntersectedStorage for the result intersected flags (0 = no geometry intersected, 1 = geometry intersected)
Returns
Status Code
  • MS::kSuccess Return is valid
  • MS::kIndexOutOfRange Array size do not match.
  • MS::kInvalidParameter Raytracing failed due to bad raySampler pointer passed in.
MStatus sampleShadingNetwork ( MString  shadingNodeName,
int  numSamples,
bool  useShadowMaps,
bool  reuseMaps,
MFloatMatrix cameraMatrix,
MFloatPointArray points,
MFloatArray uCoords,
MFloatArray vCoords,
MFloatVectorArray normals,
MFloatPointArray refPoints,
MFloatVectorArray tangentUs,
MFloatVectorArray tangentVs,
MFloatArray filterSizes,
MFloatVectorArray resultColors,
MFloatVectorArray resultTransparencies 
)
static

This utility method allows you to sample a shading node/shading engine.

You can specify the location and property of the sample point, and the method will return the result color and transparency. If you are sampling a shading engine, and there are lights in the scene, you can optionally request shadows to be computed as well.

If you specify a shading node to be evaluated, you'll need to provide the attribute to be evaluated. For example, valid shading nodes are checker1.outAlpha, file1.outColor, etc.

If you specify a shading engine to be evaluated, only the name will be needed. For example, valid shading engines are initialShadingGroup, phong1SG, etc.

Since setting up sampling is an expensive operation, try to pass in as many sample points at one time as possible and let the sampler process them in batch. Try to avoid calling the sampler with just one sample.

For extremely complicated shading networks, it is possible that passing in too many samples in one batch will cause a stack overflow. If this condition occurs, simply reduce the number of samples per batch.

Certain type of shading network requires certain type of input, and not all inputs are needed. For example, a 2D texture such as file or checker does not need point/normal/tangent information. Pass in NULL for parameters which are not needed.

In general, 2D textures require UV coordinates, 3D textures require points and refPoints, lighting calculations require points and normals.

To calculate camera space related shaders, such as hilights in a phong shader, an eye to world matrix needs to be supplied. This matrix is used to convert supplied world coordinates into camera coordinate. The matrix can be obtained by getting the inclusive matrix of the camera's DAG node.

This method can be used in both interactive and batch.

Parameters
[in]shadingNodeNameName of the shading node/shading engine
[in]numSamplesNumber of samples to be calculated
[in]useShadowMapsWhether to calculate shadows
[in]reuseMapsIf calculating shadows, whether to reuse shadowmaps
[in]cameraMatrixThe eyeToWorld matrix to be used for conversion
[in]pointsLocations to be sampled in world space
[in]uCoordsU coordinates of the samples
[in]vCoordsV coordinates of the samples
[in]normalsNormals at the sample points in world space
[in]refPointsRefPoints to be used for 3D texture in world space
[in]tangentUsU tangents at the sample points in world space
[in]tangentVsV tangents at the sample points in world space
[in]filterSizesFilter sizes to be used for 2D/3D textures
[in]resultColorsStorage for result colors
[in]resultTransparenciesstorage for result transparencies
Returns
Status Code
  • MS::kSuccess Return is valid
  • MS::kNoModelActive Unable to get the active model
  • MS::kObjectDoesNotExist Unable to find the specified shadingNodeName
  • MS::kInvalidDataType Specified node is not a shading engine
  • MS::kFailure Failed to sample the given shading network
Examples:
sampleCmd/sampleCmd.cpp, and sampleParticles/sampleParticles.cpp.
bool generatingIprFile ( )
static

Returns true if an IPR file is being created.

This can be used to optimize the IPR file. Lights do not need to request particle information (IPR does not support particle rendering) when creating a IPR file.

Returns
true if IPR file is being generated, false otherwise.
MString relativeFileName ( const MString absFileName,
MStatus ReturnStatus = NULL 
)
static

Extract relative file name from the given (absolute) file name.

If the given file name does not begin with a project root, return value is same as the input file name.

Parameters
[in]absFileNameinput file name
[out]ReturnStatusstatus code
Returns
  • file name without the project path
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidParameter absFileName is empty
bool exactFileTextureName ( const MObject fileNode,
MString texturePath,
MStatus ReturnStatus = NULL 
)
static

Attempts to resolve the file texture name specified on a file texture node into an absolute path to an image file on disk.

The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.

Python Notes:

This method is not supported in Python. See the version which returns a string.

Parameters
[in]fileNodea file texture node
[out]texturePathreturns an absolute pathname to the texture file referenced by the node.
[out]ReturnStatusstatus code
Returns
true if the image file pathname was successfully resolved, false otherwise.
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidParameter fileNode pointer is not a valid file texture node.
Examples:
fileTexture/fileTexture.cpp.
bool exactFileTextureName ( const MString baseName,
bool  useFrameExt,
const MString currentFrameExt,
MString exactName,
MStatus ReturnStatus = NULL 
)
static

This method is obsolete.

Attempts to resolve the file name specified into an absolute path to a file on disk.

[as of Maya 2019]

Deprecated:
Context (owner Node full name) must be provided to the Maya resolver. Use the one with the contextNodeFullName input param.

The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.

Python Notes:

This method is not supported in Python. See the version which returns a string.

Parameters
[in]baseNamea file name to be resolved
[in]useFrameExtuse frame extension for image file name
[in]currentFrameExtspecify a frame extension if useFrameExt is used.
[out]exactNameresolved file name with absolute path
[out]ReturnStatusstatus code
Returns
  • true if the file pathname was successfully resolved.
  • false if the pathname could not be resolved.
Status Codes:
  • MS::kSuccess Return is valid
bool exactFileTextureName ( const MString baseName,
bool  useFrameExt,
const MString currentFrameExt,
const MString contextNodeFullName,
MString exactName,
MStatus ReturnStatus = NULL 
)
static

Attempts to resolve the file name specified into an absolute path to a file on disk.

The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.

Python Notes:

This method is not supported in Python. See the version which returns a string.

Parameters
[in]baseNamea file name to be resolved
[in]useFrameExtuse frame extension for image file name
[in]currentFrameExtspecify a frame extension if useFrameExt is used.
[in]contextNodeFullNamefull name of the file owner Node.
[out]exactNameresolved file name with absolute path
[out]ReturnStatusstatus code
Returns
  • true if the file pathname was successfully resolved.
  • false if the pathname could not be resolved.
Status Codes:
  • MS::kSuccess Return is valid
bool exactFileTextureUvTileData ( const MObject fileNode,
MStringArray tilePaths,
MFloatArray tilePositions,
MStatus ReturnStatus = NULL 
)
static

Attempts to resolve all the paths to UV tiles for the given file texture node into absolute paths to image files on disk.

Also computes the lower left coordinate of each tile in UV space. The coordinates are returned in a flat array of floats so for tile 'n', the coordinate is given by: (tilePositions[n*2], tilePositions[n*2+1]).

This function applies exactly the same logic that is used by the file texture node internally for resolving the UV tile paths and positions.

Python Notes:

This method is not supported in Python.

Parameters
[in]fileNodeA file texture node
[out]tilePathsReturns the set of absolute pathnames to the UV tiles for the given texture texture file node
[out]tilePositionsReturns the lower left coordinate of each tile in UV space.
[out]ReturnStatusStatus code
Returns
True if at least one tile was resolved, false otherwise.
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidParameter fileNode pointer is not a valid file texture node.
bool convertPsdFile ( const MObject fileNode,
MString texturePath,
const bool &  forExport = false,
MStatus ReturnStatus = NULL 
)
static

Internal use only.

This method converts a Psd file texture to an IFF file that can be used by Maya.

It writes out the current layer set image the file node. The intermediate image will be either 8 or 16 b.p.c, based on the input psd file.

Python Notes:

This method is not supported in Python. See the version which returns a string.

Parameters
[in]fileNodea file texture node
[out]texturePathreturns an absolute pathname to the texture file referenced by the node.
[in]forExportif true the resulting IFF file will be stored in the project directory tree, otherwise it will be stored in a temporary file which will be deleted when Maya exits.
[out]ReturnStatusstatus code
Returns
  • true if the image file pathname was successfully resolved and exporting psd file is succeeded.
  • false if the pathname could not be resolved or exporting psd file fails.
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidObjectType fileNode pointer is not a valid file texture node.
  • MS::kInvalidParameter fileNode has empty file name string
bool exactImagePlaneFileName ( const MObject imagePlaneNode,
MString texturePath,
MStatus ReturnStatus = NULL 
)
static

Attempts to resolve the file texture name specified on an image plane node into an absolute path to an image file on disk.

The function applies exactly the same logic that is used by the image plane node internally for resolving the image file path.

Python Notes:

This method is not supported in Python. See the version which returns a string.

Parameters
[in]imagePlaneNodean image plane node
[out]texturePathreturns an absolute pathname to the texture file referenced by the node.
[out]ReturnStatusstatus code
Returns
  • true if the image file pathname was successfully resolved.
  • false if the pathname could not be resolved.
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidParameter imagePlaneNode pointer is not a valid image plane node.
MString exactFileTextureName ( const MObject fileNode,
MStatus ReturnStatus = NULL 
)
static

Attempts to resolve the file texture name specified on a file texture node into an absolute path to an image file on disk.

The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.

Parameters
[in]fileNodea file texture node
[out]ReturnStatusstatus code
Returns
An absolute pathname to the texture file referenced by the node. If the path cannot be resolved than an empty string is returned
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidParameter fileNode pointer is not a valid file texture node.
MString exactFileTextureName ( const MString baseName,
bool  useFrameExt,
const MString currentFrameExt,
MStatus ReturnStatus = NULL 
)
static

This method is obsolete.

Attempts to resolve the file name specified into an absolute path to a file on disk.

[as of Maya 2019]

Deprecated:
Context (owner Node full name) must be provided to the Maya resolver. Use the one with the contextNodeFullName input param.

The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.

Parameters
[in]baseNamea file name to be resolved
[in]useFrameExtuse frame extension for image file name
[in]currentFrameExtspecify a frame extension if useFrameExt is used.
[out]ReturnStatusstatus code
Returns
An absolute path to the texture based on its file name. If the path cannot be resolved, then an empty string is returned.
Status Codes:
  • MS::kSuccess Return is valid
MString exactFileTextureName ( const MString baseName,
bool  useFrameExt,
const MString currentFrameExt,
const MString contextNodeFullName,
MStatus ReturnStatus = NULL 
)
static

Attempts to resolve the file name specified into an absolute path to a file on disk.

The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.

Parameters
[in]baseNamea file name to be resolved
[in]useFrameExtuse frame extension for image file name
[in]currentFrameExtspecify a frame extension if useFrameExt is used.
[in]contextNodeFullNamefull name of the file owner Node.
[out]ReturnStatusstatus code
Returns
An absolute path to the texture based on its file name. If the path cannot be resolved, then an empty string is returned.
Status Codes:
  • MS::kSuccess Return is valid
MString convertPsdFile ( const MObject fileNode,
const bool &  forExport = false,
MStatus ReturnStatus = NULL 
)
static

Internal use only.

This method converts a Psd file texture to an IFF file that can be used by Maya.

It writes out the current layer set image the file node. The intermediate image will be either 8 or 16 b.p.c, based on the input psd file.

Parameters
[in]fileNodea file texture node
[in]forExportif true the resulting IFF file will be stored in the project directory tree, otherwise it will be stored in a temporary file which will be deleted when Maya exits.
[out]ReturnStatusstatus code
Returns
  • true if the image file pathname was successfully resolved and exporting psd file is succeeded.
  • false if the pathname could not be resolved or exporting psd file fails.
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidObjectType fileNode pointer is not a valid file texture node.
  • MS::kInvalidParameter fileNode has empty file name string
MString exactImagePlaneFileName ( const MObject imagePlaneNode,
MStatus ReturnStatus = NULL 
)
static

Attempts to resolve the file texture name specified on an image plane node into an absolute path to an image file on disk.

The function applies exactly the same logic that is used by the image plane node internally for resolving the image file path.

Parameters
[in]imagePlaneNodean image plane node
[out]ReturnStatusstatus code
Returns
An absolute pathname to the texture file referenced by the node. If the pathname cannot be resolved, then the returned string is empty
Status Codes:
  • MS::kSuccess Return is valid
  • MS::kInvalidParameter imagePlaneNode pointer is not a valid image plane node.
bool inCurrentRenderLayer ( const MDagPath objectPath,
MStatus ReturnStatus = NULL 
)
static

Returns true if the specified path is in the current render layer.

If the object at the end of the DAG path has not been assigned to any layer, then each node in hierarchy from bottom up will be tested whether its contained in the current render layer.

Parameters
[in]objectPathPath of object to test
[out]ReturnStatusStatus code
Returns
true if the object is in the current render layer.
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Invalid object
MRenderUtil::MRenderPass renderPass ( void  )
static

Returns an enumerated type specifying the current pass the Maya renderer is executing.

Returns
MString mainBeautyPassCustomTokenString ( )
static

Returns the custom token string of the main beauty pass for use by renderers in file naming.

Returns
The custom token string for the main beauty pass
MString mainBeautyPassName ( )
static

Returns the name of the main beauty pass for use by renderers for token substitution.

Returns
The name of the main beauty pass
float diffuseReflectance ( const void *  lightBlindData,
const MFloatVector lightDirection,
const MFloatVector pointCamera,
const MFloatVector normal,
bool  lightBackFace,
MStatus ReturnStatus = NULL 
)
static

This utility function computes and returns the diffuse or lambertian reflectance for a given light source and surface.

Parameters
[in]lightBlindDataThe reference to the aLightBlindData attribute of the current light being evaluated
[in]lightDirectionThe direction of the light being evaluated
[in]pointCameraThe position of the camera
[in]normalThe surface normal
[in]lightBackFaceIs the back face being lit, true or false.
[out]ReturnStatusStatus code
Examples:
phongShader/phongShader.cpp.
MFloatVector maximumSpecularReflection ( const void *  lightBlindData,
const MFloatVector lightDirection,
const MFloatVector pointCamera,
const MFloatVector normal,
const MFloatVector rayDirection,
MStatus ReturnStatus = NULL 
)
static

This utility function computes and returns the vector corresponding to the point on the light source that provides the maximum specular reflection.

Parameters
[in]lightBlindDataThe reference to the aLightBlindData attribute of the current light being evaluated
[in]lightDirectionThe direction of the light being evaluated
[in]pointCameraThe position of the camera
[in]normalThe surface normal
[in]rayDirectionThe direction of the current intersection ray in camera space
[out]ReturnStatusStatus code
Examples:
phongShader/phongShader.cpp.
float lightAttenuation ( const void *  lightBlindData,
const MFloatVector pointCamera,
const MFloatVector normal,
bool  lightBackFace,
MStatus ReturnStatus = NULL 
)
static

This utility function computes and returns light attentuation factor of a light.

Note that the result of 1 will be returned if the light being evaluated does not support light attentuation.

Parameters
[in]lightBlindDataThe reference to the aLightBlindData attribute of the current light being evaluated
[in]pointCameraThe position of the camera
[in]normalThe surface normal
[in]lightBackFaceIs the back face being lit, true or false.
[out]ReturnStatusStatus code
Examples:
phongShader/phongShader.cpp.
float hemisphereCoverage ( const void *  lightBlindData,
const MFloatVector lightDirection,
const MFloatVector pointCamera,
const MFloatVector rayDirection,
bool  lightBackFace,
MStatus ReturnStatus = NULL 
)
static

This utility function computes and returns the fraction of the light that is transmitted by an object.

It is mostly used for translucence and scattering effects.

Parameters
[in]lightBlindDataThe reference to the aLightBlindData attribute of the current light being evaluated
[in]lightDirectionThe direction of the light being evaluated
[in]pointCameraThe position of the camera
[in]rayDirectionThe direction of the current intersection ray in camera space
[in]lightBackFaceIs the back face being lit, true or false.
[out]ReturnStatusStatus code
void sendRenderProgressInfo ( const MString pixFile,
int  percentageDone 
)
static

This utility function sends batch rendering status to Maya.

Parameters
[in]pixFileFile name of the last rendered batch image
[in]percentageDonepercentage rendered
void getCommonRenderSettings ( MCommonRenderSettingsData mrgData)
static

Fill the set of common render setting values.

Parameters
[out]mrgDataRender settings.
MStatus renderObjectItem ( const void *  objectId,
MSelectionList item 
)
static

Procedure to look up a selection item for a given sample object id.

This is only guaranteed to work when software rendering. As multiple processors may be used when software rendering; a critical section should be used to protect multiple threads from simulaneously performing DG evaluation. This includes querying attribute values.

Parameters
[in]objectIdThe sample object id to look-up
[in]itemThe corresponding item for the id
Returns
Status Code
  • MS::kSuccess Returned if valid
  • MS::kInvalidParameter The objectId parameter is NULL
  • MS::kNotFound The item was not found
const char * className ( )
static

Returns the name of this class.

Returns
The name of this class.
MStatus eval2dTexture ( const MObject texNode,
MDoubleArray uCoords,
MDoubleArray vCoords,
MVectorArray resultColors,
MDoubleArray resultAlphas 
)
static

If a supported texture node is given, this method can be called to evaluate that texture at a number of (u,v) texture coordinate values.

Parameters
[in]texNodetexture node to evaluate. It doesn't need to be connected to anything.
[in]uCoordsarray of u coordinate values
[in]vCoordsarray of v coordinate values
[out]resultColorsif non-NULL, receives the result of the connected texture's outColor attribute, evaluated at all the (u,v) coordinates given by the uCoords and vCoords arrays.
[out]resultAlphasif non-NULL, receives the outAlpha values evaluated from the texture at these same points.
Status Codes:
  • MS::kSuccess The texture node was successfully evaluated
  • MS::kUnknownParameter There was no texture so textured values could not be evaluated.
unsigned int noiseTableSize ( )
static

Access the size of Maya's noise table.

The noise table is a constant set of random floating point values in the range [-1.0, 1.0] used by many of Maya's procedural textures.

Returns
The size of the noise table
Examples:
simpleNoiseShader/simpleNoiseShaderOverride.cpp.
unsigned int noiseTableCubeSide ( )
static

The size of Maya's noise table is a perfect cube.

This method returns the cubic root of the table size.

Returns
The cubic root of the size of the noise table
Examples:
simpleNoiseShader/simpleNoiseShaderOverride.cpp.
float valueInNoiseTable ( unsigned int  index)
static

Returns a raw value from Maya's noise table at the given index.

If the index is out of bounds, the index modulo noiseTableSize() is used instead. The noise table is a constant set of random floating point values in the range [-1.0, 1.0] used by many of Maya's procedural textures.

Parameters
[in]indexThe index to retrieve from the noise table
Returns
A value from the noise table in the range [-1.0, 1.0]
Examples:
simpleNoiseShader/simpleNoiseShader.cpp, and simpleNoiseShader/simpleNoiseShaderOverride.cpp.
float noise1 ( float  x)
static

Generates continous non-repeating one dimensional noise based on Maya's internal noise table.

Parameters
[in]xThe one dimensional coordinate for which to generate noise
Returns
A noise value that is non-repeating and continuous on the given coordinate
float noise2 ( float  x,
float  y 
)
static

Generates continous non-repeating two dimensional noise based on Maya's internal noise table.

Parameters
[in]xThe x coordinate for which to generate noise
[in]yThe y coordinate for which to generate noise
Returns
A noise value that is non-repeating and continuous on the given coordinate
float noise3 ( float  x,
float  y,
float  z 
)
static

Generates continous non-repeating three dimensional noise based on Maya's internal noise table.

Parameters
[in]xThe x coordinate for which to generate noise
[in]yThe y coordinate for which to generate noise
[in]zThe y coordinate for which to generate noise
Returns
A noise value that is non-repeating and continuous on the given coordinate
float noise4 ( float  x,
float  y,
float  z,
float  t,
unsigned short  numTimeSteps 
)
static

Generates continous four dimensional (space + time) noise based on Maya's internal noise table.

The noise will loop in a seamless manner. The larger the value for the numTimeSteps parameter the longer it will take for the noise to loop (i.e. more samples would be required along the time axis to cause the sequence to restart).

Parameters
[in]xThe x coordinate for which to generate noise
[in]yThe y coordinate for which to generate noise
[in]zThe y coordinate for which to generate noise
[in]tThe time coordinate for which to generate noise
[in]numTimeStepsControls the repetition of the noise with respect to time
Returns
A noise value that is continuous on the given coordinate

The documentation for this class was generated from the following files: