Material and Shader Prims for use with the RTX Renderer#

Utility functions for creating, editing, and querying MDL Materials and Shaders for use with the RTX Renderer.

Authoring MDL Shaders for the RTX Renderer#

This module provides functions for creating UsdShadeShaders that map to MDL Shaders and UsdShadeInputs that map to MDL Inputs.

Defining Materials for the RTX Renderer#

The RTX Renderer supports several types of UsdShadeShaders, but it is most performant & results will be more photorealistic when using MDL shaders, especially those from the Core MDL Materials, like:

Several functions below assist with authoring and adding textures to PBR and Glass Materials that are specifically tailored for the RTX Renderer.

To make the authored USD data more portable across the USD Ecosystem, these functions also author a Preview shader network (see Material and Shader Prims applicable to all render contexts), and both shader networks are driven from a top-level “Material Interface” on the UsdShadeMaterial prim. The resulting USD can be rendered in the RTX Renderer for the highest fidelity results, as well as in any other USD capable renderer for a lower fidelity preview.

Warning

If your data is targetted at the RTX Renderer, or other USD native applications or USD Ecosystem leading applications, then using Material Interfaces is recommended. If you favor broad applicability throughout the entire USD Ecosystem, it may be be preferable to avoid Material Interfaces for the time being. In this case, you can call usdex::core::removeMaterialInterface after usdex::rtx::definePbrMaterial

Functions#

bool usdex::rtx::addDiffuseTextureToPbrMaterial(pxr::UsdShadeMaterial &material, const pxr::SdfAssetPath &texturePath)

Adds a diffuse texture to the PBR material.

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

Adds a metallic texture to the PBR material.

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

Adds a normal texture to the PBR material.

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

Adds an opacity texture to the PBR material.

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

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

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

Adds a roughness texture to the PBR material.

pxr::UsdShadeShader usdex::rtx::computeEffectiveMdlSurfaceShader(const pxr::UsdShadeMaterial &material)

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

pxr::UsdShadeShader usdex::rtx::createMdlShader(pxr::UsdShadeMaterial &material, const std::string &name, const pxr::SdfAssetPath &mdlPath, const pxr::TfToken &module, bool connectMaterialOutputs=true)

Create a UsdShadeShader as a child of the UsdShadeMaterial argument with the specified MDL.

pxr::UsdShadeInput usdex::rtx::createMdlShaderInput(pxr::UsdShadeMaterial &material, const pxr::TfToken &name, const pxr::VtValue &value, const pxr::SdfValueTypeName &typeName, std::optional< const usdex::core::ColorSpace > colorSpace=std::nullopt)

Create an MDL shader input.

pxr::UsdShadeMaterial usdex::rtx::defineGlassMaterial(pxr::UsdPrim parent, const std::string &name, const pxr::GfVec3f &color, const float indexOfRefraction=1.491f)

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

pxr::UsdShadeMaterial usdex::rtx::defineGlassMaterial(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::GfVec3f &color, const float indexOfRefraction=1.491f)

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

