Material and Shader Prims#

Utility functions for creating, editing, and querying UsdShadeMaterial and UsdShadeShader objects. This module provides:

  • Context-agnostic utilities for creating and binding materials, querying effective shaders, color space conversion, and primvar reader connections.

  • Preview Materials for the universal render context, using UsdPreviewSurface shader networks.

  • PBR Materials for dual-context authoring, using OpenPBR Surface shader networks for the MaterialX render context together with a UsdPreviewSurface fallback for the universal render context.

Creating and Binding Materials#

This module provides functions for creating materials (createMaterial()), binding them to geometry (bindMaterial()), and some basic color transformation functions (linear and sRGB only).

While some of these implementations are fairly straightforward, they serve to catch & prevent several common mistakes made when authoring materials using the UsdShade module directly.

Preview Materials (Universal Render Context)#

UsdPreviewSurface materials should be supported by all renderers, and are generally used as “fallback” shaders when renderer-specific shaders have not been supplied. While typically serving as fallback/previews, they are still relatively advanced PBR materials and may be suitable as final quality materials, depending on your intended target use case for your USD data.

Several functions below assist with authoring and adding textures to Preview Materials, and are a suitable starting point for anyone needing general PBR behavior across a variety of renderers.

In the Preview Material functions, we make several assumptions about the source data, which is broadly applicable to many use cases. If more specific behavior is required, computeEffectivePreviewSurfaceShader() can be used to locate the underlying surface shader for further direct authoring (or re-wiring) of UsdShadeInputs.

PBR Materials (MaterialX + Universal Render Contexts)#

For higher-fidelity rendering, definePbrMaterial() creates a dual-context material with both an OpenPBR Surface shader network for the MaterialX render context and a UsdPreviewSurface shader network for the universal render context. The MaterialX shader nodes used are from the MaterialX Node Library. This gives renderers that support MaterialX (such as USDView/Storm and Omniverse RTX) a physically accurate shading result, while still providing a UsdPreviewSurface fallback for renderers that do not.

The two shader networks are connected through a shared Material Interface, so editing a material-level input (e.g. color or roughness) drives both networks simultaneously. Each add*TextureToPbrMaterial() function authors texture shaders for both render contexts in a single call and maintains this shared interface.

Material Interfaces#

Several of the functions below refer to a “Material Interface”. This is a term for UsdShadeInputs which have been authored directly on a UsdShadeMaterial prim and connected to lower-level UsdShadeShader inputs, to form a shading network that controls the overall appearance of the material. See UsdShadeNodeGraph for a technical explanation of the Interface Inputs.

Material Interfaces are useful for a variety of reasons:

  • They form a “contract” between the Material author and the end-user as to which inputs are available for editing.

  • They make it simpler for downstream processes, like render delegates, to make assumptions about the material.

  • Exposing top-level attributes allows a Material prototype to be instanced, while still providing controls that allow each instance to appear unique.

However, Material Interfaces are not consistently supported in every Application & Renderer:

  • Any USD native application will support Material Interfaces, and many more will also support them for import into their native scene format.

  • Some even require Material Interfaces; these will ignore edits to Shader prims and only react to edits to Material prims.

  • But a few others fail to import Material Interfaces into their native scene format.

For Preview Materials, use addPreviewMaterialInterface() to auto-generate an interface. Note that this function does not work for multi-context shader networks. PBR Materials created by definePbrMaterial() always include a Material Interface by default.

If instead you need to target applications that cannot load Material Interfaces, use removeMaterialInterface() to clean the content before loading into your target applications.

Note

PBR Materials always create a Material Interface. There is no need to call addPreviewMaterialInterface() on a PBR Material.

Enumerations Summary#

usdex::core::ColorSpace

Texture color space (encoding) types.

Functions Summary#

bool usdex::core::addColorTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a color texture to an OpenPBR material.

bool usdex::core::addColorTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a color texture to a preview material.

bool usdex::core::addDiffuseTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a diffuse texture to a preview material.

bool usdex::core::addEmissiveColorToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::GfVec3f &color, const float luminance=1000.0f)

Adds an emissive color and luminance to an OpenPBR material.

bool usdex::core::addEmissiveColorToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::GfVec3f &color)

Adds an emissive color to a preview material.

bool usdex::core::addEmissiveTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath, const float luminance=1000.0f)

Adds an emissive color texture to an OpenPBR material.

bool usdex::core::addEmissiveTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds an emissive color texture to a preview material.

bool usdex::core::addMetallicTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel metallic texture to an OpenPBR material.

bool usdex::core::addMetallicTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel metallic texture to a preview material.

bool usdex::core::addNormalTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a normals texture to an OpenPBR material.

bool usdex::core::addNormalTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a normals texture to a preview material.

bool usdex::core::addOpacityTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel opacity texture to an OpenPBR material.

bool usdex::core::addOpacityTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel opacity texture to a preview material.

bool usdex::core::addOrmTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds an ORM (occlusion, roughness, metallic) texture to an OpenPBR material.

bool usdex::core::addOrmTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds an ORM (occlusion, roughness, metallic) texture to a preview material.

bool usdex::core::addPreviewMaterialInterface(pxr::UsdShadeMaterial &material)

Adds UsdShadeInputs to the material prim to create an "interface" to the underlying Preview Shader network.

bool usdex::core::addPrimvarShaderToPbrMaterial(pxr::UsdShadeMaterial &material, const std::string &surfaceInputName, const std::string &primvarName, const pxr::VtValue &fallbackValue=pxr::VtValue())

Adds a primvar reader shader to the material prim and connects it to a surface input.

