Contexts and Plugins

Material Graph supports multiple render contexts within a single material. Each context corresponds to a shading language or standard and is backed by a plugin. The plugin controls which nodes are available, how they are validated, and how they are resolved at render time. This page explains how contexts work, how to switch between them, and how the plugin system shapes each context’s behavior.

Render Contexts

A render context defines the shading language used to describe a material’s appearance. Material Graph supports three contexts out of the box:

Context	Plugin ID	Description
MDL	mdl	NVIDIA’s Material Definition Language. Provides a rich library of physically based shading nodes, polymorphic overloads, and MDL module support.
MaterialX	mtlx	The open standard for material and look-development interchange. Uses the Sdr (Shader Definition Registry) for node definitions prefixed with ND_.
Universal	universal	A simplified, renderer-agnostic context based on UsdPreviewSurface. Suitable for interchange when you need materials that render across different backends.

A single USD material can carry graphs for all three contexts simultaneously. Each context produces its own set of material outputs, allowing a single material prim to serve different renderers without duplication of the prim itself.

Context Tabs

The context tabs appear in the Material Graph toolbar, between the error indicators and the compilation controls.

Switching Contexts

Click a tab to switch the active context. When you switch:

• The canvas updates to show only the nodes and connections that belong to the selected context.

• The Catalog refreshes to list nodes available in the new context.

• Validation re-runs against the rules defined by the new context’s plugin.

• The material output ports visible at the top level change to reflect the selected context’s output names.

Material Graph shows a tab for each registered context plugin. The standard plugins provide MDL, MaterialX, and Universal tabs.

What Context Affects

Area	Effect
Catalog content	Each context plugin supplies its own Catalog of available nodes. MDL shows MDL modules, MaterialX shows ND_ definitions, Universal shows UsdPreviewSurface nodes.
Visible nodes	Nodes authored under one context are not shown when another context is active, unless they are shared utility prims.
Material outputs	Defines its own material output ports, such as mdl:surface, mtlx:surface, and surface. Switching contexts changes the active outputs.
Connection validation	The active context’s plugin evaluates type compatibility, so the same port pair can be valid in one context and rejected in another.

Context Visibility on NodeGraphs and Backdrops

When the Confine NodeGraphs or Confine Backdrops settings are enabled (both on by default), you can restrict a NodeGraph or Backdrop to one or more render contexts. This is useful when the same graph level contains nodes for multiple contexts and you want to keep them visually separated.

To confine a NodeGraph or Backdrop:

1. Open the element’s node menu and choose Context Visibility….

2. Select every context in which the element should appear.

3. Close the menu. Material Graph stores the selection on the prim.

To remove the restriction, select all contexts.

Confinement is stored as custom data on the prim (omni:ui:contextVisibility) and is saved with the USD stage.

Context Soloing

Context Soloing lets you isolate a single render context in the Viewport so that the renderer evaluates only its material output. Use it to preview a specific context without interference from other contexts’ outputs.

How Soloing Works

When you solo a context, Material Graph temporarily disconnects the material output connections for all other inactive contexts. The renderer then evaluates only the soloed context’s output in the Viewport.

Soloing a Context

1. Switch to the context you want to preview.

2. Click the Solo (S) button in the toolbar.

The Solo (S) button lights up to indicate that soloing is active, and the Viewport updates to show only the soloed context’s output.

Behavior Details

Behavior	Description
Switching while soloed	If you click a different context tab while solo is active, the solo transfers automatically to the new context. You do not need to unsolo first.
Cleared on new material	Solo state is automatically cleared when you load a different material or close the editor.
Session layer	Solo operates on the USD session layer. The disconnections are non-destructive and are never written to the root layer or saved to disk. Your authored connections remain intact at all times.
Undo support	Soloing and unsoloing are recorded in the undo history. Press Ctrl+Z to reverse a solo action.
Stage listener	While soloed, changes to the disconnected output attributes are excluded from the stage listener to avoid unnecessary graph rebuilds.

Turning Off Solo

Click Solo (S) again to unsolo. Material Graph removes the session-layer overrides, reconnects all material outputs, and resumes rendering all contexts in the Viewport.

Known Limitation

When the Fabric scene delegate is active (/app/useFabricSceneDelegate is enabled) and the Kit major version is below 111, context soloing is not supported. The Solo button is disabled and displays an explanatory tooltip. This restriction exists because the Fabric delegate’s connection management does not currently handle the session-layer override pattern that soloing relies on.

Plugin System

Each render context is driven by a plugin, a Python class that extends the Plugin base. The plugin is the central point of customization for a context. It controls:

