Handling custom renderables for object overrides

Viewport 1.0 only interfaces

The Viewport 2.0 API only provides a rendering / drawing interface.

Pre-existing Viewport 1.0 interfaces should be used for selection and component handling. This includes methods such as MPxSurfaceShapeUI::select() and MPxSurfaceShapeUI::snap().

Drawing into the UV Editor is unchanged. The existing Viewport 1.0 methods should be used, as there are no Viewport 2.0 specific interfaces for doing the same; for example, methods such as MPxSurfaceShapeUI::drawUV()/MPxSurfaceShapeUI::canDrawUV().

Viewport 1.0 methods for overriding associated materials are not required for Viewport 2.0 rendering. This includes MPxSurfaceShapeUI::material() and MPxSurfaceShapeUI::materials().

Renderables (render items)

The renderable is the main element of concern.

For Viewport 1.0, these are represented as draw requests (MDrawRequest). For Viewport 2.0, the closest construct to this is a render item (MRenderItem). A collection of these can be thought of as representing the total set of renderables for an object.

For Viewport 1.0, there are no predefined MDrawRequests.

For Viewport 2.0, MRenderItems that represent drawing using the assigned material(s) for an object are provided. We call these material render items. Anything not predefined by the renderer is considered to be custom.

The Viewport 1.0 paradigm is to create and return draw requests to the appropriate collection and then explicitly draw the requests at draw time. The Viewport 2.0 paradigm is to create, update and/or selectively override existing render items and return them to the appropriate collection for geometry update and eventual internal drawing.

The persistent nature of render items entails considering up-front creation of the total set of render items that will be used.

Provided render items

Viewport 2.0 renderer maintains material and bounding box render items.

• For material render items, only geometry requirements filling is required.
• For bounding box render items, no additional coding is required.

It is possible, but not necessary, to override the shaders used for material render items. It is also possible to disable these render items and replace them with custom render items.

Note that the handling of objects that do not have any shader assignments is left up to the plug-in. In Viewport 1.0, the material interfaces return a default material. In Viewport 2.0, the fallback for non-plug-in objects is to show a wireframe. Because a default wireframe render item cannot be provided, this (or an alternative appropriate fallback) must be explicitly provided by the plug-in.

Custom render items

If only material and bounding box render items are provided, then the question arises as to when additional “custom” render items may be required. This is highly dependent on the type of plug-in being written, but one common situation is the rendering of non-material render items; another the overriding of existing material or bounding box drawing.

Handling change

Selection state changes generally imply a change in the color for a render item. There can be two approaches: either multiple render items can be created for each selection state; or, a single one with sufficient shader parameters can be used. If geometry is generally shared, then the inherent cost of having multiple items is small. If the draw mode differs, then a different render item is required. For example, a different item would be used for dormant versus active wireframe as the first only draws in wireframe mode, while the latter draws in all draw modes.

The actual control of colors can generally be handled by utilities such as MGeometryUtilities::wireframeColor(), which returns the correct color, taking into account current object state.

For object visibility, material render items are automatically handled, as are the UI render items. However, template status change can be considered to be a visibility change with respect to certain render items. For example, component render items should be manually disabled to be consistent with Maya’s internal behaviour. MGeometryUtilities::displayStatus() is a utility which is useful for checking status.

For draw overrides (exposed in the Attribute Editor Draw Overrides tab), template control needs to be handled as well as custom color overrides. The same utilities mentioned above may be used.

Display layers can invoke updates for templating, as well as color overrides.

Any additional items that are not controlled via Maya have its own internal plug-in logic and corresponding update logic. For example, adding the display of face centers could be an attribute on the node that drives the display of a custom render item to show these centers.

Geometry handling

Custom render items are named and thus there is a set of named render items to manage. There is also the possibly of the requirement for geometry streams of the same semantic but with different names.

For example, two streams of positions (semantic) may be required for the case where a material render item draw and a render item that draws face normal are required. The first could be named “My shaded item” and the second “My face center item”. The latter could call MRenderItem::setShader() with a custom stream name of “face center”.

