Geometric Data (MGeometry)

Vertex Buffers and GPU Data

A vertex buffer is represented in the API by the class MVertexBuffer. Logically it is just a block of binary data.

The format for this data is described in a vertex buffer descriptor, which in the API is represented by the class MVertexBufferDescriptor. A buffer descriptor describes the following properties:

• Name: user name to uniquely identify the data.
• Semantic: How the data should be interpreted as a vertex attribute. The basic semantics include position, normal, texture coordinate, color, tangent, bitangent, and tangent with winding order sign.
• Data type: Numeric data type.
• Dimension: Length of data.

Unique names allow you to have multiple sets of data with the same semantic. For example, it is possible to have two sets of texture coordinates with different names.

In the torus example, for instance, there can be a set of vertex buffers, each with a different name, for example “P1” as the name of one of the position buffers.

Figure 20

Unlike in previous systems, only GPU side (no CPU side) data is maintained by the resource management system in the rendering framework.

For vertex buffers (and in fact for all GPU side resources) the following properties are true:

• Data is managed and owned by the resource management system.
• Plug-ins are no longer free to access and update data without an active GPU device or context.
• Data must be acquired from the management system. If the data resides on the GPU, then it must be mapped back to CPU data before any modification can occur.
• When a CPU update is complete or if this is the first time data is created, then it must be committed (trans­ferred) to the GPU.
• Descriptions are mapped to GPU side descriptions. It is not possible to change the description after the ini­tial creation of the resources.
• Direct access to the draw API specific GPU handle can be obtained for each GPU resource. With this han­dle, any updates to the resource are done without the knowledge of the internal management system.

Index Buffers

Indexing data is represented by the class MIndexBuffer. Logically it is just a block of binary data.

The interpretation and format of the indexing is provided by the class MIndexBufferDescriptor. The descriptor has basic properties such as a string name for unique identification, primitive type and a data type. The only data type currently returned from internal object types is 32-bit integer.The primitive type includes basic hardware types such as points, lines and triangles but also includes enumerations for more advanced primitives which may be created via custom indexing.

The descriptor also allows for a semantic meaning to be specified for the indexing. This semantic meaning is called the indexing type. There are a series of predefined semantics which can be used, as well as the ability to mark the indexing as being “custom” generated.

More details on custom indexing are provided in the Advanced Topics sections.

The indexing does not need to represent all the elements of a given primitive type for a renderable object. For instance, it can be used to represent the component indexing for faces on a mesh for per-face shading, or to repre­sent selected CVs on a NURBS surface. For correspondence, a Maya DAG object component may be associated with the index descriptor.

As with vertex buffers, indexing is stored as GPU data and managed by the resource manager.

MGeometry management

To put all of the pieces together for MGeometry, Figure 20 below illustrates an instance of MGeometry, MIndexBuffer, MVertexBuffer, MRenderItem and the internal resource manager.

Figure 21: The MRenderItem references an MGeometry instance. The MGeometry instance references one or more MVertexBuffer instances, and zero or more MIndexBuffer instances. The MRenderItem keeps information about the specific MVertexBuffers and MIndexBuffer it uses. Any Maya DAG component can correspond to a specific MIndexBuffer. The data for MVertexBuffer and MIndexBuffer is managed by the internal resource manager which interacts directly with the GPU data.

This diagram shows a series of dependencies represented as connecting lines. The direction of arrows shows the direction of dependency. Each dependency is a reference and the collection of references shows how lifetime man­agement is handled. The resource manager always references the actual geometric data. MVertexBuffer and MIndexBuffer instances hold references to their corresponding GPU data. MGeometry holds references to all the MVertexBuffer and MInd­exBuffer instances for a renderable object. MRenderItem references specific MVertexBuffer and MIndexBuffer instances it uses.

Important notes in this scheme

1. Maya objects do not hold direct references to geometric data.
2. Plug-ins should never keep permanent references to any instances of geometry classes as they are not owned by the plug-in.
3. This includes vertex buffer descriptors and index buffer descriptors. Though they are not considered to be resources themselves they may reference resources and thus should not be held on to by the plug-in.
4. Even though there exists a backdoor to access the GPU resource handle, plug-ins should never try and delete data in this manner.

Geometry Requirements

The previous sections have discussed static geometry data structures and their relationships to one another. During the update phase, instances of these structures need to be instantiated and filled in.

We call this step fulfilling geometry requirements.

Within the API, the corresponding class that specifies what to fulfill is an MGeometryRequirements.

An instance of this class represents the hand-shake mechanism between shaders and locations where data is filled. Each shader for a render item puts forth its requirements. The cumulative set of requirements is collected and pre­sented in a single instance of MGeometryRequirements.

Requirements are specified by a set of vertex buffers descriptors (MVertexBufferDescriptor) and a set of index buffer descriptors (MIndexBufferDescriptor).

A round-trip update of geometric data is shown in the following diagram. Some geometry needs to be updated for a set of shaders. The requirements are gathered, fulfilled, and the geometry required for shading is updated.

Figure 22: In this example, a few render items are shown. The shader for each respective render item specifies a set of descriptors (index or data) and the descriptors are accumulated into a single MGeometryRequirements instance. When an update is required, those requirements are fulfilled and the resulting data cached and referenced by an MGeometry instance. In this particular case, all render items reference this MGeometry instance, and use this data during the rendering phase.

General Geometry Extraction

It is sometimes useful to be able to extract geometry from the resource manager outside the context of updating a render item, or outside the context of the rendering pipeline itself.

To do this, use the MGeometryExtractor interface. The interface is intended to provide non-renderer specific geometry data from Maya DAG objects.

It is the preferred mechanism to replace the old interface (called MGeometryManager). Though it is still possible to use either the old or the new interface or to even use functional interfaces for objects (MFn*), the existing inter­faces do not take advantage of all the properties of the new interface:

• The extraction interface is the same for all object types (unlike for MFn* interfaces)
• Geometric data is cached and only updated when required, thus reducing any DG or DAG evaluation over­head.
• The data format has been optimized to provide fast hardware draw.
• The data return resides on the CPU and has no dependence on the renderer and GPU resources.
• Data is owned by the caller.
• A common consistent mechanism is used to specify data “requirements” (MGeometryRequirements).
• Both indexing and vertex buffers can be returned. Custom defined data is also accessible via this interface.

Currently, only polygonal object types are supported.

Figure 23: For a given DAG path, a set of geometry requirements is passed to the extractor. From the associated DAG object, a set of index or vertex data blocks can be extracted.

Comparison of Geometry Classes

For plug-in writers which have used existing geometry classes, there can be some confusion between the old and the new interfaces. This is especially true as some names have been reused. One key item to remember is that all of the new interfaces are in the same namespace: MHWRender.

In this section, a table comparing some of the key differences between the old and new classes is provided. Note that the two interfaces are not designed to be compatible with each other and it is not advisable to try and mix-and-match class usage.

As has been noted before, one key difference is that all old interfaces manage CPU side data while the new inter­faces manage GPU side data.