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

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

Enumerations#

enum class usdex::core::ColorSpace#

Texture color space (encoding) types.

Values:

enumerator eAuto#

Check for gamma or metadata in the texture itself.

enumerator eRaw#

Use linear sampling (typically used for Normal, Roughness, Metallic, Opacity textures, or when using high dynamic range file formats like EXR)

enumerator eSrgb#

Use sRGB sampling (typically used for Diffuse textures when using PNG files)

Functions#

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

Adds a diffuse texture to a preview material.

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Note

If you intend to create a Material Interface, it is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface(). This function will not attempt to reconcile any existing inputs on the Material.

Parameters:

  • material – The material prim

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

Adds a single channel metallic texture to a preview material.

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Note

If you intend to create a Material Interface, it is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface(). This function will not attempt to reconcile any existing inputs on the Material.

Parameters:

  • material – The material prim

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

Adds a normals texture to a preview material.

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

The UsdPreviewSurface specification requires the texture reader to provide data that is properly scaled and ready to be consumed as a tangent space normal. Textures stored in 8-bit file formats require scale and bias adjustment to transform the normals into tangent space.

This module cannot read the provided texturePath to inspect the channel data (the file may not resolve locally, or even exist yet). To account for this, it performs the scale and bias adjustment when the texturePath extension matches a list of known 8-bit formats: ["bmp", "tga", "jpg", "jpeg", "png", "tif"]. Similarly, it assumes that the raw normals data was written into the file, regardless of any file format specific color space metadata. If either of these assumptions is incorrect for your source data, you will need to adjust the scale, bias, and sourceColorSpace settings after calling this function.

Note

If you intend to create a Material Interface, it is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface(). This function will not attempt to reconcile any existing inputs on the Material.

Parameters:

  • material – The material prim

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

Adds a single channel opacity texture to a preview material.

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

In addition to driving the opacity input, these additional shader inputs will be set explicitly, to produce better masked geometry:

  • UsdPreviewSurface: ior = 1.0

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

Note

If you intend to create a Material Interface, it is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface(). This function will not attempt to reconcile any existing inputs on the Material.

Parameters:

  • material – The material prim

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

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

An ORM texture is a normal 3-channel image asset, where the R channel represents occlusion, the G channel represents roughness, and the B channel represents metallic/metallness.

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Note

If you intend to create a Material Interface, it is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface(). This function will not attempt to reconcile any existing inputs on the Material.

Parameters:

  • material – The material prim

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

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

All non-default-value UsdShadeInputs on the effective surface shader for the universal render context will be “promoted” to the UsdShadeMaterial as new UsdShadeInputs. They will be connected to the original source inputs on the shaders, to drive those values, and they will be authored with a value matching what had been set on the shader inputs at the time this function was called.

Additionally, UsdUVTexture.file inputs on connected shaders will be promoted to the material, following the same logic as direct surface inputs.

Note

It is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface().

Warning

This function will fail if there is any other render context driving the material surface. It is only suitable for use on Preview Shader networks, such as the network generated by definePreviewMaterial() and its associated add*Texture functions. If you require multiple contexts, you should instead construct a Material Interface directly, or with targetted end-user interaction.

Parameters:

material – The material prim

Returns:

Whether or not the Material inputs were added successfully

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

Adds a single channel roughness texture to a preview material.

It is expected that the material was created by definePreviewMaterial()

The texture will be sampled using texture coordinates from the default UV set (generally named primvars:st).

Note

If you intend to create a Material Interface, it is preferable to author all initial shader attributes (including textures) before calling addPreviewMaterialInterface(). This function will not attempt to reconcile any existing inputs on the Material.

Parameters:

  • material – The material prim

  • texturePath – The SdfAssetPath to the texture file

Returns:

Whether or not the texture was added to the material

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

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

Validates both the prim and the material, applies the UsdShadeMaterialBindingAPI to the target prim, and binds the material to the target prim.

Note

The material is bound with the default “all purpose” used for both full and preview rendering, and with the default “fallback strength” meaning descendant prims can override with a different material. If alternate behavior is desired, use the UsdShadeMaterialBindingAPI directly.

Parameters:

  • prim – The prim that the material will affect

  • material – The material to bind to the prim

Returns:

Whether the material was successfully bound to the target prim.

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

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

Parameters:

material – The Material to consider

Returns:

The connected Shader. Returns an invalid shader object on error.

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

Create a UsdShadeMaterial as a child of the Prim parent.

Parameters:

  • parent – Parent prim of the new material

  • name – Name of the material to be created

Returns:

The newly created UsdShadeMaterial. Returns an invalid material object on error.

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.

The input parameters reflect a subset of the UsdPreviewSurface specification commonly used when authoring materials using the metallic/metalness workflow (as opposed to the specular workflow). Many other inputs are available and can be authored after calling this function (including switching to the specular workflow).

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

  • 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 object on error.

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.

The input parameters reflect a subset of the UsdPreviewSurface specification commonly used when authoring materials using the metallic/metalness workflow (as opposed to the specular workflow). Many other inputs are available and can be authored after calling this function (including switching to the specular workflow).

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

  • 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 object on error.

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

Get the TfToken matching a given ColorSpace

The token representation is typically used when setting shader inputs, such as inputs:sourceColorSpace on UsdUVTexture.

Parameters:

value – The ColorSpace

Returns:

The token for the given ColorSpace value

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

Translate a linear color value to sRGB color space.

Many 3D modeling applications define colors in sRGB (0-1) color space. Many others use a linear color space that aligns with how light and color behave in the natural world. When authoring UsdShadeShader color input data, including external texture assets, you may need to translate between color spaces.

Note

Color is a complex topic in 3D rendering and providing utilities covering the full breadth of color science is beyond the scope of this module. See this MathWorks article for a relatively brief introduction. If you need more specific color handling please use a dedicated color science library like OpenColorIO.

Parameters:

color – linear representation of a color to be translated to sRGB color space

Returns:

The color in sRGB color space

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

Removes any UsdShadeInputs found on the material prim.

All UsdShadeInputs on the UsdShadeMaterial will be disconnected from any underlying shader inputs, then removed from the material. The current values may be optionally “baked down” onto the shader inputs in order to retain the current material behavior, or may be discarded in order to revert to a default appearance based on the shader definitions.

Note

While addPreviewMaterialInterface is specific to Preview Material shader networks, removeMaterialInterface affects all render contexts and will remove all UsdShadeInputs returned via UsdShadeMaterial::GetInterfaceInputs(), baking down the values onto all consumer shaders, regardless of render context.

Parameters:

  • material – The material prim

  • bakeValues – Whether or not the current Material inputs values are set on the underlying Shader inputs

Returns:

Whether or not the Material inputs were removed successfully

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

Translate an sRGB color value to linear color space.

Many 3D modeling applications define colors in sRGB (0-1) color space. Many others use a linear color space that aligns with how light and color behave in the natural world. When authoring UsdShadeShader color input data, including external texture assets, you may need to translate between color spaces.

Note

Color is a complex topic in 3D rendering and providing utilities covering the full breadth of color science is beyond the scope of this module. See this MathWorks article for a relatively brief introduction. If you need more specific color handling please use a dedicated color science library like OpenColorIO.

Parameters:

color – sRGB representation of a color to be translated to linear color space

Returns:

The translated color in linear color space

On this page