Additionally, as no explicit association is given between streams and render items, it can sometimes be useful to name streams if it is required that they be used for specific custom render items. There are trade-offs, as each named stream may result in additional geometry data and indexing allocation being required. Also, geometry updates must handle the fact that stream naming is per render item. That is, it applies to all streams for an item. An example usage is given in 4.4.5.5 Basic component handling.

Figure 80

The figure above shows three render items on the left. The top-most item is for drawing face centers. It requires only positions and has a custom name of "face center". Next is an item to draw active vertices and requires positions and has a custom stream name of "Active Vertices". The last is a material render item which requires positions and normal. There are no custom names. When the final cumulative set of requirements comes back for which the override must provide geometry, there are descriptions for 4 streams of data required (MVertexBufferDescriptor): 3 position streams and one normal stream. The position streams could be shared for material and active vertex display.

No assumptions should be made as to when data is required, and as such, all requirements should always be fulfilled. The renderer may attempt to provide some default data if the appropriate data is not provided, but there is no guarantee that the appropriate data can be provided. For example, one viewport panel may require the data for a wireframe render item in addition to a shaded one if the viewport configuration has one panel in shaded mode and the other with wire-on-shaded mode enabled. The shaded render item may require tangents to be provided.

Custom UI drawing example

As an example, a plug-in can create custom render items for the following:

• Dormant wireframe draw
• Active wireframe draw
• Dormant vertex draw
• Active vertex draw
• Shaded template wireframe draw
• Proxy drawing when no shader is assigned to the DAG object

Figure 81

Green boxes represent areas that the plug-in would create and manage. White boxes are provided by the renderer.

The following are example parameters of the items illustrated above and their proposed update frequency:

• Depth priority: Uniqueness of the item depends on this parameter; so, would be set at creation time.
• Draw mode: Uniqueness of the item depends on this parameter; so, would be set at creation time. Just as the active and dormant wireframe items would be set to only show in wireframe mode, a shaded template wireframe item is specifically created to handle drawing of template wireframe when in shaded mode.
• Color: This is a shader parameter that can be dynamically set at render item update time. As an example, the color would update depending on the current object display status.

• Point size: For the same reasons as color, this can be dynamically set at render item update time.

The crescent “container” shows how logically both geometry and subscene override render items are collected into a set of render items. The main difference is that subscene override container classes are explicitly exposed in the API.

The following are some example user workflows and how the plug-in could handle their render items:

1. User goes into component selection mode while in shaded mode:
   1. The object is in highlight mode so the dormant wireframe item should be enabled and the color set appropriately.
   2. The dormant vertex render item should be enabled and the color set appropriately.
   3. The active wireframe item should be disabled.
   4. The active vertex item should be disabled.
   5. The shaded template item should be disabled.
   6. The shaded proxy item should be disabled.
      NOTE: The material shaded item is enabled internally, and was enabled when entering into shaded mode.
2. The user then selects some vertices:
   1. The active vertex item should be enabled. The active components should be parsed to set the appropriate indexing to show a subset of vertices.
3. The user switches back to object selection mode:
   1. Dormant and active vertex items are disabled.
   2. Active wireframe item is enabled.
   3. The dormant wireframe item is disabled.
4. The user switches to wireframe mode:
   1. “Nothing” needs to be done in the plug-in as the render items marked to draw in shaded mode are filtered out in the draw pipeline.
5. The user sets the object override to make the object template:
   1. If there are any custom material render items, they should be disabled. Provided material render items are automatically disabled.
   2. The dormant and active wireframe items should be disabled.
   3. The dormant vertex item should be disabled.
   4. The shaded template item should be enabled and set to the appropriate color depending on whether or not the object is active.

Figure 82

From top to bottom, and left to right are the five actions listed above, shown graphically. At all times, all the render items are retained with basic enabling and disabling occurring as well as possible parameter changes such as color. Items in green are enabled while all other render items are disabled.

Custom materials

If custom material rendering is required, then the level of integration is dependent on the interfaces that are used. The following table outlines the main trade-offs associated with each interface. Increased flexibility generally requires more work to be done by the plug-in writer. To a certain extent, simpler shaders can be maintained inside the geometry handler/override.

