add note on OpenUSD's MaterialX node parser behavior.

2026-01-18 01:11:17 +01:00 · 2025-12-25 01:31:53 +09:00
parent b6c8bb095d
commit dbec308bd1
1 changed files with 121 additions and 0 deletions
--- a/doc/pxr-mtlx.md
+++ b/doc/pxr-mtlx.md
@@ -0,0 +1,121 @@
+# MaterialX Parser Logic Summary
+
+This document summarizes the node graph parsing logic in `pxr/usd/usdMtlx/parser.cpp`.
+
+## Overview
+
+The parser converts MaterialX node definitions into USD's Sdr (Shader Definition Registry) shader nodes. It implements `SdrParserPlugin` to integrate with USD's shader discovery system.
+
+## Key Components
+
+### 1. ShaderBuilder (lines 78-136)
+
+A builder pattern class that accumulates data for constructing `SdrShaderNode`:
+
+- **Fields**: `discoveryResult`, `valid`, `definitionURI`, `implementationURI`, `context`, `properties`, `metadata`
+- **AddPropertyNameRemapping()**: Maps MaterialX property names to USD names
+- **AddProperty()**: Converts MaterialX typed elements to `SdrShaderProperty`
+- **Build()**: Creates the final `SdrShaderNodeUniquePtr`
+
+### 2. Property Parsing (AddProperty, lines 224-391)
+
+Converts MaterialX inputs/outputs to Sdr properties:
+
+1. **Type Resolution**: Maps MaterialX types to USD Sdf types via `UsdMtlxGetUsdType()`
+2. **Default Values**: Extracts via `UsdMtlxGetUsdValue()`
+3. **Metadata Extraction**:
+   - `defaultinput` for outputs
+   - `target` for inputs
+   - `colorspace` for inputs/outputs
+   - UI metadata: `uiname`, `doc`, `uifolder`, `uimin`, `uimax`, `uisoftmin`, `uisoftmax`, `uistep`
+   - Unit info: `unit`, `unittype`
+4. **Primvar Handling**: Tracks `defaultgeomprop` references, replacing `UV0` with the configured primary UV set name
+
+### 3. ParseElement (lines 436-551)
+
+Main NodeDef parsing function:
+
+1. **Context Determination** (lines 444-454):
+   - Checks type's semantic for "shader" to get context
+   - Falls back to standard typedefs
+   - Defaults to `SdrNodeContext->Pattern`
+
+2. **Node Metadata** (lines 462-467):
+   - `Label` = nodeDef's node string
+   - `Category` = nodeDef's type
+   - `Help` from `doc` attribute
+   - `Target` from `target` attribute
+   - `Role` from `nodegroup` attribute
+
+3. **Primvar Collection** (lines 471-535):
+   - `ND_geompropvalue*` nodes: add `$geomprop`
+   - `ND_texcoord_vector2`: add primary UV set name
+   - **Implementation NodeGraph traversal**:
+     - `geompropvalue` nodes: extract primvar from `geomprop` input
+     - `texcoord` nodes: add primary UV set
+     - `image`/`tiledimage` nodes: add primary UV set if no texcoord already added
+   - `internalgeomprops` attribute: parse and add primvars
+
+4. **Property Collection** (lines 538-544):
+   - Iterates `nodeDef->getActiveInputs()` for input properties
+   - Iterates `nodeDef->getActiveOutputs()` for output properties
+
+### 4. UsdMtlxParserPlugin (lines 556-643)
+
+The main parser plugin:
+
+**ParseShaderNode()** (lines 567-622):
+1. Load MaterialX document from `resolvedUri` or `sourceCode`
+2. Look up NodeDef by `identifier` or `subIdentifier`
+3. Create `ShaderBuilder` and call `ParseElement()`
+4. Return built shader node
+
+**GetDiscoveryTypes()**: Returns `["mtlx"]`
+
+**GetSourceType()**: Returns empty string (default source type)
+
+## Data Flow
+
+```
+MaterialX Document
+       │
+       ▼
+   NodeDef lookup
+       │
+       ▼
+   ShaderBuilder
+       │
+       ├─── ParseElement() ───┬─── Extract context
+       │                      ├─── Extract metadata
+       │                      ├─── Collect primvars
+       │                      └─── Parse inputs/outputs
+       │
+       ▼
+   AddProperty() for each input/output
+       │
+       ├─── Type conversion (UsdMtlxGetUsdType)
+       ├─── Default value (UsdMtlxGetUsdValue)
+       ├─── Metadata extraction
+       └─── Primvar tracking
+       │
+       ▼
+   ShaderBuilder.Build()
+       │
+       ▼
+   SdrShaderNode
+```
+
+## Key Tokens (lines 32-56)
+
+Private tokens for attribute names:
+- `mtlx`, `defaultgeomprop`, `defaultinput`, `doc`, `enum`, `enumvalues`
+- `nodecategory`, `nodegroup`, `target`, `uifolder`, `uimax`, `uimin`
+- `uiname`, `uisoftmax`, `uisoftmin`, `uistep`, `unit`, `unittype`, `UV0`
+
+## Environment Settings
+
+- `USDMTLX_PRIMARY_UV_NAME`: Override the primary UV set name (defaults to USD's `UsdUtilsGetPrimaryUVSetName()`, typically "st")
+
+## Role Normalization (lines 405-414)
+
+For stdlib texture nodes, `texture2d` and `texture3d` roles are normalized to `texture` for Sdr compatibility.