Skip to content

Align UsdUVTexture wrap modes with USD specification #2979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pixelsandpointers wants to merge 12 commits into
base: main
Choose a base branch
from
Open

Align UsdUVTexture wrap modes with USD specification #2979

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
cd0295a
Adjust nodedef to use new values and defaults
pixelsandpointers Jun 11, 2026
89b886b
Rename AddressMode enum values and fix default wrap mode
pixelsandpointers Jun 13, 2026
b9e84cd
Fix remaining MSL address modes
pixelsandpointers Jun 13, 2026
89671af
Make black wrap mode the default
pixelsandpointers Jun 13, 2026
bcd9a63
Merge branch 'main' into unify-wrap-modes
pixelsandpointers Jun 14, 2026
d76a211
Add fallback case for useMetaData
pixelsandpointers Jun 14, 2026
da68906
Add new test cases
pixelsandpointers Jun 14, 2026
a110a7a
Adjust library documents
pixelsandpointers Jun 14, 2026
54699a1
Versioning: map old constant and periodic to black and repeat
pixelsandpointers Jun 14, 2026
2b4c738
Change remaining enum case
pixelsandpointers Jun 14, 2026
13798a1
Remove header
pixelsandpointers Jun 14, 2026
ef0deda
Restrict USD wrap mode changes to UsdUVTexture, keep constant/black d…
pixelsandpointers Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions libraries/bxdf/usd_preview_surface.mtlx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@
<nodedef name="ND_UsdUVTexture_23" node="UsdUVTexture" nodegroup="texture2d" version="2.3" isdefaultversion="true">
<input name="file" type="filename" value="" uniform="true" />
<input name="st" type="vector2" defaultgeomprop="UV0" />
<input name="wrapS" type="string" value="periodic" enum="black,clamp,periodic,mirror" uniform="true" />
<input name="wrapT" type="string" value="periodic" enum="black,clamp,periodic,mirror" uniform="true" />
<input name="wrapS" type="string" value="useMetaData" enum="black,clamp,repeat,mirror,useMetaData" uniform="true" />
<input name="wrapT" type="string" value="useMetaData" enum="black,clamp,repeat,mirror,useMetaData" uniform="true" />
<input name="fallback" type="color4" value="0, 0, 0, 1" />
<input name="scale" type="color4" value="1, 1, 1, 1" uniform="true" />
<input name="bias" type="color4" value="0, 0, 0, 0" uniform="true" />
Expand Down
24 changes: 12 additions & 12 deletions libraries/stdlib/stdlib_defs.mtlx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,8 +128,8 @@
<input name="layer" type="string" value="" uiname="Layer" uniform="true" />
<input name="default" type="float" value="0.0" uiname="Default Color" />
<input name="texcoord" type="vector2" defaultgeomprop="UV0" uiname="Texture Coordinates" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode V" uniform="true" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode V" uniform="true" />
<input name="filtertype" type="string" value="linear" enum="closest,linear,cubic" uiname="Filter Type" uniform="true" />
<input name="framerange" type="string" value="" uiname="Frame Range" uniform="true" />
<input name="frameoffset" type="integer" value="0" uiname="Frame Offset" uniform="true" />
Expand All @@ -141,8 +141,8 @@
<input name="layer" type="string" value="" uiname="Layer" uniform="true" />
<input name="default" type="color3" value="0.0, 0.0, 0.0" uiname="Default Color" />
<input name="texcoord" type="vector2" defaultgeomprop="UV0" uiname="Texture Coordinates" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode V" uniform="true" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode V" uniform="true" />
<input name="filtertype" type="string" value="linear" enum="closest,linear,cubic" uiname="Filter Type" uniform="true" />
<input name="framerange" type="string" value="" uiname="Frame Range" uniform="true" />
<input name="frameoffset" type="integer" value="0" uiname="Frame Offset" uniform="true" />
Expand All @@ -154,8 +154,8 @@
<input name="layer" type="string" value="" uiname="Layer" uniform="true" />
<input name="default" type="color4" value="0.0, 0.0, 0.0, 0.0" uiname="Default Color" />
<input name="texcoord" type="vector2" defaultgeomprop="UV0" uiname="Texture Coordinates" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode V" uniform="true" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode V" uniform="true" />
<input name="filtertype" type="string" value="linear" enum="closest,linear,cubic" uiname="Filter Type" uniform="true" />
<input name="framerange" type="string" value="" uiname="Frame Range" uniform="true" />
<input name="frameoffset" type="integer" value="0" uiname="Frame Offset" uniform="true" />
Expand All @@ -167,8 +167,8 @@
<input name="layer" type="string" value="" uiname="Layer" uniform="true" />
<input name="default" type="vector2" value="0.0, 0.0" uiname="Default Color" />
<input name="texcoord" type="vector2" defaultgeomprop="UV0" uiname="Texture Coordinates" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode V" uniform="true" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode V" uniform="true" />
<input name="filtertype" type="string" value="linear" enum="closest,linear,cubic" uiname="Filter Type" uniform="true" />
<input name="framerange" type="string" value="" uiname="Frame Range" uniform="true" />
<input name="frameoffset" type="integer" value="0" uiname="Frame Offset" uniform="true" />
Expand All @@ -180,8 +180,8 @@
<input name="layer" type="string" value="" uiname="Layer" uniform="true" />
<input name="default" type="vector3" value="0.0, 0.0, 0.0" uiname="Default Color" />
<input name="texcoord" type="vector2" defaultgeomprop="UV0" uiname="Texture Coordinates" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode V" uniform="true" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode V" uniform="true" />
<input name="filtertype" type="string" value="linear" enum="closest,linear,cubic" uiname="Filter Type" uniform="true" />
<input name="framerange" type="string" value="" uiname="Frame Range" uniform="true" />
<input name="frameoffset" type="integer" value="0" uiname="Frame Offset" uniform="true" />
Expand All @@ -193,8 +193,8 @@
<input name="layer" type="string" value="" uiname="Layer" uniform="true" />
<input name="default" type="vector4" value="0.0, 0.0, 0.0, 0.0" uiname="Default Color" />
<input name="texcoord" type="vector2" defaultgeomprop="UV0" uiname="Texture Coordinates" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror" uiname="Address Mode V" uniform="true" />
<input name="uaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode U" uniform="true" />
<input name="vaddressmode" type="string" value="periodic" enum="constant,clamp,periodic,mirror,black,repeat,useMetaData" uiname="Address Mode V" uniform="true" />
<input name="filtertype" type="string" value="linear" enum="closest,linear,cubic" uiname="Filter Type" uniform="true" />
<input name="framerange" type="string" value="" uiname="Frame Range" uniform="true" />
<input name="frameoffset" type="integer" value="0" uiname="Frame Offset" uniform="true" />
Expand Down
63 changes: 38 additions & 25 deletions source/MaterialXCore/Version.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -977,34 +977,24 @@ void Document::upgradeVersion()
// Upgrade from 1.38 to 1.39
if (majorVersion == 1 && minorVersion == 38)
{
const std::unordered_map<char, size_t> CHANNEL_INDEX_MAP =
{
{ 'r', 0 }, { 'g', 1 }, { 'b', 2 }, { 'a', 3 },
{ 'x', 0 }, { 'y', 1 }, { 'z', 2 }, { 'w', 3 }
const std::unordered_map<char, size_t> CHANNEL_INDEX_MAP = {
{ 'r', 0 }, { 'g', 1 }, { 'b', 2 }, { 'a', 3 }, { 'x', 0 }, { 'y', 1 }, { 'z', 2 }, { 'w', 3 }
};
const std::unordered_map<char, float> CHANNEL_CONSTANT_MAP =
{
const std::unordered_map<char, float> CHANNEL_CONSTANT_MAP = {
{ '0', 0.0f }, { '1', 1.0f }
};
const std::unordered_map<string, size_t> CHANNEL_COUNT_MAP =
{
const std::unordered_map<string, size_t> CHANNEL_COUNT_MAP = {
{ "float", 1 },
{ "color3", 3 }, { "color4", 4 },
{ "vector2", 2 }, { "vector3", 3 }, { "vector4", 4 }
{ "color3", 3 },
{ "color4", 4 },
{ "vector2", 2 },
{ "vector3", 3 },
{ "vector4", 4 }
};
const std::array<std::pair<string, size_t>, 10> CHANNEL_CONVERT_PATTERNS =
{ {
{ "rgb", 3 }, { "rgb", 4 }, { "rgba", 4 },
{ "xyz", 3 }, { "xyz", 4 }, { "xyzw", 4 },
{ "rr", 1 }, { "rrr", 1 },
{ "xx", 1 }, { "xxx", 1 }
} };
const std::array<std::pair<StringSet, string>, 3> CHANNEL_ATTRIBUTE_PATTERNS =
{ {
{ { "xx", "xxx", "xxxx" }, "float" },
{ { "xyz", "x", "y", "z" }, "vector3" },
{ { "rgba", "a" }, "color4" }
} };
const std::array<std::pair<string, size_t>, 10> CHANNEL_CONVERT_PATTERNS = { { { "rgb", 3 }, { "rgb", 4 }, { "rgba", 4 }, { "xyz", 3 }, { "xyz", 4 }, { "xyzw", 4 }, { "rr", 1 }, { "rrr", 1 }, { "xx", 1 }, { "xxx", 1 } } };
const std::array<std::pair<StringSet, string>, 3> CHANNEL_ATTRIBUTE_PATTERNS = { { { { "xx", "xxx", "xxxx" }, "float" },
{ { "xyz", "x", "y", "z" }, "vector3" },
{ { "rgba", "a" }, "color4" } } };

// Convert channels attributes to legacy swizzle nodes, which are then converted
// to modern nodes in a second pass.
Expand Down Expand Up @@ -1281,7 +1271,7 @@ void Document::upgradeVersion()
}
}
else if (sourceType != destType && std::find(CHANNEL_CONVERT_PATTERNS.begin(), CHANNEL_CONVERT_PATTERNS.end(),
std::make_pair(channelString, sourceChannelCount)) != CHANNEL_CONVERT_PATTERNS.end())
std::make_pair(channelString, sourceChannelCount)) != CHANNEL_CONVERT_PATTERNS.end())
{
// Replace swizzle with convert.
node->setCategory("convert");
Expand Down Expand Up @@ -1405,7 +1395,7 @@ void Document::upgradeVersion()
// Clear tangent-space input.
node->removeInput("space");

// If the normal or tangent inputs are set and the bitangent input is not,
// If the normal or tangent inputs are set and the bitangent input is not,
// the bitangent should be set to normalize(cross(N, T))
InputPtr normalInput = node->getInput("normal");
InputPtr tangentInput = node->getInput("tangent");
Expand Down Expand Up @@ -1436,6 +1426,29 @@ void Document::upgradeVersion()
node->getParent()->removeChild(node->getName());
}