Fragment, Effects, and Stock are options available via the shader manager, and hence supported options are determined by the internal renderer. Shader Override is MPxShaderOverride.

When dealing with material items, there are generally render items that have “shaded” or “shaded and textured” draw modes being passed to an override. There can be 0 or more sets of these passed in, depending on the number of materials that are assigned to the DAG object.

Figure 83

In this example, a DAG object has 2 shaders assigned to different components on the DAG object. It is possible to have 4 “material” render items: one for each component shader to draw in “shaded” draw mode, and one for each component shader to draw in “shaded and textured” mode.

Parameters on these render items can be used as is, modified, or they can be disabled. If disabled, then the plug-in is responsible for providing replacements. If no replacement is provided, then the object appears to “disappear” when in shaded and/or textured modes. Depending on the type of replacement, different levels of integration may result.

When the shader handling complexity for certain render items reaches a point where an MPxShaderOverride is required, then the complexity of the geometry handler is reduced, and it only fulfills the geometry requirements for these render items.

For example, the plug-in may require only a built-in Blinn shader with some pre-set shading configuration that is fully integrated. A stock fragment shader can be used in this case. In another example, tessellation may be required for a hair shader. In this case, it is best to not control this from inside the geometry handler and instead create a custom MPxShaderOverride “hair shader node” which “feeds” render items to a custom “hair geometry node” override.

Figure 84

The various possible options are all shown at once.

The renderer provided (material) render item is shown uncoloured. There could be a mix of internal shaders and plug-in shaders used to derive these items. Some nodes may supply a custom fragment shader or a shader override may be associated. The geometry handler (override) receives these as non-custom render items.

Custom render items (in green) can be instantiated with shader instances which are created via the shader manager using fragment, stock or effects files interfaces.

UI Draw Manager

The MUIDrawManager class provides a convenience interface for queuing additional UI drawing that are generally not associated with being part of an object. The “drawables” which may be queued can be thought of as being roughly equivalent to render items.

A direct implication of using the manager is that the “drawables” are never persistent and as such, the number of drawables queued via this interface should be kept relatively small. If more items are required or the data content is large, then interfaces such as the mesh() call be used. Custom render items are otherwise recommended.

For example, for drawing a large number of vertices on a plug-in object, a custom render item would be recommended over drawing individual points in the draw manager. However for drawing a 3d or 2d label on an object, the draw manager would be a better choice.

One other aspect to consider is that the UI drawn via the manager may draw at a fixed place within the overall pipeline and with a more rigid set of pre-defined drawing properties.

Effects and context interaction

By default, render items used for UI drawing (lines, points) are excluded from scene effects such as screen-space ambient occlusion, motion blur, and depth-of-field. Additionally, they do not, in general, cast or receive shadows. Render items using internal material shader instances participate in these effects.

Effects drawing is performed within some drawing context.

Geometry overrides are never passed any context information and their behaviour is for the most part independent of context (shader callbacks being the exception). Subscene overrides are provided with context but only a frame context which does not provide access to a pass context. Thus, any items should work independently of the pass from which they are being called.

Viewport 1.0 / Viewport 2.0 comparison chart

Sample code

The apiMeshShape developer kit example takes into account a number of workflows related to UI handling as well as for proxy shader handling.

Figure 85

apiMeshShape sample scene in wireframe mode.

Figure 86

apiMeshShape sample scene in shaded mode.

The above snapshots demonstrate a number of different custom render items being used. All objects except the planes and the IK chain are drawn using the same plug-in. Included are:

• Dormant wire items :
  • blue wireframes using default dormant color
  • red and green wireframes using display layer color
  • black wireframe using “draw override” color
  • grey wireframe on template object in wireframe mode
  • pink wireframe on active-affected object (affected by IK chain)
• Active wire items:
  • White wireframe for lead object.
• Shaded template item:
  • grey wireframe in shaded mode
• Provided material:
  • Red, green, blue, pink Blinn and grey Lambert shaded items
• Proxy shaded item:
  • “Rainbow” colored color-per-vertex dashed line wireframe item

// Utility to set the color on a shader instance.
void setSolidColor(MHWRender::MShaderInstance* shaderInstance, const float *value)
{
  if (!shaderInstance)
	return;
  const MString colorParameterName = "solidColor";
  shaderInstance->setParameter(colorParameterName, value);
}

