Registration

The attachment model for DG nodes or DAG objects is supported by the registration interface MDrawRegistry. The attachment model for render loop overrides is discussed in greater detail in the section: 3.6 Render Loop Overrides.

For draw, shader, shading node, geometry and sub-scene overrides, the association is implicitly provided via the use of node classification strings. Override classification and Maya node/object classification matching forms this implicit link. The matching is performed hierarchically from broad to specific via the usage of “sub-classifications.”

The format required of a classification string is as follows:

“drawdb/<object classification>/[<sub-classification>]/<override classification>”

• drawdb : Is root string used to identify registration with the rendering database. This is always required.
• <object classification> :
  • “shader” : To be recognized as a shader, this string is required.
  • “geometry” : To be recognized as something that can draw geometry for a renderable object, this string is required.
  • “subscene“ : To be recognized as a DAG object that is evaluated with an MPxSubSceneOverride implementation, this string is required.
  • “light” : To be recognized as a lighting contributor, this string is required. It is recommended that both “drawdb/light” and “light” be used.

• <sub-classification> : This provides additional levels of classification which are useful, and in some cases, required for grouping and managing overrides. In particular, shading nodes that are used as surface shaders (connected to the Maya shading engine) must use a classification which starts with “drawdb/shader/surface/”. Sub-classification is optional for DAG overrides.

  In general, the more sub-classifications specified, the more specific the type of objects/nodes associated with a given entry point. For example, in these two examples:

  1. “drawdb/shader/surface/myLibrary/myShader”
  2. “drawdb/shader/surface/myLibrary”

  The first classification string, when used, would match fewer objects/nodes than the more-generic second string.

  For either existing or new plug-in node types, it is the responsibility of the plug-in writer to ensure that the appropriate classifications are used for both the override and for the node itself so that the correct classification string matching (association) is performed.

  Light classification

  

  If the classification is “light”, then the only possible sub-classifications are those available for internal Maya lights. This include “ambientLight”, “pointLight”, “directionalLight”, “spotlight” and “volumeLight”.

  The lights sub-classification indicates the internal lighting fragment that will be used during the computation of illumination. The parameters for these fragments are updated if an appropriate attribute is found on the node. The attributes may be a 1:1 match or an approximate match.

  For example, if a node of classification “drawdb/geometry/mynode” has the following attributes:

  • intensity attribute
  • use dmap shadows
  • use rtrace shadows

  And the light fragment has the following attributes:

  • intensity parameter
  • shadows enabled

  Then the intensity attributes map to each other, but the "use dmap shadows" and "use rtrace shadows" attributes both map to the same “shadows enabled” parameter.

  If a match is possible, then the unmapped (unconnected) value is used. If a match for an attribute is not found, then the appropriate default value for the attribute is used.

  NOTE:

  If you use the “light” classification, you must include these light attributes: intensity, color, emitDiffuse, and emitSpecular, in order for the light to behave like a Maya light. The attributes can be static or dynamic.

  If you use the “light” classification, then the only possible sub-classifications are those available for internal Maya lights:

  • ambientLight
  • pointLight
  • directionalLight
  • spotlight
  • volumeLight
  • image.

  

  The exposure attribute is also parsed for internal light evaluation.

  

  The apiDirectionalLightShape Developer Kit example plug-in and the Arnold for Maya plug-in lights have implementations that show support for the various classifications and attribute handling, including exposure.

  No drawing override is required as the internal drawing for the given light type is provided automatically.

• <override classification> : Unique override classification. Often, this is the name of the node type the override is to be used with (if it is not used with multiple node types).

Figure 35: For each override type the classification matches any objects or nodes specified in the classification.

Figure 36: Example demonstrating that, depending on how on how specific the classification is, different matches results. The “drawdb/geometry/parametricSurface/B-spline” DAG object classification matches more closely to the override with the identical classification string, rather than the more generic “drawdb/geometry/parametricSurface” string. The classification with the closest match is used.

The getClassification command documentation contains a list of classifications recognized by Viewport 2.0.

Draw a custom object that performs lighting in Viewport 2.0

For dag objects that wish to contribute lighting as well as have custom drawing, it is possible to have two “drawdb” classifications: one that starts with “light” and one that starts with “geometry”. This is shown with the “drawdb/geometry/light/myLight” classification on the node and corresponding geometry override, as well as a “light” and “drawdb/light/directionalLight” classification.

A simple example is given in the apiDirectionalLightShape plug-in example, which draws the following custom geometry (in blue) as compared to the default internal drawing of a directional light.

Only classifications for draw and geometry overrides may be registered along with “drawdb/light”. Overrides such as “drawdb/subscene”, for example, are not allowed.

In order for the override of a plug-in node to represent the drawing of a light, the “drawdb/geometry/light” classification string should be used when registering the override; for example, a classification string such as “drawdb/geometry/light/myLight” could be used. Support for display type filters becomes available when this classification is used, such that the drawing of these plug-in nodes are filtered when lights are filtered.

Register transform node plug-ins

Plug-in writers should be aware that, in order for a plug-in transform to be recognized in Viewport 2.0, the appropriate classification string drawdb/geometry/transform must be added when registering the transform. This must be done so that:

• Local rotation axis and pivots draw.
• Transforming the object moves any children parented under it in the DAG.

For example, for the rockingTransform plug-in, the code is as follows:

// Classify the node as a transform.  This causes Viewport
// 2.0 to treat the node the same way it treats a regular
// transform node.
const MString classification = "drawdb/geometry/transform";
status = plugin.registerTransform("rockingTransform", 								
                                   rockingTransformNode::id, 					 				
                                   &rockingTransformNode::creator, 								
                                   &rockingTransformNode::initialize,
                                   &rockingTransformMatrix::creator,
                                   rockingTransformMatrix::id,
                                   &classification);

If this is not done, then registerTransform() automatically adds the drawdb/geometry/transform classification if no other drawdb classification is specified.

 Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.