pxr::UsdShadeMaterial usdex::rtx::definePbrMaterial(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 interface that drives both an RTX render context and the universal render context.

pxr::UsdShadeMaterial usdex::rtx::definePbrMaterial(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 interface that drives both an RTX render context and the universal render context.

Functions#

bool usdex::rtx::addDiffuseTextureToPbrMaterial(
pxr::UsdShadeMaterial &material,
const pxr::SdfAssetPath &texturePath,
)#

Adds a diffuse texture to the PBR material.

It is expected that the material was created by usdex::rtx::definePbrMaterial().

Note

The material prim’s “Color” input will be removed and replaced with “DiffuseTexture”. Due to the input removal this function should be used at initial authoring time rather than in a stronger layer.

Parameters:

  • material – The UsdShadeMaterial prim to add the texture

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

Adds a metallic texture to the PBR material.

It is expected that the material was created by usdex::rtx::definePbrMaterial().

Note

The material prim’s “Metallic” input will be removed and replaced with “MetallicTexture”. Due to the input removal this function should be used at initial authoring time rather than in a stronger layer.

Parameters:

  • material – The UsdShadeMaterial prim to add the texture

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

Adds a normal texture to the PBR material.

It is expected that the material was created by usdex::rtx::definePbrMaterial().

Parameters:

  • material – The UsdShadeMaterial prim to add the texture

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

Adds an opacity texture to the PBR material.

It is expected that the material was created by usdex::rtx::definePbrMaterial().

These shader parameters will be set to produce better masked geometry:

  • MDL OmniPBR: opacity_threshold = float_epsilon (just greater than zero)

  • UsdPreviewSurface: ior = 1.0

  • UsdPreviewSurface: opacityThreshold = float_epsilon (just greater than zero)

Note

The material prim’s “Opacity” input will be removed and replaced with “OpacityTexture”. Due to the input removal this function should be used at initial authoring time rather than in a stronger layer.

Parameters:

  • material – The UsdShadeMaterial prim to add the texture

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

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

It is expected that the material was created by usdex::rtx::definePbrMaterial().

Note

The material prim’s “Roughness” and “Metallic” inputs will be removed and replaced with “ORMTexture”. Due to the input removal this function should be used at initial authoring time rather than in a stronger layer.

Parameters:

  • material – The UsdShadeMaterial prim to add the texture

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

Adds a roughness texture to the PBR material.

It is expected that the material was created by usdex::rtx::definePbrMaterial().

Note

The material prim’s “Roughness” input will be removed and replaced with “RoughnessTexture”. Due to the input removal this function should be used at initial authoring time rather than in a stronger layer.

Parameters:

  • material – The UsdShadeMaterial prim to add the texture

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

pxr::UsdShadeShader usdex::rtx::computeEffectiveMdlSurfaceShader(
const pxr::UsdShadeMaterial &material,
)#

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

Parameters:

material – The Material to consider

Returns:

The connected Shader. Returns an invalid object on error.

pxr::UsdShadeShader usdex::rtx::createMdlShader(
pxr::UsdShadeMaterial &material,
const std::string &name,
const pxr::SdfAssetPath &mdlPath,
const pxr::TfToken &module,
bool connectMaterialOutputs = true,
)#

Create a UsdShadeShader as a child of the UsdShadeMaterial argument with the specified MDL.

Parameters:

  • material – Parent UsdShadeMaterial for the shader to be created

  • name – Name of the shader to be created

  • mdlPath – Absolute or relative path to the MDL asset

  • module – Name of the MDL module to set as source asset sub-identifier for the shader

  • connectMaterialOutputs – If true, creates surface, displacement and volume outputs on the material and connects them to the shader output

Returns:

The newly created UsdShadeShader. Returns an Invalid prim on error.

pxr::UsdShadeInput usdex::rtx::createMdlShaderInput(
pxr::UsdShadeMaterial &material,
const pxr::TfToken &name,
const pxr::VtValue &value,
const pxr::SdfValueTypeName &typeName,
std::optional<const usdex::core::ColorSpace> colorSpace = std::nullopt,
)#

Create an MDL shader input.

If the shader input already exists and is a different type, defined in the current edit target layer -> it will be removed and recreated.

If the shader input already exists and has a connected source -> the source will be disconnected before being set.

Note

When creating texture asset inputs (diffuse, normal, roughness, etc.) it is important to set the colorSpace parameter so that the textures are sampled correctly. Typically, diffuse is “auto”, which resolves to “sRGB”. Normal, roughness, and other textures should be “raw”.

Parameters:

  • material – The UsdShadeMaterial prim that contains the MDL shader

  • name – Name of the input to be created

  • value – The value assigned to the input

  • typeName – The value type of the input

  • colorSpace – If set, the newly created input’s colorSpace attribute

Returns:

The newly created UsdShadeInput input. Returns an Invalid UsdShadeInput on error.

pxr::UsdShadeMaterial usdex::rtx::defineGlassMaterial(
pxr::UsdPrim parent,
const std::string &name,
const pxr::GfVec3f &color,
const float indexOfRefraction = 1.491f,
)#

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

The resulting Material prim will have “Interface” UsdShadeInputs which drive both render contexts. See Material and Shader Prims for use with the RTX Renderer for details.

Note: The use of MDL shaders inside this Material interface is considered an implementation detail of the RTX Renderer. Once the RTX Renderer supports OpenPBR or MaterialX shaders we may change the implementation to author those shaders instead of MDL.

Parameters:

  • parent – Prim below which to define the Material

  • name – Name of the Material

  • color – The color of the Material

  • indexOfRefraction – The Index of Refraction to set, 1.0-4.0 range

Returns:

The newly defined UsdShadeMaterial. Returns an Invalid prim on error

pxr::UsdShadeMaterial usdex::rtx::defineGlassMaterial(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const pxr::GfVec3f &color,
const float indexOfRefraction = 1.491f,
)#

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

The resulting Material prim will have “Interface” UsdShadeInputs which drive both render contexts. See Material and Shader Prims for use with the RTX Renderer for details.

Note: The use of MDL shaders inside this Material interface is considered an implementation detail of the RTX Renderer. Once the RTX Renderer supports OpenPBR or MaterialX shaders we may change the implementation to author those shaders instead of MDL.

Parameters:

  • stage – The stage on which to define the Material

  • path – The absolute prim path at which to define the Material

  • color – The color of the Material

  • indexOfRefraction – The Index of Refraction to set, 1.0-4.0 range

Returns:

The newly defined UsdShadeMaterial. Returns an Invalid prim on error

pxr::UsdShadeMaterial usdex::rtx::definePbrMaterial(
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 interface that drives both an RTX render context and the universal render context.

The resulting Material prim will have “Interface” UsdShadeInputs which drive both render contexts. See Material and Shader Prims for use with the RTX Renderer for details.

Note

The use of MDL shaders inside this Material interface is considered an implementation detail of the RTX Renderer. Once the RTX Renderer supports OpenPBR or MaterialX shaders we may change the implementation to author those shaders instead of MDL.

Parameters:

  • stage – The stage on which to define the Material

  • path – The absolute prim path at which to define the Material

  • color – The diffuse color of the Material

  • opacity – The Opacity Amount to set, 0.0-1.0 range where 1.0 = opaque and 0.0 = invisible. Enable Opacity will be set to true and Fractional Opacity will be enabled in the RT renderer.

  • roughness – The Roughness Amount to set, 0.0-1.0 range where 1.0 = flat and 0.0 = glossy

  • metallic – The Metallic Amount to set, 0.0-1.0 range where 1.0 = max metallic and 0.0 = no metallic

Returns:

The newly defined UsdShadeMaterial. Returns an Invalid prim on error

pxr::UsdShadeMaterial usdex::rtx::definePbrMaterial(
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 interface that drives both an RTX render context and the universal render context.

The resulting Material prim will have “Interface” UsdShadeInputs which drive both render contexts. See Material and Shader Prims for use with the RTX Renderer for details.

Note

The use of MDL shaders inside this Material interface is considered an implementation detail of the RTX Renderer. Once the RTX Renderer supports OpenPBR or MaterialX shaders we may change the implementation to author those shaders instead of MDL.

Parameters:

  • parent – Prim below which to define the Material

  • name – Name of the Material

  • color – The diffuse color of the Material

  • opacity – The Opacity Amount to set, 0.0-1.0 range where 1.0 = opaque and 0.0 = invisible. Enable Opacity will be set to true and Fractional Opacity will be enabled in the RT renderer.

  • roughness – The Roughness Amount to set, 0.0-1.0 range where 1.0 = flat and 0.0 = glossy

  • metallic – The Metallic Amount to set, 0.0-1.0 range where 1.0 = max metallic and 0.0 = no metallic

Returns:

The newly defined UsdShadeMaterial. Returns an Invalid prim on error

On this page