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 ¤tFrameExt, MString &exactName, MStatus *ReturnStatus=NULL) |
This method is obsolete. More... | |
static bool | exactFileTextureName (const MString &baseName, bool useFrameExt, const MString ¤tFrameExt, 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 ¤tFrameExt, MStatus *ReturnStatus=NULL) |
This method is obsolete. More... | |
static MString | exactFileTextureName (const MString &baseName, bool useFrameExt, const MString ¤tFrameExt, 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... | |
Common API rendering functions.
MRenderUtil is a class which provides static API methods to access Maya's rendering functionalities.
enum MRenderState |
enum MRenderPass |
Defines the current pass of Maya.
|
static |
Returns an enumerated type specifying the current state of the Maya renderer.
|
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.
[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 |
|
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.
[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 |
|
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.
[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) |
|
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.
[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 |
|
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.
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.
[in] | absFileName | input file name |
[out] | ReturnStatus | status code |
|
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.
This method is not supported in Python. See the version which returns a string.
[in] | fileNode | a file texture node |
[out] | texturePath | returns an absolute pathname to the texture file referenced by the node. |
[out] | ReturnStatus | status code |
|
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]
The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.
This method is not supported in Python. See the version which returns a string.
[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 |
|
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.
This method is not supported in Python. See the version which returns a string.
[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. |
[in] | contextNodeFullName | full name of the file owner Node. |
[out] | exactName | resolved file name with absolute path |
[out] | ReturnStatus | status code |
|
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.
This method is not supported in Python.
[in] | fileNode | A file texture node |
[out] | tilePaths | Returns the set of absolute pathnames to the UV tiles for the given texture texture file node |
[out] | tilePositions | Returns the lower left coordinate of each tile in UV space. |
[out] | ReturnStatus | Status code |
|
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.
This method is not supported in Python. See the version which returns a string.
[in] | fileNode | a file texture node |
[out] | texturePath | returns an absolute pathname to the texture file referenced by the node. |
[in] | forExport | if 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] | ReturnStatus | status code |
|
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.
This method is not supported in Python. See the version which returns a string.
[in] | imagePlaneNode | an image plane node |
[out] | texturePath | returns an absolute pathname to the texture file referenced by the node. |
[out] | ReturnStatus | status code |
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.
[in] | fileNode | a file texture node |
[out] | ReturnStatus | status code |
|
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]
The function applies exactly the same logic that is used by the file texture node internally for resolving the image file path.
[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 |
|
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.
[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. |
[in] | contextNodeFullName | full name of the file owner Node. |
[out] | ReturnStatus | status code |
|
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.
[in] | fileNode | a file texture node |
[in] | forExport | if 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] | ReturnStatus | status code |
|
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.
[in] | imagePlaneNode | an image plane node |
[out] | ReturnStatus | status code |
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.
[in] | objectPath | Path of object to test |
[out] | ReturnStatus | Status code |
|
static |
Returns an enumerated type specifying the current pass the Maya renderer is executing.
|
static |
Returns the custom token string of the main beauty pass for use by renderers in file naming.
|
static |
Returns the name of the main beauty pass for use by renderers for token substitution.
|
static |
This utility function computes and returns the diffuse or lambertian reflectance for a given light source and surface.
[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 |
|
static |
This utility function computes and returns the vector corresponding to the point on the light source that provides the maximum specular reflection.
[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 |
|
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.
[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 |
|
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.
[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 |
|
static |
This utility function sends batch rendering status to Maya.
[in] | pixFile | File name of the last rendered batch image |
[in] | percentageDone | percentage rendered |
|
static |
Fill the set of common render setting values.
[out] | mrgData | Render settings. |
|
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.
[in] | objectId | The sample object id to look-up |
[in] | item | The corresponding item for the id |
|
static |
Returns the name of this class.
|
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.
[in] | texNode | texture node to evaluate. It doesn't need to be connected to anything. |
[in] | uCoords | array of u coordinate values |
[in] | vCoords | array of v coordinate values |
[out] | resultColors | if 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] | resultAlphas | if non-NULL, receives the outAlpha values evaluated from the texture at these same points. |
|
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.
|
static |
The size of Maya's noise table is a perfect cube.
This method returns the cubic root of the table size.
|
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.
[in] | index | The index to retrieve from the noise table |
|
static |
Generates continous non-repeating one dimensional noise based on Maya's internal noise table.
[in] | x | The one dimensional coordinate for which to generate noise |
|
static |
Generates continous non-repeating two dimensional noise based on Maya's internal noise table.
[in] | x | The x coordinate for which to generate noise |
[in] | y | The y coordinate for which to generate noise |
|
static |
Generates continous non-repeating three dimensional noise based on Maya's internal noise table.
[in] | x | The x coordinate for which to generate noise |
[in] | y | The y coordinate for which to generate noise |
[in] | z | The y coordinate for which to generate noise |
|
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).
[in] | x | The x coordinate for which to generate noise |
[in] | y | The y coordinate for which to generate noise |
[in] | z | The y coordinate for which to generate noise |
[in] | t | The time coordinate for which to generate noise |
[in] | numTimeSteps | Controls the repetition of the noise with respect to time |