// ************************** Update during updateRenderItems() ******************
…
// Unique name for active wireframe
MString fSelectedWireframeItemName = “selectedWireframeName”;
// Create the item once. Use enable/disable toggle to control when it should
// be drawn (below)
MHWRender::MRenderItem* selectItem = NULL;
int index = list.indexOf( // list = MRenderItemList passed as an input argument
	fSelectedWireframeItemName,
	MHWRender::MGeometry::kLines, // Type of primitive is lines 
	MHWRender::MGeometry::kAll); // Draw in all display modes
if (index < 0)
{
	static const bool raiseAboveShaded = true;
	selectItem = MHWRender::MRenderItem::Create(
		fSelectedWireframeItemName,
		MHWRender::MGeometry::kLines,
		MHWRender::MGeometry::kAll,
		raiseAboveShaded);
	// This is the same as setting the argument raiseAboveShaded = true,
	// since it sets the priority value to be the same. This line is just
	// an example of another way to do the same thing after creation of
	// the render item.
	selectItem->depthPriority( MHWRender::MRenderItem::sActiveWireDepthPriority);
	list.append(selectItem);

	// Choose an line shader to match primitive type
	MHWRender::MShaderInstance* shader = 
		shaderMgr->getStockShader( MHWRender::MShaderManager::k3dSolidShader );
	if (shader)
	{

		// Assign shader
		selectItem->setShader(shader);
		// Once assigned, no need to hold on to shader instance
		shaderMgr->releaseShader(shader);
	}
}
else
{
	selectItem = list.itemAt(index);
}

// Perform updates on the render item parameters. In this case
// update the shader instance.
//
MHWRender::MShaderInstance* shader = NULL;
if (selectItem)
{
	shader = selectItem->getShader();
}

// Check the current display status of the object and color to use for this
// instance of the object.
MHWRender::DisplayStatus displayStatus = 
	MHWRender::MGeometryUtilities::displayStatus(path);
MColor wireColor = MHWRender::MGeometryUtilities::wireframeColor(path);

// It is not necessary to use the colors provided and instead a custom color could be 
// used if (fUseCustomColors) is set.
bool fUseCustomColors = false;
switch (displayStatus) {
case MHWRender::kLead:
	selectItem->enable(true);
	if (shader)
	{
		static const float theColor[] = { 0.0f, 0.8f, 0.0f, 1.0f };
		setSolidColor( shader, !fUseCustomColors ? &(wireColor.r) : theColor );
	}
	break;
case MHWRender::kActive:
	if (shader)
	{
		static const float theColor[] = { 1.0f, 1.0f, 1.0f, 1.0f };
		setSolidColor( shader, !fUseCustomColors ? &(wireColor.r) : theColor );
	}
	selectItem->enable(true); // Enable if the object is active
	break;
case MHWRender::kHilite:
case MHWRender::kActiveComponent:
	if (shader)
	{
		static const float theColor[] = { 0.0f, 0.5f, 0.7f, 1.0f };
		setSolidColor( shader, !fUseCustomColors ? &(wireColor.r) : theColor );
	}
	selectItem->enable(true); // Enable if the object is hilite, or 
                                  // its components are active.

	break;
default:
	// Otherwise make sure to disable it. The item is still present, it will just
	// not be sent down the rendering pipeline to draw.
	selectItem->enable(false);
	break;
};

/***** Call in MPxGeometryOverride::updatedDG() to perform any DG operations ****/
void updateDG()
{
	fActiveVertices.clear(); // fActiveVertices is an MIntArray 
	
	MObjectArray clist = // Get the active vertex components – plug-in specific ;
	if (clist.length())
	{
		MFnSingleIndexedComponent fnComponent( clist[0] );
		if (fnComponent.elementCount())
		{
			// Cache the vertex identifiers for later usage.
			fnComponent.getElements( fActiveVertices );
		}
	}
}