Responsibility	Description
Catalog	Determines which nodes appear in the Catalog and how they are categorized.
Prim identification	Decides whether a given USD prim belongs to its context by using shader IDs, source asset attributes, or naming conventions.
Connection validation	Evaluates type compatibility between ports, including context-specific rules such as MDL render types or MaterialX Sdr type roles.
Material outputs	Supplies the output port names that correspond to its context (used by soloing and the graph UI).
Style and icons	Provides category colors, node icons, and preview images for nodes in its context.

The plugin for the active context is loaded when you switch tabs and drives every aspect of the editor’s behavior for that context.

MDL Context Details

The MDL plugin identifies nodes by the presence of MDL source asset attributes (info:mdl:sourceAsset and info:mdl:sourceAsset:subIdentifier) on UsdShade.Shader prims.

Module List

The MDL Catalog is built from a configurable list of MDL module files. The default set is defined in the extension settings under:

persistent.app.properties.materialGraph.plugins.mdl.modules

Each module is resolved through the MDL search paths, and all public definitions within the module are registered as Catalog entries. Changing the module list refreshes the Catalog when the MDL context is active.

Polymorphic Nodes

MDL supports polymorphic nodes, whose input and output types adapt based on how they are connected. For example, a math::add node can operate on floats, vectors, or colors depending on its inputs.

Polymorphic support is enabled by default (enablePolymorphic: true in plugin settings). When enabled, the plugin resolves the correct overload at connection time and updates the node’s port types accordingly. If you connect a color3f output to a polymorphic input, the node automatically selects the color overload.

Annotation Filters

MDL definitions can carry annotations such as deprecated, hidden, or unused. The MDL plugin filters annotated definitions out of the Catalog by default. The excluded annotation list is configurable:

persistent.app.properties.materialGraph.plugins.mdl.catalogExcludedAnnotations

Removing an annotation from the exclusion list causes matching definitions to reappear in the Catalog.

MaterialX Context Details

The MaterialX plugin identifies nodes by matching shader IDs registered in the Sdr (Shader Definition Registry) with a source type of mtlx. It also recognizes shader IDs that begin with the ND_ prefix.

Catalog Organization

MaterialX nodes are grouped in the Catalog by role and family heuristics derived from their Sdr metadata. The plugin normalizes role names and generates display names from the Sdr entry, producing a categorized tree similar in structure to the MaterialX specification’s node groupings.

Filtering

The MaterialX plugin supports several filtering mechanisms to control which nodes appear in the Catalog:

Filter	Purpose
Ignore contexts	Exclude nodes whose Sdr context matches an internal implementation pattern.
Ignore families	Exclude entire node families by name.
Ignore name patterns	Exclude nodes whose names match a regular expression.

These filters are defined in the plugin’s property settings and are applied during Catalog construction.

Texture Channel Detection

When you add a MaterialX texture or image node to the graph, the plugin inspects its name for channel-count hints. These hints include float, vector2, vector3, vector4, color3, and color4. The plugin configures the node’s output type accordingly.

Universal Context Details

The Universal plugin centers on UsdPreviewSurface, the renderer-agnostic material model defined by the USD specification. It resolves registered ID-authored shaders such as UsdPreviewSurface. It also keeps unresolved, non-MaterialX ID-authored shaders visible through their USD-authored fallback ports. MaterialX-style ND_ identifiers remain in the MaterialX context instead of leaking into Universal.

On startup, the plugin registers the UsdPreviewSurface.mdl module (if resolvable on the current MDL search paths) so that the node is available in the Catalog with proper port definitions.

Because UsdPreviewSurface is intentionally simple, the Universal Catalog is smaller than MDL or MaterialX. It is the right choice when you need materials that render predictably across any compliant USD viewer.

Summary

Concept	Key Points
Context tabs	Switch contexts in the toolbar. The canvas, Catalog, and validation follow the active context.
Context visibility	NodeGraphs and Backdrops can be restricted to selected contexts through Context Visibility….
Soloing	The S button isolates a context in the Viewport using non-destructive session-layer edits.
Plugins	Each context is driven by a plugin that controls Catalog, validation, and node identification.
MDL	Module-based Catalog, polymorphic nodes, annotation filtering.
MaterialX	Sdr-driven Catalog, role/family grouping, regex-based filtering.
Universal	UsdPreviewSurface-focused, small Catalog, maximum portability.

Related Pages

• Overview: Key concepts and interface tour.

• Working with Nodes: Creating, connecting, and organizing nodes.

• Validation and Errors: How the active plugin’s validation rules surface in the editor.

• Backdrops and Layout: Backdrop confinement and visual organization.