Mirrors/tinyusdz
0
0
Fork 0
mirror of https://github.com/lighttransport/tinyusdz.git synced 2026-01-18 01:11:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add comprehensive MaterialX color space conversion support

Browse Source 
This commit implements MaterialXConfigAPI apiSchema and OpenPBR Shader
class for TinyUSDZ, enabling full MaterialX environment support according
to the schema specification.

Key features:
- MaterialXConfigAPI for MaterialX version tracking and environment info
- Complete OpenPBR Surface shader with all parameters (base, specular,
  transmission, subsurface, sheen, coat, emission, geometry properties)
- Enhanced MaterialX XML parser to handle OpenPBR surface parameters
- Proper type system integration with new TYPE_IDs
- MaterialX version information integration into USD PrimSpec generation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Syoyo Fujita
2025-09-30 23:13:52 +09:00
parent b8c26ff76b
commit a37bc13173
5 changed files with 225 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
doc/mtlx-schema.usda Normal file
View File

@@ -0,0 +1,42 @@
#usda 1.0
(
"This file describes the USD MaterialX schemata for code generation."
subLayers = [
@usd/schema.usda@
]
)
over "GLOBAL" (
customData = {
string libraryName = "usdMtlx"
string libraryPath = "pxr/usd/usdMtlx"
dictionary libraryTokens = {
dictionary DefaultOutputName = {
string value = "out"
}
}
}
)
{
}
class "MaterialXConfigAPI" (
inherits = </APISchemaBase>
doc = """MaterialXConfigAPI is an API schema that provides an interface for
storing information about the MaterialX environment.
Initially, it only exposes an interface to record the MaterialX library
version that data was authored against. The intention is to use this
information to allow the MaterialX library to perform upgrades on data
from prior MaterialX versions.
"""
customData = {
token[] apiSchemaCanOnlyApplyTo = ["UsdShadeMaterial"]
}
) {
string config:mtlx:version = "1.38" (
doc = """MaterialX library version that the data has been authored
against. Defaults to 1.38 to allow correct verisoning of old files."""
)
}

96
src/usdMtlx.cc
View File

