Python API 2.0 Reference
|
Public Member Functions | |
def | __init__ () |
def | activateKey () |
def | addGeometryRequirement () |
def | addGeometryRequirements () |
def | addIndexingRequirement () |
def | addShaderSignature () |
def | boundingBoxExtraScale () |
def | draw () |
def | drawGeometry () |
def | endUpdate () |
def | handlesConsolidatedGeometry () |
def | handlesDraw () |
def | initialize () |
def | initialize2 () |
def | isTransparent () |
def | nonTexturedShaderInstance () |
def | overridesDrawState () |
def | overridesNonMaterialItems () |
def | rebuildAlways () |
def | setGeometryRequirements () |
def | shaderInstance () |
def | supportedDrawAPIs () |
def | supportsAdvancedTransparency () |
def | terminateKey () |
def | updateDG () |
def | updateDevice () |
Static Public Member Functions | |
def | __new__ () |
Base class for user defined shading effect draw overrides.
def OpenMayaRender.MPxShaderOverride.__init__ | ( | ) |
Initialize self. See help(type(self)) for accurate signature.
|
static |
Create and return a new object. See help(type) for accurate signature.
def OpenMayaRender.MPxShaderOverride.activateKey | ( | ) |
activateKey(context, key) -> self This is the activateKey callback. This method is called during the draw phase before invoking any draw() callback that are sharing a common shader key. The default implementation is empty.
def OpenMayaRender.MPxShaderOverride.addGeometryRequirement | ( | ) |
addGeometryRequirement(MVertexBufferDescriptor) -> self During the initialization phase the geometry requirements for the shading effect can be updated. The update is accomplished by calling this method once for each new data stream that needs to be added to the list of requirements. If the geometry has multiple fields of the same type associated with it (e.g. multiple UV sets) the 'name' attribute of the vertex descriptor can be used to select the desired one. If that member is empty or does not match any of the fields then the default field of that type will be used.
def OpenMayaRender.MPxShaderOverride.addGeometryRequirements | ( | ) |
addGeometryRequirements(MVertexBufferDescriptorList) -> self During the initialization phase the geometry requirements for the shading effect can be updated. The update is accomplished by calling this method with a list containing descriptions of all data streams that are required by the shader. If the geometry has multiple fields of the same type associated with it (e.g. multiple UV sets) the 'name' attribute of the vertex descriptor can be used to select the desired one. If that member is empty or does not match any of the fields then the default field of that type will be used. This method will attempt to add as many requirements as possible from the list, skipping invalid ones. If kInvalidParameter is returned it means at least one requirement failed to be added.
def OpenMayaRender.MPxShaderOverride.addIndexingRequirement | ( | ) |
addIndexingRequirement(MIndexBufferDescriptor) -> self During the initialization phase the indexing requirements for the shading effect can be updated. The update is accomplished by calling this method once for each new index stream required by the shader. A shader override can specify the type of primitive it supports. If the shader relies on a special primitive type like kPatch it should use this method to indicate that requirement to the system. Not all fields on the MIndexBufferDescriptor need to be filled in when using this method. Only the name(), primitive(), and primitiveStride() values are important for a shader to report as requirements. The primitive type must be specified if the shader requires a primitive type different then a standard point, line, or triangle list or strip. The primitiveStride must be specified if using the kPatch primitive type. Valid values range from 1 - 32. The name can be specified to trigger a custom MPxPrimitiveGenerator plugin to be used to produce the desired primitive tessellation. When requesting custom primitives you should register an MPxPrimitiveGenerator that knows how to produce the custom primitive needed by the shader.
def OpenMayaRender.MPxShaderOverride.addShaderSignature | ( | ) |
addShaderSignature(signature, signatureSize) -> selfaddShaderSignature(MShaderInstance) -> self During the initialization phase, the "signature" for the shader may be set. Certain Draw APIs (like DirectX 11) require a signature to allow a shading effect to be properly activated. The signature will be used if the override uses MPxShaderOverride.drawGeometry() in the draw phase in order to perform drawing. If drawing is done manually, adding a shader signature is not necessary.
def OpenMayaRender.MPxShaderOverride.boundingBoxExtraScale | ( | ) |
boundingBoxExtraScale() -> float Returns the Extra scale factor. Override this method to supply an extra scale factor to be applied to the object space bounding box of any objects which use the shader associated with this override. This is to allow the shader to indicate that the bounding box should be bigger than just the base geometry; normally due to shading effects like displacement. Note that the value returned here will only be used to put a lower bound on the extra scale applied to the bounding box. It may be made larger due to the demands of other shaders associated with the object. This method will be called any time a change occurs which may affect the bounding box of associated objects. It is acceptable to access the Maya dependency graph within calls to this method as it will never be called during draw. The default implementation returns the unit scale factor (1.0).
def OpenMayaRender.MPxShaderOverride.draw | ( | ) |
draw(context, renderItemList) -> bool This is the draw callback, the method is called during the draw phase. The expected implementation of this method is to do shader setup and then call drawGeometry() to allow Maya to handle the actual geometry drawing. It is however possible to do all shader setup and geometry draw here directly by accessing the hardware resource handles for geometry and index buffers through the geometry associated with each render item in the render item list. No dependency graph evaluation should occur during this phase. If data from Maya is needed here it must be cached on this object (or elsewhere) during the update phase. This method should return True on successful draw. If False is returned, Maya will attempt to draw using the default internal draw mechanism. Information about the current GPU state may be accessed through the MDrawContext object passed to this method. The MRenderItemList object contains one render item for each object that is meant to be drawn by this method. * context [IN/OUT] (MDrawContext) - The current draw context * renderItemList (MRenderItemList) - The list of renderable items to draw Returns True if draw was successful, False otherwise.
def OpenMayaRender.MPxShaderOverride.drawGeometry | ( | ) |
drawGeometry(MDrawContext) -> self This method may be called from draw() and will cause Maya to immediately draw the current geometry using the current state of the draw API.
def OpenMayaRender.MPxShaderOverride.endUpdate | ( | ) |
endUpdate() -> self This is the final part of the update phase. This method is called by Maya to allow the plugin to clean up any data or state from the previous update stages. No dependency graph evaluation, nor graphics device access should be performed during this phase.
def OpenMayaRender.MPxShaderOverride.handlesConsolidatedGeometry | ( | ) |
handlesConsolidatedGeometry() -> bool Returns True if the shader instance should disable the consolidation for the geometry it is applied to. Override this method if the shader instance should disable the consolidation for the geometry it is applied to.This is to prevent inconsistency between consolidated and non-consolidated geometry, particularly useful for shading effects that compute displacement based on the World position. The default implementation returns true indicating that the shader instance should not be disable the consolidation of the geometry.
def OpenMayaRender.MPxShaderOverride.handlesDraw | ( | ) |
handlesDraw(context) -> bool Returns True if shader handles drawing. This method indicates whether the shader will handle the drawing based on the context passed in. The default implementation will check the pass context. If the pass semantic is specified to be a color pass and the pass has no shader override (MPassContext.hasShaderOverride() returns False) then this method will return True.
def OpenMayaRender.MPxShaderOverride.initialize | ( | ) |
initialize(shader) -> string initialize(initContext, initFeedback) -> string Initialization occurs when Maya determines that the hardware shader needs to be rebuilt. Any initialization work may be performed here. Also, this is the only time that calls to addGeometryRequirement() may occur. Note: There are two versions of the initialize method. Derived classes should override exactly one of them. The default implementation returns a constant string.
def OpenMayaRender.MPxShaderOverride.initialize2 | ( | ) |
initialize2(initContext) -> string, userData Initialization occurs when Maya determines that the hardware shader needs to be rebuilt. Any initialization work may be performed here. Also, this is the only time that calls to addGeometryRequirement() may occur. The default implementation returns a string and None MUserData
def OpenMayaRender.MPxShaderOverride.isTransparent | ( | ) |
isTransparent() -> bool Returns True if semi-transparent drawing should occur. During the update phase the override will be called to return whether it will be drawing with semi-transparency. This call occurs after updateDevice() which allows for any device evaluation to occur to determine the transparency state. The default return value is False.
def OpenMayaRender.MPxShaderOverride.nonTexturedShaderInstance | ( | ) |
nonTexturedShaderInstance() -> MShaderInstancenonTexturedShaderInstance() -> (MShaderInstance, bool) Returns an override shader instance to be used when drawing in non-textured mode. If None is returned an internally defined non-modifiable shader instance is used. A second optional boolean value 'monitorNode' can be returned as well which will indicate that the associated shader node requires monitoring to call back to the override during the update phase. Note that if transparency is required at initialization time then the method setIsTransparent() should be called within this method. The default implementation returns None indicating that no shader instance will be used.
def OpenMayaRender.MPxShaderOverride.overridesDrawState | ( | ) |
overridesDrawState() -> bool Returns True if the override overrides the draw state. During the draw phase this method will be called to determine whether the override will override the draw state when drawing. This call occurs after updateDevice() which allows for any device evaluation to occur to determine if the override will override the draw state. The Viewport 2.0 renderer will skip setting the draw state for plugins that will override the draw state when drawing. Note that the MPxShaderOverride.terminateKey() should still return the draw state to the value it had when activateKey was called. The default return value is False.
def OpenMayaRender.MPxShaderOverride.overridesNonMaterialItems | ( | ) |
overridesNonMaterialItems() -> bool Returns True if the shader instance should also be used to render non material items. Override this method if the shader instance should also be used to render non material items such as the wireframe and the selected edges/vertices components. This is particularly useful for shading effects that compute displacement for which the object geometry will not match the rendered material, making selection difficult. The default implementation returns False indicating that the shader instance should not be used for non material items.
def OpenMayaRender.MPxShaderOverride.rebuildAlways | ( | ) |
rebuildAlways() -> bool Returns True if the shader and geometry should be rebuilt on every update. If this method returns True, it will force shader and geometry data to be rebuilt on any change to the shader. This may be necessary for shaders that request specific named data sets like UVs or CPVs. Any change to the required data set means that geometry needs to be rebuilt. The default return value is False.
def OpenMayaRender.MPxShaderOverride.setGeometryRequirements | ( | ) |
setGeometryRequirements(MShaderInstance) -> self During the initialization phase the geometry requirements for the shading effect can be updated. The update can be accomplished by calling this method with a shader instance (MShaderInstance). The geometry requirements are copied from the MShaderInstance and used as the current shading effect requirements. If there are any requirements already specified for the shading effect, they will be replaced. This method should not be used in conjunction with addGeometryRequirement() and addGeometryRequirements() methods. The reason is that when rendering the vertex format used must exactly match the one used for the shader instance. If any additional requirements are added, the geometry may not draw properly. The corresponding addShaderSignature() method, which takes an MShaderInstance as an input argument, should also be called during initialization if the utility method drawGeometry() is used by the plug-in.
def OpenMayaRender.MPxShaderOverride.shaderInstance | ( | ) |
shaderInstance() -> MShaderInstance Returns the Shader instance. Override this method if a shader instance (MShaderInstance) is to be used for drawing. The default implementation returns None indicating that no shader instance will be used.
def OpenMayaRender.MPxShaderOverride.supportedDrawAPIs | ( | ) |
supportedDrawAPIs() -> DrawAPI Returns The draw API supported by this override. Returns the draw API supported by this override. The returned value may be formed as the bitwise 'or' of render drawAPI elements to indicate that the override supports multiple draw APIs. See MRenderer.drawAPI(). This method returns 'MRender.kOpenGL' by default.
def OpenMayaRender.MPxShaderOverride.supportsAdvancedTransparency | ( | ) |
supportsAdvancedTransparency() -> bool Returns True if advanced tranparency algorithm is supported. During the update phase the override will be called to return whether it supports advanced transparency algorithms (such as depth peeling).
def OpenMayaRender.MPxShaderOverride.terminateKey | ( | ) |
terminateKey(context, key) -> self This is the terminateKey callback. This method is called during the draw phase after invoking draw() callbacks that are sharing a common shader key. The default implementation is empty.
def OpenMayaRender.MPxShaderOverride.updateDevice | ( | ) |
updateDevice() -> self This is the second part of the update phase. Perform any work required to update the shading effect which is related to accessing the underlying graphics device. This is the only place that the graphics device may be safely accessed other than at draw time.
def OpenMayaRender.MPxShaderOverride.updateDG | ( | ) |
updateDG(object) -> self This is the first part of the update phase. Perform any work required to update the shading effect which is related to evaluating the dependency graph. This should be the only place that dependency graph evaluation occurs. Data retrieved from Maya may be cached on the override for use in later stages.