MRenderUtil Class Reference
[OpenMayaRender - API module for rendering]

#include <MRenderUtil.h>

List of all members.


Detailed Description

Common API rendering functions.

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


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 ()
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)
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)
static MStatus  raytraceFirstGeometryIntersections (const MFloatVectorArray &rayOrigins, const MFloatVectorArray &rayDirections, const void *objectId, const void *raySampler, MFloatVectorArray &resultIntersections, MIntArray &resultIntersected)
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)
static bool  generatingIprFile ()
static MString  relativeFileName (const MString &absFileName, MStatus *ReturnStatus=NULL)
static bool  exactFileTextureName (const MObject &fileNode, MString &texturePath, MStatus *ReturnStatus=NULL)
static bool  exactFileTextureName (const MString &baseName, bool useFrameExt, const MString &currentFrameExt, MString &exactName, MStatus *ReturnStatus=NULL)
static bool  convertPsdFile (const MObject &fileNode, MString &texturePath, const bool &state=false, MStatus *ReturnStatus=NULL)
  Internal use only.
static bool  exactImagePlaneFileName (const MObject &imagePlaneNode, MString &texturePath, MStatus *ReturnStatus=NULL)
static MString  exactFileTextureName (const MObject &fileNode, MStatus *ReturnStatus=NULL)
static MString  exactFileTextureName (const MString &baseName, bool useFrameExt, const MString &currentFrameExt, MStatus *ReturnStatus=NULL)
static MString  convertPsdFile (const MObject &fileNode, const bool &state=false, MStatus *ReturnStatus=NULL)
  Internal use only.
static MString  exactImagePlaneFileName (const MObject &imagePlaneNode, MStatus *ReturnStatus=NULL)
static bool  inCurrentRenderLayer (const MDagPath &objectPath, MStatus *ReturnStatus=NULL)
static MRenderPass  renderPass (void)
static MString  mainBeautyPassCustomTokenString ()
static MString  mainBeautyPassName ()
static float  diffuseReflectance (const void *lightBlindData, const MFloatVector &lightDirection, const MFloatVector &pointCamera, const MFloatVector &normal, bool lightBackFace, MStatus *ReturnStatus=NULL)
static MFloatVector  maximumSpecularReflection (const void *lightBlindData, const MFloatVector &lightDirection, const MFloatVector &pointCamera, const MFloatVector &normal, const MFloatVector &rayDirection, MStatus *ReturnStatus=NULL)
static float  lightAttenuation (const void *lightBlindData, const MFloatVector &pointCamera, const MFloatVector &normal, bool lightBackFace, MStatus *ReturnStatus=NULL)
static float  hemisphereCoverage (const void *lightBlindData, const MFloatVector &lightDirection, const MFloatVector &pointCamera, const MFloatVector &rayDirection, bool lightBackFace, MStatus *ReturnStatus=NULL)
static void  sendRenderProgressInfo (const MString &pixFile, int percentageDone)
static void  getCommonRenderSettings (MCommonRenderSettingsData &rgData)
static MStatus  renderObjectItem (const void *objectId, MSelectionList &item)

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

MRenderUtil::MRenderState MRenderUtil::mayaRenderState (  )  [static]

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

Returns:

MStatus MRenderUtil::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]  rayOrigin  Origin of the ray to shoot from in camera space
[in]  rayDirection  Direction of the ray to shoot at in camera space
[in]  notUsed  unused argument left for compatibility
[in]  raySampler  Pointer to the raytracer from the renderer
[in]  rayDepth  Current ray depth from the renderer
[in]  resultColor  Storage for the result color
[in]  resultTransparency  Storage for the result transparency
[in]  isReflectedRays  true for reflected rays (default), false for refracted rays
Returns:
Status Code
Examples:

MStatus MRenderUtil::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]  rayOrigins  Origins of the ray to shoot from in camera space
[in]  rayDirections  Directions of the ray to shoot at in camera space
[in]  notUsed  unused argument left for compatability
[in]  raySampler  Pointer to the raytracer from the renderer
[in]  rayDepth  Current ray depth from the renderer
[in]  resultColors  Storage for the result colors
[in]  resultTransparencies  Storage for the result transparencies
[in]  isReflectedRays  true for reflected rays (default), false for refracted rays
Returns:
Status Code

MStatus MRenderUtil::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]  rayOrigins  Origins of the ray to shoot from in camera space
[in]  rayDirections  Directions of the ray to shoot at in camera space
[in]  notUsed  unused argument left for compatability
[in]  raySampler  Pointer to the raytracer from the renderer
[in]  resultIntersections  Storage for the result intersection locations in camera space
[in]  resultIntersected  Storage for the result intersected flags (0 = no geometry intersected, 1 = geometry intersected)
Returns:
Status Code