bool usdex::core::addPrimvarShaderToPreviewMaterial(pxr::UsdShadeMaterial &material, const std::string &surfaceInputName, const std::string &primvarName, const pxr::VtValue &fallbackValue=pxr::VtValue())

Adds a primvar reader shader to the material prim and connects it to a surface input.

bool usdex::core::addRoughnessTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel roughness texture to an OpenPBR material.

bool usdex::core::addRoughnessTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a single channel roughness texture to a preview material.

bool usdex::core::bindMaterial(pxr::UsdPrim prim, const pxr::UsdShadeMaterial &material)

Authors a direct binding to the given material on this prim.

bool usdex::core::bindMaterialSubsets(const std::vector< pxr::UsdGeomSubset > &subsets, const std::vector< pxr::UsdShadeMaterial > &materials)

Binds materials to the geometry subsets of the given geometry prim.

pxr::UsdShadeShader usdex::core::computeEffectiveMtlxSurfaceShader(const pxr::UsdShadeMaterial &material)

Get the effective surface Shader of a Material for the MaterialX render context.

pxr::UsdShadeShader usdex::core::computeEffectivePreviewSurfaceShader(const pxr::UsdShadeMaterial &material)

Get the effective surface Shader of a Material for the universal render context.

bool usdex::core::connectPrimvarShader(pxr::UsdShadeInput &shaderInput, const std::string &primvarName, const pxr::VtValue &fallbackValue=pxr::VtValue())

Connects a shader input to a primvar reader shader.

pxr::UsdShadeMaterial usdex::core::createMaterial(pxr::UsdPrim parent, const std::string &name)

Create a UsdShadeMaterial as a child of the Prim parent.

pxr::UsdShadeMaterial usdex::core::defineGlassPbrMaterial(pxr::UsdPrim parent, const std::string &name, const pxr::GfVec3f &color, const float indexOfRefraction=1.5f, const float roughness=0.02f, const float previewOpacity=0.2f)

Defines a Glass UsdShadeMaterial interface that drives both an OpenPBR MaterialX render context and the universal render context.

pxr::UsdShadeMaterial usdex::core::defineGlassPbrMaterial(pxr::UsdPrim prim, const pxr::GfVec3f &color, const float indexOfRefraction=1.5f, const float roughness=0.02f, const float previewOpacity=0.2f)

Defines a Glass UsdShadeMaterial interface that drives both an OpenPBR MaterialX render context and the universal render context.

pxr::UsdShadeMaterial usdex::core::defineGlassPbrMaterial(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::GfVec3f &color, const float indexOfRefraction=1.5f, const float roughness=0.02f, const float previewOpacity=0.2f)

Defines a Glass UsdShadeMaterial interface that drives both an OpenPBR MaterialX render context and the universal render context.

pxr::UsdShadeMaterial usdex::core::defineGlassPreviewMaterial(pxr::UsdPrim prim, const pxr::GfVec3f &color, const float indexOfRefraction=1.5f, const float roughness=0.02f, const float opacity=0.2f)

Defines a Glass PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

pxr::UsdShadeMaterial usdex::core::defineGlassPreviewMaterial(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::GfVec3f &color, const float indexOfRefraction=1.5f, const float roughness=0.02f, const float opacity=0.2f)

Defines a Glass PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

pxr::UsdShadeMaterial usdex::core::defineGlassPreviewMaterial(pxr::UsdPrim parent, const std::string &name, const pxr::GfVec3f &color, const float indexOfRefraction=1.5f, const float roughness=0.02f, const float opacity=0.2f)

Defines a Glass PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

pxr::UsdShadeMaterial usdex::core::definePbrMaterial(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.3f, const float metallic=0.0f)

Defines an OpenPBR UsdShadeMaterial interface that drives both an OpenPBR MaterialX render context and the universal render context.

pxr::UsdShadeMaterial usdex::core::definePbrMaterial(pxr::UsdPrim parent, const std::string &name, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.3f, const float metallic=0.0f)

Defines an OpenPBR UsdShadeMaterial interface that drives both an OpenPBR MaterialX render context and the universal render context.

pxr::UsdShadeMaterial usdex::core::definePbrMaterial(pxr::UsdPrim prim, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.3f, const float metallic=0.0f)

Defines an OpenPBR UsdShadeMaterial interface that drives both an OpenPBR MaterialX render context and the universal render context.

pxr::UsdShadeMaterial usdex::core::definePreviewMaterial(pxr::UsdPrim prim, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.5f, const float metallic=0.0f)

Defines a PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

pxr::UsdShadeMaterial usdex::core::definePreviewMaterial(pxr::UsdPrim parent, const std::string &name, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.5f, const float metallic=0.0f)

Defines a PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

pxr::UsdShadeMaterial usdex::core::definePreviewMaterial(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::GfVec3f &color, const float opacity=1.0f, const float roughness=0.5f, const float metallic=0.0f)

Defines a PBR UsdShadeMaterial driven by a UsdPreviewSurface shader network for the universal render context.

const pxr::TfToken & usdex::core::getColorSpaceToken(ColorSpace value)

Get the TfToken matching a given ColorSpace

pxr::GfVec3f usdex::core::linearToSrgb(const pxr::GfVec3f &color)

Translate a linear color value to sRGB color space.

bool usdex::core::removeMaterialInterface(pxr::UsdShadeMaterial &material, bool bakeValues=true)

Removes any UsdShadeInputs found on the material prim.

pxr::GfVec3f usdex::core::sRgbToLinear(const pxr::GfVec3f &color)

Translate an sRGB color value to linear color space.