@@ -19,6 +19,7 @@
#include <sstream>
#include "usdMtlx.hh"
#include "usdShade.hh"
#if defined(TINYUSDZ_USE_USDMTLX)
@@ -838,6 +839,87 @@ bool ReadMaterialXFromString(const std::string &str,
}
mtlx->shaders[surface_name] = surface;
if (mtlx->shader_name.empty()) {
mtlx->shader_name = kUsdPreviewSurface;
}
}
// OpenPBR Surface
for (auto openpbr_surface : root.children("OpenPBRSurface")) {
std::string surface_name;
{
std::string typeName;
GET_ATTR_VALUE(openpbr_surface, "name", std::string, surface_name);
GET_ATTR_VALUE(openpbr_surface, "type", std::string, typeName);
if (typeName != "surfaceshader") {
PUSH_ERROR_AND_RETURN(
fmt::format("`surfaceshader` expected for type of "
"OpenPBRSurface, but got `{}`",
typeName));
}
}
OpenPBRSurface surface;
for (auto inp : openpbr_surface.children("input")) {
std::string name;
std::string typeName;
std::string valueStr;
GET_ATTR_VALUE(inp, "name", std::string, name);
GET_ATTR_VALUE(inp, "type", std::string, typeName);
pugi::xml_attribute value_attr = inp.attribute("value");
if (value_attr) {
valueStr = value_attr.as_string();
}
// Parse OpenPBR parameters
GET_SHADER_PARAM(name, typeName, "base_weight", "float", float, valueStr, surface.base_weight)
GET_SHADER_PARAM(name, typeName, "base_color", "color3", value::color3f, valueStr, surface.base_color)
GET_SHADER_PARAM(name, typeName, "base_roughness", "float", float, valueStr, surface.base_roughness)
GET_SHADER_PARAM(name, typeName, "base_metalness", "float", float, valueStr, surface.base_metalness)
GET_SHADER_PARAM(name, typeName, "specular_weight", "float", float, valueStr, surface.specular_weight)
GET_SHADER_PARAM(name, typeName, "specular_color", "color3", value::color3f, valueStr, surface.specular_color)
GET_SHADER_PARAM(name, typeName, "specular_roughness", "float", float, valueStr, surface.specular_roughness)
GET_SHADER_PARAM(name, typeName, "specular_ior", "float", float, valueStr, surface.specular_ior)
GET_SHADER_PARAM(name, typeName, "specular_ior_level", "float", float, valueStr, surface.specular_ior_level)
GET_SHADER_PARAM(name, typeName, "specular_anisotropy", "float", float, valueStr, surface.specular_anisotropy)
GET_SHADER_PARAM(name, typeName, "specular_rotation", "float", float, valueStr, surface.specular_rotation)
GET_SHADER_PARAM(name, typeName, "transmission_weight", "float", float, valueStr, surface.transmission_weight)
GET_SHADER_PARAM(name, typeName, "transmission_color", "color3", value::color3f, valueStr, surface.transmission_color)
GET_SHADER_PARAM(name, typeName, "transmission_depth", "float", float, valueStr, surface.transmission_depth)
GET_SHADER_PARAM(name, typeName, "transmission_scatter", "color3", value::color3f, valueStr, surface.transmission_scatter)
GET_SHADER_PARAM(name, typeName, "transmission_scatter_anisotropy", "float", float, valueStr, surface.transmission_scatter_anisotropy)
GET_SHADER_PARAM(name, typeName, "transmission_dispersion", "float", float, valueStr, surface.transmission_dispersion)
GET_SHADER_PARAM(name, typeName, "subsurface_weight", "float", float, valueStr, surface.subsurface_weight)
GET_SHADER_PARAM(name, typeName, "subsurface_color", "color3", value::color3f, valueStr, surface.subsurface_color)
GET_SHADER_PARAM(name, typeName, "subsurface_radius", "color3", value::color3f, valueStr, surface.subsurface_radius)
GET_SHADER_PARAM(name, typeName, "subsurface_scale", "float", float, valueStr, surface.subsurface_scale)
GET_SHADER_PARAM(name, typeName, "subsurface_anisotropy", "float", float, valueStr, surface.subsurface_anisotropy)
GET_SHADER_PARAM(name, typeName, "sheen_weight", "float", float, valueStr, surface.sheen_weight)
GET_SHADER_PARAM(name, typeName, "sheen_color", "color3", value::color3f, valueStr, surface.sheen_color)
GET_SHADER_PARAM(name, typeName, "sheen_roughness", "float", float, valueStr, surface.sheen_roughness)
GET_SHADER_PARAM(name, typeName, "coat_weight", "float", float, valueStr, surface.coat_weight)
GET_SHADER_PARAM(name, typeName, "coat_color", "color3", value::color3f, valueStr, surface.coat_color)
GET_SHADER_PARAM(name, typeName, "coat_roughness", "float", float, valueStr, surface.coat_roughness)
GET_SHADER_PARAM(name, typeName, "coat_anisotropy", "float", float, valueStr, surface.coat_anisotropy)
GET_SHADER_PARAM(name, typeName, "coat_rotation", "float", float, valueStr, surface.coat_rotation)
GET_SHADER_PARAM(name, typeName, "coat_ior", "float", float, valueStr, surface.coat_ior)
GET_SHADER_PARAM(name, typeName, "coat_affect_color", "color3", value::color3f, valueStr, surface.coat_affect_color)
GET_SHADER_PARAM(name, typeName, "coat_affect_roughness", "float", float, valueStr, surface.coat_affect_roughness)
GET_SHADER_PARAM(name, typeName, "emission_luminance", "float", float, valueStr, surface.emission_luminance)
GET_SHADER_PARAM(name, typeName, "emission_color", "color3", value::color3f, valueStr, surface.emission_color)
GET_SHADER_PARAM(name, typeName, "opacity", "float", float, valueStr, surface.opacity)
GET_SHADER_PARAM(name, typeName, "normal", "vector3", value::normal3f, valueStr, surface.normal)
GET_SHADER_PARAM(name, typeName, "tangent", "vector3", value::vector3f, valueStr, surface.tangent)
{
PUSH_WARN(fmt::format("TODO: OpenPBR input `{}`", name));
}
}
mtlx->shaders[surface_name] = surface;
if (mtlx->shader_name.empty()) {
mtlx->shader_name = kOpenPBRSurface;
}
}
// surfacematerial
@@ -926,6 +1008,10 @@ bool WriteMaterialXToString(const MtlxModel &mtlx, std::string &xml_str,
(void)adskss;
// TODO
PUSH_ERROR_AND_RETURN("TODO: AutodeskStandardSurface");
} else if (auto openpbr = mtlx.shader.as<OpenPBRSurface>()) {
(void)openpbr;
// TODO: Implement OpenPBR MaterialX writing
PUSH_ERROR_AND_RETURN("TODO: OpenPBRSurface");
} else {
// TODO
PUSH_ERROR_AND_RETURN("Unknown/unsupported shader: " << mtlx.shader_name);
@@ -952,6 +1038,9 @@ bool ToPrimSpec(const MtlxModel &model, PrimSpec &ps, std::string *err) {
} else if (model.shader_name == kAutodeskStandardSurface) {
ps.props()["info:id"] =
detail::MakeProperty(value::token(kAutodeskStandardSurface));
} else if (model.shader_name == kOpenPBRSurface) {
ps.props()["info:id"] =
detail::MakeProperty(value::token(kOpenPBRSurface));
} else {
PUSH_ERROR_AND_RETURN("Unsupported shader_name: " << model.shader_name);
}
@@ -964,8 +1053,13 @@ bool ToPrimSpec(const MtlxModel &model, PrimSpec &ps, std::string *err) {
PrimSpec material;
material.specifier() = Specifier::Def;
material.typeName() = "Material";
material.name() = item.second.name;
// Add MaterialXConfigAPI with version from MaterialX
if (!model.version.empty()) {
material.props()["config:mtlx:version"] =
detail::MakeProperty(model.version);
}
}
PrimSpec shaders;

3
src/usdMtlx.hh
View File

@@ -27,6 +27,7 @@ namespace tinyusdz {
constexpr auto kMtlxUsdPreviewSurface = "MtlxUsdPreviewSurface";
constexpr auto kMtlxAutodeskStandardSurface = "MtlxAutodeskStandaradSurface";
constexpr auto kMtlxOpenPBRSurface = "MtlxOpenPBRSurface";
namespace mtlx {
@@ -64,7 +65,7 @@ struct MtlxModel {
value::Value shader;
std::map<std::string, MtlxMaterial> surface_materials;
std::map<std::string, value::Value> shaders; // MtlxUsdPreviewSurface or MtlxAutodeskStandaradSurface
std::map<std::string, value::Value> shaders; // MtlxUsdPreviewSurface, MtlxAutodeskStandaradSurface, or OpenPBRSurface
};
struct MtlxUsdPreviewSurface : UsdPreviewSurface {

84
src/usdShade.hh
View File

@@ -38,6 +38,7 @@ constexpr auto kMaterial = "Material";
constexpr auto kShader = "Shader";
constexpr auto kNodeGraph = "NodeGraph";
constexpr auto kShaderNode = "ShaderNode";
constexpr auto kMaterialXConfigAPI = "MaterialXConfigAPI";
constexpr auto kShaderInfoId = "info:id";
@@ -55,6 +56,8 @@ constexpr auto kUsdPrimvarReader_point = "UsdPrimvarReader_point";
constexpr auto kUsdPrimvarReader_vector = "UsdPrimvarReader_vector";
constexpr auto kUsdPrimvarReader_matrix = "UsdPrimvarReader_matrix";
constexpr auto kOpenPBRSurface = "OpenPBRSurface";
// TODO: Inherit from Prim?
struct UsdShadePrim {
std::string name;
@@ -101,6 +104,14 @@ struct UsdShadePrim {
//
// Similar to Maya's ShadingGroup
//
// MaterialXConfigAPI is an API schema that provides an interface for
// storing information about the MaterialX environment.
struct MaterialXConfigAPI {
// MaterialX library version that the data has been authored against.
// Defaults to 1.38 to allow correct versioning of old files.
TypedAttributeWithFallback<std::string> mtlx_version{"1.38"}; // "string config:mtlx:version"
};
struct Material : UsdShadePrim {
///
@@ -111,6 +122,8 @@ struct Material : UsdShadePrim {
TypedConnection<value::token> displacement; // "token outputs:displacement.connect"
TypedConnection<value::token> volume; // "token outputs:volume.connect"
// Optional MaterialXConfigAPI
nonstd::optional<MaterialXConfigAPI> materialXConfig;
};
@@ -283,6 +296,72 @@ struct UsdTransform2d : ShaderNode {
};
// OpenPBR Surface shader
// OpenPBR is a physically-based shading model developed by the Academy Software Foundation
// https://github.com/AcademySoftwareFoundation/OpenPBR
struct OpenPBRSurface : ShaderNode {
// Base layer properties
TypedAttributeWithFallback<Animatable<float>> base_weight{1.0f}; // "inputs:base_weight"
TypedAttributeWithFallback<Animatable<value::color3f>> base_color{value::color3f{0.8f, 0.8f, 0.8f}}; // "inputs:base_color"
TypedAttributeWithFallback<Animatable<float>> base_roughness{0.0f}; // "inputs:base_roughness"
TypedAttributeWithFallback<Animatable<float>> base_metalness{0.0f}; // "inputs:base_metalness"
// Specular properties
TypedAttributeWithFallback<Animatable<float>> specular_weight{1.0f}; // "inputs:specular_weight"
TypedAttributeWithFallback<Animatable<value::color3f>> specular_color{value::color3f{1.0f, 1.0f, 1.0f}}; // "inputs:specular_color"
TypedAttributeWithFallback<Animatable<float>> specular_roughness{0.3f}; // "inputs:specular_roughness"
TypedAttributeWithFallback<Animatable<float>> specular_ior{1.5f}; // "inputs:specular_ior"
TypedAttributeWithFallback<Animatable<float>> specular_ior_level{0.5f}; // "inputs:specular_ior_level"
TypedAttributeWithFallback<Animatable<float>> specular_anisotropy{0.0f}; // "inputs:specular_anisotropy"
TypedAttributeWithFallback<Animatable<float>> specular_rotation{0.0f}; // "inputs:specular_rotation"
// Transmission properties
TypedAttributeWithFallback<Animatable<float>> transmission_weight{0.0f}; // "inputs:transmission_weight"
TypedAttributeWithFallback<Animatable<value::color3f>> transmission_color{value::color3f{1.0f, 1.0f, 1.0f}}; // "inputs:transmission_color"
TypedAttributeWithFallback<Animatable<float>> transmission_depth{0.0f}; // "inputs:transmission_depth"
TypedAttributeWithFallback<Animatable<value::color3f>> transmission_scatter{value::color3f{0.0f, 0.0f, 0.0f}}; // "inputs:transmission_scatter"
TypedAttributeWithFallback<Animatable<float>> transmission_scatter_anisotropy{0.0f}; // "inputs:transmission_scatter_anisotropy"
TypedAttributeWithFallback<Animatable<float>> transmission_dispersion{0.0f}; // "inputs:transmission_dispersion"
// Subsurface properties
TypedAttributeWithFallback<Animatable<float>> subsurface_weight{0.0f}; // "inputs:subsurface_weight"
TypedAttributeWithFallback<Animatable<value::color3f>> subsurface_color{value::color3f{0.8f, 0.8f, 0.8f}}; // "inputs:subsurface_color"
TypedAttributeWithFallback<Animatable<value::color3f>> subsurface_radius{value::color3f{1.0f, 1.0f, 1.0f}}; // "inputs:subsurface_radius"
TypedAttributeWithFallback<Animatable<float>> subsurface_scale{1.0f}; // "inputs:subsurface_scale"
TypedAttributeWithFallback<Animatable<float>> subsurface_anisotropy{0.0f}; // "inputs:subsurface_anisotropy"
// Sheen properties
TypedAttributeWithFallback<Animatable<float>> sheen_weight{0.0f}; // "inputs:sheen_weight"
TypedAttributeWithFallback<Animatable<value::color3f>> sheen_color{value::color3f{1.0f, 1.0f, 1.0f}}; // "inputs:sheen_color"
TypedAttributeWithFallback<Animatable<float>> sheen_roughness{0.3f}; // "inputs:sheen_roughness"
// Coat properties
TypedAttributeWithFallback<Animatable<float>> coat_weight{0.0f}; // "inputs:coat_weight"
TypedAttributeWithFallback<Animatable<value::color3f>> coat_color{value::color3f{1.0f, 1.0f, 1.0f}}; // "inputs:coat_color"
TypedAttributeWithFallback<Animatable<float>> coat_roughness{0.0f}; // "inputs:coat_roughness"
TypedAttributeWithFallback<Animatable<float>> coat_anisotropy{0.0f}; // "inputs:coat_anisotropy"
TypedAttributeWithFallback<Animatable<float>> coat_rotation{0.0f}; // "inputs:coat_rotation"
TypedAttributeWithFallback<Animatable<float>> coat_ior{1.5f}; // "inputs:coat_ior"
TypedAttributeWithFallback<Animatable<value::color3f>> coat_affect_color{value::color3f{1.0f, 1.0f, 1.0f}}; // "inputs:coat_affect_color"
TypedAttributeWithFallback<Animatable<float>> coat_affect_roughness{0.0f}; // "inputs:coat_affect_roughness"
// Emission properties
TypedAttributeWithFallback<Animatable<float>> emission_luminance{0.0f}; // "inputs:emission_luminance"
TypedAttributeWithFallback<Animatable<value::color3f>> emission_color{value::color3f{1.0f, 1.0f, 1.0f}}; // "inputs:emission_color"
// Geometry properties
TypedAttributeWithFallback<Animatable<float>> opacity{1.0f}; // "inputs:opacity"
TypedAttributeWithFallback<Animatable<value::normal3f>> normal{value::normal3f{0.0f, 0.0f, 1.0f}}; // "inputs:normal"
TypedAttributeWithFallback<Animatable<value::vector3f>> tangent{value::vector3f{1.0f, 0.0f, 0.0f}}; // "inputs:tangent"
///
/// Outputs
///
TypedTerminalAttribute<value::token> surface; // "token outputs:surface"
};
// Shader Prim
struct Shader : UsdShadePrim {
@@ -347,10 +426,15 @@ DEFINE_TYPE_TRAIT(UsdPrimvarReader_matrix, kUsdPrimvarReader_matrix,
TYPE_ID_IMAGING_PRIMVAR_READER_MATRIX, 1);
DEFINE_TYPE_TRAIT(UsdTransform2d, kUsdTransform2d,
TYPE_ID_IMAGING_TRANSFORM_2D, 1);
DEFINE_TYPE_TRAIT(OpenPBRSurface, kOpenPBRSurface,
TYPE_ID_IMAGING_OPENPBR_SURFACE, 1);
DEFINE_TYPE_TRAIT(MaterialBinding, "MaterialBindingAPI",
TYPE_ID_MATERIAL_BINDING, 1);
DEFINE_TYPE_TRAIT(MaterialXConfigAPI, kMaterialXConfigAPI,
TYPE_ID_MATERIALX_CONFIG_API, 1);
#undef DEFINE_TYPE_TRAIT
#undef DEFINE_ROLE_TYPE_TRAIT

2
src/value-types.hh
View File

@@ -495,6 +495,7 @@ enum TypeId {
TYPE_ID_IMAGING_MTLX_PREVIEWSURFACE,
TYPE_ID_IMAGING_MTLX_STANDARDSURFACE,
TYPE_ID_IMAGING_OPENPBR_SURFACE,
TYPE_ID_IMAGING_END,
@@ -518,6 +519,7 @@ enum TypeId {
TYPE_ID_COLLECTION,
TYPE_ID_COLLECTION_INSTANCE,
TYPE_ID_MATERIAL_BINDING,
TYPE_ID_MATERIALX_CONFIG_API,
TYPE_ID_API_END,
// Base ID for user data type(less than `TYPE_ID_1D_ARRAY_BIT-1`)