MStatus MRenderUtil::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]  shadingNodeName  Name of the shading node/shading engine
[in]  numSamples  Number of samples to be calculated
[in]  useShadowMaps  Whether to calculate shadows
[in]  reuseMaps  If calculating shadows, whether to reuse shadowmaps
[in]  cameraMatrix  The eyeToWorld matrix to be used for conversion
[in]  points  Locations to be sampled in world space
[in]  uCoords  U coordinates of the samples
[in]  vCoords  V coordinates of the samples
[in]  normals  Normals at the sample points in world space
[in]  refPoints  RefPoints to be used for 3D texture in world space
[in]  tangentUs  U tangents at the sample points in world space
[in]  tangentVs  V tangents at the sample points in world space
[in]  filterSizes  Filter sizes to be used for 2D/3D textures
[in]  resultColors  Storage for result colors
[in]  resultTransparencies  storage 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:

bool MRenderUtil::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 MRenderUtil::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]  absFileName  input file name
[out]  ReturnStatus  status code
Returns:
  • file name without the project path
Status Codes:

bool MRenderUtil::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]  fileNode  a file texture node
[out]  texturePath  returns an absolute pathname to the texture file referenced by the node.
[out]  ReturnStatus  status code
Returns:
true if the image file pathname was successfully resolved, false otherwise.
Status Codes:

bool MRenderUtil::exactFileTextureName ( const MString baseName,
bool  useFrameExt,
const MString currentFrameExt,
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]  baseName  a file name to be resolved
[in]  useFrameExt  use frame extension for image file name
[in]  currentFrameExt  specify a frame extension if useFrameExt is used.
[out]  exactName  resolved file name with absolute path
[out]  ReturnStatus  status code
Returns:
  • true if the file pathname was successfully resolved.
  • false if the pathname could not be resolved.
Status Codes:

bool MRenderUtil::convertPsdFile ( const MObject fileNode,
MString texturePath,
const bool &  state = 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]  fileNode  a file texture node
[out]  texturePath  returns an absolute pathname to the texture file referenced by the node.
[out]  ReturnStatus  status 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:

bool MRenderUtil::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]  imagePlaneNode  an image plane node
[out]  texturePath  returns an absolute pathname to the texture file referenced by the node.
[out]  ReturnStatus  status code
Returns:
  • true if the image file pathname was successfully resolved.
  • false if the pathname could not be resolved.
Status Codes:

MString MRenderUtil::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]  fileNode  a file texture node
[out]  ReturnStatus  status 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:

MString MRenderUtil::exactFileTextureName ( const MString baseName,
bool  useFrameExt,
const MString currentFrameExt,
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]  baseName  a file name to be resolved
[in]  useFrameExt  use frame extension for image file name
[in]  currentFrameExt  specify a frame extension if useFrameExt is used.
[out]  ReturnStatus  status code
Returns:
  • true if the file pathname was successfully resolved.
  • false if the pathname could not be resolved.
Status Codes:

MString MRenderUtil::convertPsdFile ( const MObject fileNode,
const bool &  state = 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]  fileNode  a file texture node
[out]  ReturnStatus  status 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:

MString MRenderUtil::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]  imagePlaneNode  an image plane node
[out]  ReturnStatus  status 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:

bool MRenderUtil::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]  objectPath  Path of object to test
[out]  ReturnStatus  Status code
Returns:
true if the object is in the current render layer.
Status Codes:

MRenderUtil::MRenderPass MRenderUtil::renderPass ( void   )  [static]

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

Returns:

MString MRenderUtil::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 MRenderUtil::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 MRenderUtil::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]  lightBlindData  The reference to the aLightBlindData attribute of the current light being evaluated
[in]  lightDirection  The direction of the light being evaluated
[in]  pointCamera  The position of the camera
[in]  normal  The surface normal
[in]  lightBackFace  Is the back face being lit, true or false.
[out]  ReturnStatus  Status code
Examples:

MFloatVector MRenderUtil::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]  lightBlindData  The reference to the aLightBlindData attribute of the current light being evaluated
[in]  lightDirection  The direction of the light being evaluated
[in]  pointCamera  The position of the camera
[in]  normal  The surface normal
[in]  rayDirection  The direction of the current intersection ray in camera space
[out]  ReturnStatus  Status code
Examples:

float MRenderUtil::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]  lightBlindData  The reference to the aLightBlindData attribute of the current light being evaluated
[in]  pointCamera  The position of the camera
[in]  normal  The surface normal
[in]  lightBackFace  Is the back face being lit, true or false.
[out]  ReturnStatus  Status code
Examples:

float MRenderUtil::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]  lightBlindData  The reference to the aLightBlindData attribute of the current light being evaluated
[in]  lightDirection  The direction of the light being evaluated
[in]  pointCamera  The position of the camera
[in]  rayDirection  The direction of the current intersection ray in camera space
[in]  lightBackFace  Is the back face being lit, true or false.
[out]  ReturnStatus  Status code

void MRenderUtil::sendRenderProgressInfo ( const MString pixFile,
int  percentageDone  
) [static]

This utility function sends batch rendering status to Maya

Parameters:
[in]  pixFile  File name of the last rendered batch image
[in]  percentageDone  percentage rendered

void MRenderUtil::getCommonRenderSettings ( MCommonRenderSettingsData mrgData  )  [static]

Fill the set of common render setting values

MStatus MRenderUtil::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]  objectId  The sample object id to look-up
[in]  item  The corresponding item for the id
Returns:
Status Code
Examples:

Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6