Material and Shader Prims applicable to all render contexts#

Utility functions for creating, editing, and querying UsdShadeMaterial and UsdShadeShader objects, as well as conveniences around authoring UsdPreviewSurface specification compliant shader networks for use with 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.

Defining Preview Materials#

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.

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.

If you would like to use Material Interfaces with Preview Materials, try addPreviewMaterialInterface() to auto-generate an interface. Note that this function does not work for multi-context shader networks.

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

Warning

If your data is targetted at USD native applications or other USD Ecosystem leading applications, then using Material Interfaces is recommended. If you favor broad applicability throughout the entire USD Ecosystem, it maybe be preferable to avoid Material Interfaces for the time being.

Enumerations#

usdex::core::ColorSpace

Texture color space (encoding) types.

Functions#

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

Adds a diffuse texture to a preview 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::addNormalTextureToPreviewMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a normals texture to a preview 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::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::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::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.

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 surface 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::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.