/* Test to see if active components should be enabled.
           Based on active vertices + non-template state
*/
bool enableActiveComponentDisplay(const MDagPath &path) const
{
	bool enable = true;

	// If no active components then disable the active
	// component render item
	if (fActiveVertices.length() == 0)
	{
		enable = false;
	}
	else
	{
		// If there are components then we need to check
		// either the display status of the object, or
		// in the case of a templated object make sure 
		// to hide components to be consistent with how
		// internal objects behave
		//
		MHWRender::DisplayStatus displayStatus = 
			MHWRender::MGeometryUtilities::displayStatus(path);
		if (displayStatus == MHWRender::kTemplate ||
			displayStatus == MHWRender::kActiveTemplate)
		{
			enable = false;
		}
		else
		{
			// Do an explicit path test for templated
			// since display status does not indicate this.
			if (path.isTemplated())
				enable = false;
		}
	}
	return enable;
}

…
// Unique name identifier for the render item
MString fActiveVertexItemName = “activeVertexItemName”;
MHWRender::MRenderItem* activeItem = NULL;
int index = list.indexOf(
	fActiveVertexItemName,
	MHWRender::MGeometry::kPoints,// Primitive type is points.
	MHWRender::MGeometry::kAll); // Render item should display in all display modes.
if (index < 0)
{
	activeItem = MHWRender::MRenderItem::Create(
		fActiveVertexItemName,
		MHWRender::MGeometry::kPoints,
		MHWRender::MGeometry::kAll,
		false);
	// Set depth priority to be active point. This should offset it 
	// to be visible above items with "dormant point" priority.
	activeItem->depthPriority( MHWRender::MRenderItem::sActivePointDepthPriority );
	list.append(activeItem);

	MHWRender::MShaderInstance* shader = shaderMgr->getStockShader(
		MHWRender::MShaderManager::k3dFatPointShader );
	if (shader)
	{
		// Set the point size parameter. Make it slightly larger for active
		// vertices
		static const float pointSize = 5.0f;
		setSolidPointSize( shader, pointSize );

		// Assign shader. Use a named stream if we want to supply a different
		// set of "shared" vertices for drawing active vertices
		bool fDrawSharedActiveVertices = true;
		MString fActiveVertexStreamName = “activeVertexStreamName”;
		if (fDrawSharedActiveVertices)
		{
			activeItem->setShader(shader, &fActiveVertexStreamName );
		}
		else
		{
			activeItem->setShader(shader, NULL);
		}

		// once assigned, no need to hold on to shader instance
		shaderMgr->releaseShader(shader);
	}
}
else
{
	activeItem = list.itemAt(index);
}

// Update the color and enable / disable the render item as appropriate.
// Just using a fixed color and not checking display status.
bool enableActiveDisplay = enableActiveComponentDisplay( <dagpath> );
if (activeItem)
{
	MHWRender::MShaderInstance* shader = activeItem->getShader();
	if (shader)
	{
		// Set active color
		static const float theColor[] = { 1.0f, 1.0f, 0.0f, 1.0f };
			setSolidColor( shader, theColor); // See code for active 
					// wireframe for this code utility.
	}

	activeItem->enable( enableActiveDisplay );
}

const MHWRender::MVertexBufferDescriptorList& descList =
		requirements.vertexRequirements();
int numVertexReqs = descList.length();
MHWRender::MVertexBufferDescriptor desc;
for (int reqNum=0; reqNum<numVertexReqs; reqNum++)
{
	if (!descList.getDescriptor(reqNum, desc))
	{
		continue;
	}

	// Fill in vertex data for drawing active vertex components 
	//
	if (fDrawSharedActiveVertices && (desc.name() == fActiveVertexStreamName))
	switch (desc.semantic())
	{
		case MHWRender::MGeometry::kPosition:
		{
			if (!activeVertexPositionBuffer)
			{
				activeVertexPositionBuffer = data.createVertexBuffer(desc);
				if (activeVertexPositionBuffer)
				{
				   // Allocate a position buffer to fit the # of active vertices
				   unsigned int activeVertexCount = fActiveVertices.length()
				   activeVertexPositions =
				      (float*)activeVertexPositionBuffer>acquire(
				              activeVertexCount, 
				              true 
				              /*writeOnly*/				
				}
			}
		}
		break;

		default:
			break;
	}
}