#include <MViewport2Renderer.h>
Main interface class to the Viewport 2.0 renderer.
Public Types | |
enum | MGPUMemType { kMemTexture, kMemAll } |
GPU memory type. More... | |
typedef void(* | NotificationCallback) (MDrawContext &context, void *clientData) |
Definition for callback function for addNotification() | |
Public Member Functions | |
::MHWRender::DrawAPI | drawAPI () const |
Returns the current drawing API. More... | |
bool | drawAPIIsOpenGL () const |
Method will indicate whether the current drawing API is OpenGL or not. More... | |
unsigned int | drawAPIVersion () const |
Method will return the version of drawing API. More... | |
void * | GPUDeviceHandle () const |
Method will return a pointer to the GPU "device". More... | |
unsigned int | GPUmaximumVertexBufferSize () const |
Method to return the maximum number of vertices allowed in a vertex buffer by the GPU device. More... | |
unsigned int | GPUmaximumPrimitiveCount () const |
Method to return the maximum number of primitives that can be drawn per draw call by the GPU device. More... | |
void | GPUmaximumOutputTargetSize (unsigned int &w, unsigned int &h) const |
Retrieve the maximum allowable dimensions for output target by the GPU device. More... | |
MInt64 | GPUtotalMemorySize () const |
Retrieve the total amount of memory on the GPU device in bytes. More... | |
MInt64 | GPUUsedMemorySize (MGPUMemType type) const |
Retrieve the amount of Maya occupied GPU memory in bytes. More... | |
MFragmentManager * | getFragmentManager () const |
Access the fragment manager. More... | |
const MShaderManager * | getShaderManager () const |
Access the shader manager. More... | |
const MRenderTargetManager * | getRenderTargetManager () const |
Access the render target manager. More... | |
bool | copyTargetToScreen (const MRenderTarget *renderTarget) |
Copy a render target to the screen. More... | |
bool | render (const MString &sourceName, MRenderTarget **targets, unsigned int count) |
Render source view into render targets. More... | |
MTextureManager * | getTextureManager () const |
Access the texture manager. More... | |
MStatus | registerOverride (const MRenderOverride *roverride) |
Register the override as being usable by the renderer. More... | |
MStatus | deregisterOverride (const MRenderOverride *roverride) |
Deregister an existing render override on the renderer. More... | |
const MRenderOverride * | findRenderOverride (const MString &name) |
Return a reference to an existing render override registered with the renderer. More... | |
const MString | activeRenderOverride () const |
Get the name of the active override. More... | |
unsigned int | renderOverrideCount () |
Get the number of registered render overrides. More... | |
MStatus | setRenderOverrideName (const MString &name) |
Set the name of a render override (MHWRender::MRenderOverride) for batch rendering. More... | |
MString | renderOverrideName (MStatus *ReturnStatus=NULL) const |
Get the current render override name used for batch rendering. More... | |
MStatus | registerScriptCallback (MRenderScriptCallback *callback) |
Register a MRenderScriptCallback that can be then from a script fragment. More... | |
MStatus | deregisterScriptCallback (MRenderScriptCallback *callback) |
Deregister a MRenderScriptCallback and delete the registered instance. More... | |
MStatus | holdGPUMemory (MInt64 sizeInBytes, MInt64 *evictedGPUMemSize=NULL) |
Inform Maya that the total amount of GPU memory allocated by a plug-in is increasing by sizeInBytes. More... | |
MStatus | releaseGPUMemory (MInt64 sizeInBytes) |
Inform Maya that the total amount of GPU memory allocated by a plug-in is decreasing by sizeInBytes. More... | |
void | getStandardViewportOperations (MRenderOperationList &operations) const |
Return a list of new MRenderOperations representing the standard viewport pipeline. More... | |
void | setOutputTargetOverrideSize (unsigned int w, unsigned int h) |
This method allows rendering to occur to an offscreen target which differs from the interactive 3d viewport size. More... | |
void | getOutputTargetOverrideSize (int &w, int &h) |
Get the override dimensions set for the final output target. More... | |
void | unsetOutputTargetOverrideSize () |
Will unset any override dimensions set fot the final output target. More... | |
MStatus | outputTargetSize (unsigned int &w, unsigned int &h) const |
Return the current dimensions for the output target. More... | |
bool | setLightRequiresShadows (MObject obj, bool flag) |
The Viewport 2.0 renderer has a light limit option which is used to determine the number of lights used for computing illumination. More... | |
MStatus | addNotification (NotificationCallback notification, const MString &name, const MString semanticLocation, void *clientData) |
Add a notification callback to the rendering pipeline. More... | |
MStatus | removeNotification (const MString &name, const MString &semanticLocation) |
Remove a notification operation from the rendering pipeline. More... | |
unsigned int | notificationCount (const MString &semanticLocation) const |
Returns the number of notifications that have been set for a given semantic location. More... | |
bool | presentOnScreen () const |
Returns whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode. More... | |
void | setPresentOnScreen (bool val) |
Set whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode. More... | |
bool | useGradient () const |
Returns whether a gradient is being used to clear the background color. More... | |
MColor | clearColor () const |
Returns the first clear color. More... | |
MColor | clearColor2 () const |
Return the second clear color. More... | |
Static Public Member Functions | |
static MRenderer * | theRenderer (bool initializeRenderer=true) |
Returns a static pointer to the renderer. More... | |
static void | disableChangeManagementUntilNextRefresh () |
Calling this method will cause Viewport 2.0 to stop processing all changes to the Maya scene until the next viewport refresh. More... | |
static void | setGeometryDrawDirty (MObject obj, bool topologyChanged=true) |
Notify the Viewport 2.0 renderer that the geometry (size, shape, etc.) of obj has changed, causing the object to be updated in the viewport. More... | |
static void | needEvaluateAllLights () |
Notify the Viewport 2.0 renderer that it should evaluate all lights marked dirty, regardless of the light limit. More... | |
static void | setLightsAndShadowsDirty () |
Notify the Viewport 2.0 renderer that something has changed which requires re-evaluation of lighting and shadows. More... | |
enum MGPUMemType |
|
static |
Returns a static pointer to the renderer.
[in] | initializeRenderer | Fully initialize the renderer. |
When requesting the renderer to fully initialize, the internal renderer will be created and initialized. In some cases, a plugin may only want to access the renderer without having to initialize it. This can be useful for plugins that are auto-loaded when Maya start, and only need an access to the renderer to register their render overrides.
MHWRender::DrawAPI drawAPI | ( | ) | const |
Returns the current drawing API.
Returns 'kNone' if the renderer is not initialized.
bool drawAPIIsOpenGL | ( | ) | const |
Method will indicate whether the current drawing API is OpenGL or not.
unsigned int drawAPIVersion | ( | ) | const |
Method will return the version of drawing API.
void * GPUDeviceHandle | ( | ) | const |
Method will return a pointer to the GPU "device".
In the case that the drawing API is OpenGL then the "device" is a handle to an OpenGL context. In the case that the drawing API is DirectX then the "device" is a pointer to a DirectX device.
It is imperative that when a programmer makes any modifications to the device or context that the pre-modified state always be restored after the changes are no longer required. If this is not done then Maya's internal state tracking system will become inconsistent. This can result in unpredictable rendering behaviour.
If the renderer has not been initialized a NULL pointer will be returned.
unsigned int GPUmaximumVertexBufferSize | ( | ) | const |
Method to return the maximum number of vertices allowed in a vertex buffer by the GPU device.
unsigned int GPUmaximumPrimitiveCount | ( | ) | const |
Method to return the maximum number of primitives that can be drawn per draw call by the GPU device.
void GPUmaximumOutputTargetSize | ( | unsigned int & | w, |
unsigned int & | h | ||
) | const |
Retrieve the maximum allowable dimensions for output target by the GPU device.
These dimensions are not directly tied to the on-screen display resolution.
[out] | w | Maximum width |
[out] | h | Maximum height |
MInt64 GPUtotalMemorySize | ( | ) | const |
Retrieve the total amount of memory on the GPU device in bytes.
MInt64 GPUUsedMemorySize | ( | MGPUMemType | type | ) | const |
Retrieve the amount of Maya occupied GPU memory in bytes.
This size is not the accurate gpu memory current in use queried from system, but the number that tracked and used by Maya.
[in] | type | The type of GPU memory for query. |
kMemTexture returns the texture gpu memory used by Maya. kMemAll returns the total gpu memory used by Maya.
MFragmentManager * getFragmentManager | ( | ) | const |
Access the fragment manager.
const MShaderManager * getShaderManager | ( | ) | const |
Access the shader manager.
The shader manager can be used to produce MShaderInstance objects which may be assigned to MRenderItem objects by implementations of MPxGeometryOverride.
const MRenderTargetManager * getRenderTargetManager | ( | ) | const |
Access the render target manager.
The render target manager can be used to produce MRenderTarget objects which may be assigned to MRenderOperation objects as output target overrides.
bool copyTargetToScreen | ( | const MRenderTarget * | renderTarget | ) |
Copy a render target to the screen.
If the target's dimensions are not the same as the active viewport it will be scaled up or down as necessary to fill the entire viewport.
[in] | renderTarget | Render target to copy. |
bool render | ( | const MString & | sourceName, |
MRenderTarget ** | targets, | ||
unsigned int | count | ||
) |
Render source view into render targets.
[in] | sourceName | The name of the source view want to render. |
[in] | targets | The render target list want to render into. |
[in] | count | The number of the targets |
MTextureManager * getTextureManager | ( | ) | const |
Access the texture manager.
The texture manager can be used to acquire texture
MStatus registerOverride | ( | const MRenderOverride * | roverride | ) |
Register the override as being usable by the renderer.
If the override is already registered it will not be registered again.
[in] | roverride | Rendering override to be registered. |
MStatus deregisterOverride | ( | const MRenderOverride * | roverride | ) |
Deregister an existing render override on the renderer.
The renderer will remove this override from it's list of registered overrides.
[in] | roverride | Rendering override to be deregistered. |
const MRenderOverride * findRenderOverride | ( | const MString & | name | ) |
Return a reference to an existing render override registered with the renderer.
[in] | name | Name of override to find |
const MString activeRenderOverride | ( | ) | const |
Get the name of the active override.
There can only be one active override at any given time and that override must exist be registered with the renderer.
unsigned int renderOverrideCount | ( | ) |
Get the number of registered render overrides.
Set the name of a render override (MHWRender::MRenderOverride) for batch rendering.
[in] | name | Name of the override. |
Get the current render override name used for batch rendering.
If there is no override then an empty string will be returned
[out] | ReturnStatus | return status. |
MStatus registerScriptCallback | ( | MRenderScriptCallback * | callback | ) |
Register a MRenderScriptCallback that can be then from a script fragment.
[in] | callback | An instance of the callback class to register. |
MStatus deregisterScriptCallback | ( | MRenderScriptCallback * | callback | ) |
Deregister a MRenderScriptCallback and delete the registered instance.
The callback will no longer be callable from a script fragment once deregistered.
[in] | callback | An instance of the callback class to register. |
MStatus holdGPUMemory | ( | MInt64 | sizeInBytes, |
MInt64 * | evictedGPUMemSize = NULL |
||
) |
Inform Maya that the total amount of GPU memory allocated by a plug-in is increasing by sizeInBytes.
To avoid running out of GPU memory Maya may move buffers allocated by Maya from GPU memory to system memory. This system relies on Maya accurately tracking the amount of GPU memory being used. User plug-ins can log their memory usage using holdGPUMemory and releaseGPUMemory.
Maya has no ability to move user allocated GPU buffers to system memory, so all user allocated buffers take priority over any Maya allocated buffer. For this reason GPU buffers which are unlikely to be re-used should be deallocated immediately rather than held.
To prevent a GPU buffer allocated by Maya from being moved to system memory see MVertexBuffer::lockResourceHandle().
A call to holdGPUMemory may cause Maya to move buffers allocated by Maya from GPU memory to system memory. This may negatively impact overall performance in two ways. First, the call to holdGPUMemory itself may take a significant amount of time to copy the GPU buffer. Second, future rendering calls which rely on that buffer will be slower because resources must be moved from system memory to GPU memory for rendering.
If a non-null evictedGPUMemSize is given, it will be set to the size of GPU memory moved to system memory during this API call. evictedGPUMemSize of zero does not mean the call failed, it just means that we didn't need to evict any internal buffers from GPU to system.
[in] | sizeInBytes | The size of the allocation being held in bytes |
[out] | evictedGPUMemSize | The size of GPU memory moved to system memory |
MStatus releaseGPUMemory | ( | MInt64 | sizeInBytes | ) |
Inform Maya that the total amount of GPU memory allocated by a plug-in is decreasing by sizeInBytes.
See MRenderer::holdGPUMemory for more information.
[in] | sizeInBytes | The size of the allocation being released in bytes |
void getStandardViewportOperations | ( | MRenderOperationList & | operations | ) | const |
Return a list of new MRenderOperations representing the standard viewport pipeline.
The list is not cleared by this method before it is filled. If any operation already exist in the list the standard operations will be appended to the end of the list.
[out] | operations | The operation list that will be populated with standard operations. |
void setOutputTargetOverrideSize | ( | unsigned int | w, |
unsigned int | h | ||
) |
This method allows rendering to occur to an offscreen target which differs from the interactive 3d viewport size.
The general purpose for this method is usage in conjunction with target read-back used for capturing sequences of images to disk. The key additional option is the ability to explicitly set the output target size as opposed to relying on attempting to resize a viewport to get an appropriate size.
For this purpose, it can be used in conjunction with a post render notification via the MRenderer::addNotification() interface.
For example the following can be done:
Note that when the override is no longer required the method MRenderer::unsetOutputTargetOverrideSize() should be called.
The maximum allowable target dimensions can be queried using the MRenderer::GPUmaximumOutputTargetSize() method.
This override affects neither batch rendering nor playblast which have their own explicit output target size controls.
[in] | w | Width of the output target |
[in] | h | Height of the output target |
void getOutputTargetOverrideSize | ( | int & | w, |
int & | h | ||
) |
Get the override dimensions set for the final output target.
If the values have never been set or if MRenderer::unsetOutputTargetOverrideSize() is used to clear the values then the dimensions returned with be (-1,-1) respectively for the width and height values.
[out] | w | Width of the output target. -1 if not set. |
[out] | h | Height of the output target. -1 if not set. |
void unsetOutputTargetOverrideSize | ( | ) |
Will unset any override dimensions set fot the final output target.
The values stored will be set to (-1,-1) respectively for width and height
MStatus outputTargetSize | ( | unsigned int & | w, |
unsigned int & | h | ||
) | const |
Return the current dimensions for the output target.
[out] | w | Width of the output target |
[out] | h | Height of the output target |
|
static |
Calling this method will cause Viewport 2.0 to stop processing all changes to the Maya scene until the next viewport refresh.
Upon the next viewport refresh, all existing scene information (geometry, textures, shaders, etc.) stored for Viewport 2.0 will be deleted and then rebuilt.
This method can be used to prevent overhead from Viewport 2.0 from affecting the performance of complex scene operations which change large parts of the scene without needing the viewport to update.
This method may only be called from the main thread.
|
static |
Notify the Viewport 2.0 renderer that the geometry (size, shape, etc.) of obj has changed, causing the object to be updated in the viewport.
Note that this method does NOT perform any DG evaluation when it is called. This method is an extention of the dirty propagation system. It adds obj to the list of objects which must be updated before the next frame is rendered. The actual evaluation does not occur until the next viewport refresh. This method is threadsafe. The viewport refresh will occur asynchronously. Multiple calls to this method will get merged. It's not necessary to call this method when assigning new material, since Maya automatically tracks material assignment.
[in] | obj | DAG object which has been modified. |
[in] | topologyChanged | has the object topology changed |
|
static |
Notify the Viewport 2.0 renderer that it should evaluate all lights marked dirty, regardless of the light limit.
For example, if there are 8 lights accessible because of the Viewport 2.0 light limit option, Only the first 8 non-ambient lights created will be evaluated. Call this method to instruct Viewport 2.0 to evaluate all dirty lights regardless of the light limit option.
Note that this method does NOT perform any DG evaluation when it is called. The actual evaluation does not occur until the next viewport refresh. This method is threadsafe. The viewport refresh will occur asynchronously. Multiple calls to this method will get merged.
Call this method may decrease performance in Viewport 2.0 during the next viewport refresh. Once this method is called, all unused lights that are marked dirty will be evaluated in the next viewport refresh.
An example application of this method is to obtain light information while ignoring the light limit. If this method is not called, information for unused lights cannot be obtained via MDrawContext, even if LightFilter is set to kFilteredToLightLimit. This is because unused lights are not evaluated automatically by Viewport 2.0 by default.
|
static |
Notify the Viewport 2.0 renderer that something has changed which requires re-evaluation of lighting and shadows.
This will trigger an update of all active lights in the scene which will also force a recomputation of all active shadow maps.
Note that this method does NOT perform any DG evaluation when it is called. This method is an extention of the dirty propagation system. It simply marks all lights as needing to be updated before the next frame is rendered. The actual evaluation does not occur until the next viewport refresh. This method is threadsafe. The viewport refresh will occur asynchronously. Multiple calls to this method will get merged.
An example use of this method would be for advanced shaders which alter the geometry of objects through displacement and thus would alter the shadowing caused by objects that use the shader. Since the geometry of the object itself is not changing Maya cannot automatically update the lights and shadows. Thus the plug-in must mark them dirty manually.
bool setLightRequiresShadows | ( | MObject | object, |
bool | flag | ||
) |
The Viewport 2.0 renderer has a light limit option which is used to determine the number of lights used for computing illumination.
If the light is not used for illumination then the associated shadow map contents will not be computed.
This method allows for plug-in writers to indicate that the shadow map contents for a given light are required, regardless of the light limit.
The method does not force a shadow map evaluation, nor does it mark the shadow map contents as being dirty. Instead, the next time that shadow maps require updating, the renderer will only ensure that the shadow maps for the given light are recomputed as necessary.
The contents of the shadow map may not always require an update. For example the light contents may already be up-to-date, or renderer options may indicate to not render with shadows enabled. In cases like this no additional action will be performed.
[in] | object | Light to request shadow update for |
[in] | flag | Indicate if an update is requested. When set to true a request is added, and when set false any existing request is removed. |
MStatus addNotification | ( | NotificationCallback | notification, |
const MString & | name, | ||
const MString | semanticLocation, | ||
void * | clientData | ||
) |
Add a notification callback to the rendering pipeline.
If a notification with the same name and location has already been specified then no new notification will be added.
For the common case, when no MRenderOverride is specified, there will be one scene pass per render. The basic order of rendering would be:
If there are multiple scene passes for a given render then notifications specified using the MPassContext::kBeginRenderSemantic semantic will occur before the execution of the first scene pass. This would occur just before any notifications associated with the MPassContext::kBeginSceneRenderSemantic semantic. The basic order of rendering would be:
[in] | notification | Notification callback |
[in] | name | Unique name for the notification |
[in] | semanticLocation | Location in pipeline to invoke callback from. The only valid values are currently:
|
[in] | clientData | Optional client data. The caller is responsible for maintaining this data. |
Remove a notification operation from the rendering pipeline.
If a notification with the same name and semantic location exists then the notification will be removed.
[in] | name | Name of the notification |
[in] | semanticLocation | Location in the pipeline that the notification was added to. See addNotification(). |
unsigned int notificationCount | ( | const MString & | semanticLocation | ) | const |
Returns the number of notifications that have been set for a given semantic location.
[in] | semanticLocation | Location in the pipeline that the notification was added to. See addNotification(). |
bool presentOnScreen | ( | ) | const |
Returns whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode.
By default Maya will always update on-screen buffers when in interactive mode.
void setPresentOnScreen | ( | bool | val | ) |
Set whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode.
This option will take effect on the next refresh of an on-screen buffer.
[in] | val | Presentation option. |
bool useGradient | ( | ) | const |
Returns whether a gradient is being used to clear the background color.
MColor clearColor | ( | ) | const |
Returns the first clear color.
This will be the color used at the top of the background gradient if a color gradient is specified.
MColor clearColor2 | ( | ) | const |
Return the second clear color.
This will be the color used at the botom of the background gradient if a color gradient is specified.