C++ API Reference

Static class providing Render View API functions. More...

#include <MRenderView.h>

Static Public Member Functions

static bool doesRenderEditorExist ()
 Determines whether or not a Render View exists to receive image data. More...
 
static MStatus setCurrentCamera (MDagPath &camera)
 Informs the render client of the camera that will be performing the rendering. More...
 
static MStatus getRenderRegion (unsigned int &left, unsigned int &right, unsigned int &bottom, unsigned int &top)
 Retrieves the currently selected Render Region in Maya's Render View. More...
 
static MStatus startRender (unsigned int width, unsigned int height, bool doNotClearBackground=false, bool immediateFeedback=false)
 Informs the Render View that a full image render is about to begin. More...
 
static MStatus startRegionRender (unsigned int imageWidth, unsigned int imageHeight, unsigned int regionLeft, unsigned int regionRight, unsigned int regionBottom, unsigned int regionTop, bool doNotClearBackground=false, bool immediateFeedback=false)
 Informs the Render View that a region render is about to begin. More...
 
static MStatus updatePixels (unsigned int left, unsigned int right, unsigned int bottom, unsigned int top, RV_PIXEL *pPixels, bool isHdr=false, const unsigned int numberOfAOVs=0, const RV_AOV *const pAOVs=NULL)
 Sends a block of pixels to the Render View. More...
 
static MStatus refresh (unsigned int left, unsigned int right, unsigned int bottom, unsigned int top)
 Requests that the Render View refresh the display of a particular region of the displayed image. More...
 
static MStatus endRender ()
 Informs the Render View that the current render has completed. More...
 
static const char * className ()
 Returns the name of this class. More...
 

Detailed Description

Static class providing Render View API functions.

This class provides access to the Maya Render View. The class allows plugins to send image data to the Render View in the same way that the Maya renderer does. Either a "full render" or a "region render" can be performed. In a full render, the Render View expects to receive pixel data that fills the entire image, while a region render expects only updates to a specified image region.

Usage

To send an image to the Render View, use the following sequence of calls:

  1. Call doesRenderEditorExist() to make sure that a Render View exists. If this returns false, then Maya is operating in batch mode.
  2. Call setCurrentCamera() to specify the name of the camera that is being rendered.
  3. Call startRender() or startRegionRender() to inform the Render View that you are about to start sending either a full image or a region update. When region rendering, the getRenderRegion() method can be used to retrieve the currently selected marquee region in the Render View.
  4. The image or image region is sent to the Render View as a series of one or more tiles. For each tile, send the tile's image data using the updatePixels() method. Call the refresh() method to refresh the Render View after each tile has been sent.
  5. Call endRender() to signal the Render View that all image data has been sent.

Member Function Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN bool doesRenderEditorExist ( )
static

Determines whether or not a Render View exists to receive image data.

If this function returns false, then Maya is currently running in batch mode, so it would be pointless to try to send data to the Render View.

Returns
  • true if the Render View exists.
  • false otherwise.
Examples:
renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd/renderViewRenderCmd.cpp, and renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp.
MStatus setCurrentCamera ( MDagPath currentCamera)
static

Informs the render client of the camera that will be performing the rendering.

Parameters
[in]currentCameraCamera to be used in the render.
Returns
  • MS::kSuccess Operation was successful.
  • MS::kFailure Operation failed because no Render View existed.
Examples:
renderViewRenderCmd/renderViewRenderCmd.cpp, and renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp.
MStatus getRenderRegion ( unsigned int &  left,
unsigned int &  right,
unsigned int &  bottom,
unsigned int &  top 
)
static

Retrieves the currently selected Render Region in Maya's Render View.

The region extends from the bottom-left corner (left,bottom) to the upper-right corner (right,top) inclusive (i.e. the row y=top and column x=right are part of the region).

Parameters
[out]leftreceives the left extent of the region
[out]rightreceives the right extent of the region
[out]bottomreceives the bottom extent of the region
[out]topreceives the top extent of the region
Returns
  • MS::kSuccess Operation was successful, returned values are valid.
  • MS::kFailure Operation failed because no Render View existed.
Examples:
renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp.
MStatus startRender ( unsigned int  width,
unsigned int  height,
bool  doNotClearBackground = false,
bool  immediateFeedback = false 
)
static

Informs the Render View that a full image render is about to begin.

The entire Render View buffer will be cleared in anticipation of receiving an entire image.

Parameters
[in]widthwidth of the image to be sent to the Render View (must be greater than zero).
[in]heightheight of the image to be sent to the Render View (must be greater than zero).
[in]doNotClearBackgroundWhen true, the Render View is not cleared before starting to draw. Default (false) is to clear the Render View.
[in]immediateFeedbackWhen true, each call to refresh() will immediately redraw the Render View. Default (false) is to wait at least two seconds between redraws.
Returns
  • MS::kSuccess Operation was successful.
  • MS::kInvalidParameter Operation failed because the specified width or height was invalid.
  • MS::kFailure Operation failed because no Render View existed.
