Skip to content

Clarify vector2 roughness inputs of BSDF nodes - #3065

Open
jabrailkhalil wants to merge 1 commit into
AcademySoftwareFoundation:mainfrom
jabrailkhalil:roughness-input-clarity
Open

Clarify vector2 roughness inputs of BSDF nodes#3065
jabrailkhalil wants to merge 1 commit into
AcademySoftwareFoundation:mainfrom
jabrailkhalil:roughness-input-clarity

Conversation

@jabrailkhalil

Copy link
Copy Markdown

Closes #3031.

The vector2 roughness inputs of the microfacet BSDF nodes (dielectric_bsdf, conductor_bsdf, generalized_schlick_bsdf) have no documentation in the data library, and the PBR specification only states the pair semantics once, in the GGX section, with no link from the node sections. This makes it easy for both users and implementers to mistake them for the scalar roughness used elsewhere, and to apply an internal remap that the spec explicitly forbids ("supplied directly ... with no internal remapping").

Changes

libraries/pbrlib/pbrlib_defs.mtlx:

  • Add doc strings to the vector2 roughness inputs of dielectric_bsdf, conductor_bsdf, and generalized_schlick_bsdf, stating that the pair supplies the anisotropic roughness along the surface tangent and bitangent directly to the microfacet distribution, with no internal remapping.
  • Add doc strings to the vector2 roughness inputs of chiang_hair_bsdf (roughness_R, roughness_TT, roughness_TRT) describing them as the longitudinal variance / azimuthal logistic scale pair.
  • Add doc strings to the inputs of the roughness_anisotropy, roughness_dual, and glossiness_anisotropy utility nodes that produce these pairs.

documents/Specification/MaterialX.PBRSpec.md:

  • Link each microfacet BSDF node section to the GGX Normal Distribution Function section and state in the formulation mapping that the roughness input supplies (alpha_x, alpha_y) directly, with no remapping.
  • Fix the conductor_bsdf port table, which still described roughness as scalar-style "Surface roughness", to match dielectric_bsdf/generalized_schlick_bsdf.
  • Clarify the port tables and add reciprocal cross-links in the roughness_anisotropy, roughness_dual, and glossiness_anisotropy sections; correct the reported glossiness default to 1.0, matching the data library.

No API, port type, default value, or behavior changes.

Verification performed

  • Loaded stdlib + pbrlib from the working copy through the MaterialX Python bindings: all documents load and resolve; all 11 changed input doc strings are present; full-document write/read round-trip succeeds; all 56 library .mtlx files parse.
  • python Scripts/mxspec.py compare --spec ../documents/Specification/MaterialX.PBRSpec.md --mtlx ../libraries/pbrlib/pbrlib_defs.mtlx --defaults (same command family as repo CI): no new differences; only the two pre-existing artistic_ior default mismatches and pre-existing displacement node are reported.
  • python Scripts/mxspec.py compare for MaterialX.StandardNodes.md and MaterialX.NPRSpec.md: unchanged, no new differences.
  • python Scripts/mxdoc.py --docType md ../libraries/pbrlib/pbrlib_defs.mtlx and --docType html ../libraries/bxdf/standard_surface.mtlx (as run by repo CI): succeed and render the new doc strings.
  • python Scripts/mxvalidate.py ../resources/Materials/Examples/StandardSurface/standard_surface_marble_solid.mtlx: valid document.

Note: this machine has no C++ toolchain installed, so MaterialXTest could not be built locally; the change is documentation-only in library/spec data. The EasyCLA check will need to be signed before merge; I can sign as an individual contributor if required.

…tion#3031)

Document that vector2 roughness inputs of the microfacet BSDF nodes supply the anisotropic pair (alpha_x, alpha_y) along the surface tangent and bitangent directly, with no internal remapping, and cross-link the GGX formulation section of the PBR specification. Adds matching input docs in the pbrlib data library and clarifies the roughness utility node tables, including the conductor_bsdf port table which still described the input as a scalar-style 'Surface roughness'.
@linux-foundation-easycla

linux-foundation-easycla Bot commented Sep 10, 2026

Copy link
Copy Markdown

CLA Signed
The committers listed above are authorized under a signed CLA.

  • ✅ login: jabrailkhalil / name: jabrailkhalil (9ee5839)

@jstone-lucasfilm

Copy link
Copy Markdown
Member

Thanks for this proposal, @jabrailkhalil, and before we review it in detail, take a look at the instructions at #3065 (comment) for resolving the CLA authorization warnings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

vector2 roughness inputs in BSDF nodes are unclear

2 participants