// Rename the UsdUVTexture "periodic" wrap mode to "repeat", aligning with the
// terminology used by the OpenUSD UsdUVTexture schema. This is purely a naming
// change: "periodic" and "repeat" describe identical sampling behavior. Unlike
// "periodic"/"repeat", "constant" and "black" are not interchangeable -- "constant"
// clamps to the node's configurable default color, while "black" always clamps to
// black -- so no rename is applied for that case.
for (ElementPtr elem : traverseTree())
{
NodePtr node = elem->asA<Node>();
if (!node)
{
continue;
}
for (const string& inputName : { string("wrapS"), string("wrapT") })
{
InputPtr input = node->getInput(inputName);
if (input && input->getValueString() == "periodic")
{
input->setValueString("repeat");
}
}
}

minorVersion = 39;
}

Expand Down
11 changes: 7 additions & 4 deletions source/MaterialXRender/ImageHandler.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,10 @@ class MX_RENDER_API ImageSamplingProperties
CONSTANT = 0,
CLAMP = 1,
PERIODIC = 2,
MIRROR = 3
MIRROR = 3,
BLACK = 4,
REPEAT = 5,
USE_META_DATA = 6
};

/// Address mode in U
Expand Down Expand Up @@ -94,11 +97,11 @@ struct MX_RENDER_API ImageSamplingKeyHasher
{
size_t operator()(const ImageSamplingProperties& k) const
{
return (size_t) k.enableMipmaps + // 1 bit
(((size_t) k.filterType & 3) << 1) + // 2 bit
return (size_t) k.enableMipmaps + // 1 bit
(((size_t) k.filterType & 3) << 1) + // 2 bit
((((size_t) k.uaddressMode + 1) & 7) << 3) + // 3 bit
((((size_t) k.vaddressMode + 1) & 7) << 6) + // 3 bit
((((size_t) k.defaultColor[0] + 1)) << 9) ;
((((size_t) k.defaultColor[0] + 1)) << 9);
}
};

Expand Down
Loading
Loading