Examples:
renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, and renderViewRenderCmd/renderViewRenderCmd.cpp.
MStatus startRegionRender ( unsigned int  imageWidth,
unsigned int  imageHeight,
unsigned int  regionLeft,
unsigned int  regionRight,
unsigned int  regionBottom,
unsigned int  regionTop,
bool  doNotClearBackground = false,
bool  immediateFeedback = false 
)
static

Informs the Render View that a region render is about to begin.

The specified region will be cleared in anticipation of receiving new image data for it. The specified region must lie within the image region (0,0)->(imageWidth-1,imageHeight-1). The region 'left' coordinate must be less than the region 'right' coordinate, and the region 'bottom' coordinate must be less than the region 'top' coordinate.

Parameters
[in]imageWidthwidth of the image in which the region is embedded. (must be greater than zero).
[in]imageHeightheight of the image in which the region is embedded (must be greater than zero).
[in]regionLeftleft extent of the region.
[in]regionRightright extent of the region. The column x=regionRight is considered part of the region.
[in]regionBottombottom extent of the region.
[in]regionToptop extent of the region. The row y=regionTop is considered part of the region.
[in]doNotClearBackgroundWhen true, the Render View is not cleared before starting to draw. Default (false) is to clear the Render View.
[in]immediateFeedbackWhen true, each call to refresh() will immediately redraw the Render View. Default (false) is to wait at least two seconds between redraws.
Returns
  • MS::kSuccess Operation was successful.
  • MS::kInvalidParameter Operation failed because either the specified image width/height or the specified image region was invalid.
  • MS::kFailure Operation failed because no Render View existed.
Examples:
renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, and renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp.
MStatus updatePixels ( unsigned int  left,
unsigned int  right,
unsigned int  bottom,
unsigned int  top,
RV_PIXEL pPixels,
bool  isHdr = false,
const unsigned int  numberOfAOVs = 0,
const RV_AOV *const  pAOVs = NULL 
)
static

Sends a block of pixels to the Render View.

Pixel colors are represented as 4-channel floating point values. For low dynamic range images, color values are in standard RGB (sRGB) colorspace, and in the range (0,255.0). For high dynamic range (HDR) images, the range is unbounded, and values are in linear CIE XYZ color space, with the X, Y, and Z values stored respectively in the R, G and B fields of the RV_PIXEL structure. Alpha values for HDR images are expected to be in the range (0,1). Out of range alpha values are not clamped, and may behave unexpectedly.

Parameters
[in]leftleft extent of the update region.
[in]rightright extent of the update region. The column x=right is considered part of the region.
[in]bottombottom extent of the update region.
[in]toptop extent of the update region. The row y=regionTop is considered part of the region.
[in]pPixelsbuffer containing the pixel data for the image. The buffer should contain (right-left+1)*(top-bottom+1) pixels.
[in]isHdrindicates whether the image has high dynamic range
[in]numberOfAOVsindicates the number of arbitrary output variable (AOV) buffers (not yet implemented).
[in]pAOVsarray of RV_AOV objects. The height and width of each AOV must match pPixels (not yet implemented).
Returns
  • MS::kSuccess Operation was successful.
  • MS::kInvalidParameter Operation failed, either because the specified update region was invalid, or because the specified pixel buffer was NULL.
  • MS::kFailure Operation failed because no Render View existed.
Examples:
renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd/renderViewRenderCmd.cpp, and renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp.
MStatus refresh ( unsigned int  left,
unsigned int  right,
unsigned int  bottom,
unsigned int  top 
)
static

Requests that the Render View refresh the display of a particular region of the displayed image.

Parameters
[in]leftleft extent of the update region.
[in]rightright extent of the update region. The column x=right is considered part of the region.
[in]bottombottom extent of the update region.
[in]toptop extent of the update region. The row y=regionTop is considered part of the region.
Returns
  • MS::kSuccess Operation was successful.
  • MS::kInvalidParameter Operation failed, because the specified refresh region was invalid.
  • MS::kFailure Operation failed because no Render View existed.
Examples:
renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd/renderViewRenderCmd.cpp, and renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp.
MStatus endRender ( )
static

Informs the Render View that the current render has completed.

The Render View is refreshed and no further updates are accepted.

Returns
  • MS::kSuccess Operation was successful.
  • MS::kFailure Operation failed because no Render View existed.
Examples:
renderViewInteractiveRenderCmd/renderViewInteractiveRenderCmd.cpp, renderViewRenderCmd/renderViewRenderCmd.cpp, and renderViewRenderRegionCmd/renderViewRenderRegionCmd.cpp.
static const char* className ( )
inlinestatic

Returns the name of this class.

Returns
The name of this class.

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