mirror of
https://github.com/lighttransport/tinyusdz.git
synced 2026-01-18 01:11:17 +01:00
122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# 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.
|