Skip to content

Align UsdUVTexture wrap modes with USD specification#2979

Open
pixelsandpointers wants to merge 11 commits into
AcademySoftwareFoundation:mainfrom
pixelsandpointers:unify-wrap-modes
Open

Align UsdUVTexture wrap modes with USD specification#2979
pixelsandpointers wants to merge 11 commits into
AcademySoftwareFoundation:mainfrom
pixelsandpointers:unify-wrap-modes

Conversation

@pixelsandpointers

@pixelsandpointers pixelsandpointers commented Jun 13, 2026

Copy link
Copy Markdown
Contributor

Closes #2899

The wrap mode enum values for ND_UsdUVTexture_23 did not match those used by UsdUVTexture in OpenUSD, making round-trip interchange lossy. This PR aligns the names, defaults, and fallback behavior with the USD specification.

Changes

libraries/bxdf/usd_preview_surface.mtlx

  • Renamed enum values periodicrepeat and black is now explicitly included (was previously named constant)
  • Changed the default for wrapS/wrapT from periodic to useMetaData, matching the USD default

source/MaterialXRender/ImageHandler.h

  • Renamed AddressMode enum values: CONSTANTBLACK, PERIODICREPEAT to match USD terminology

GL / Metal / Slang texture handlers

  • Updated all references to the renamed enum values
  • Changed the default (unspecified) address mode fallback from REPEAT (GL: GL_REPEAT, Metal: MTLSamplerAddressModeRepeat) to BLACK (GL: GL_CLAMP_TO_BORDER, Metal: MTLSamplerAddressModeClampToBorderColor), matching USD's fallback from useMetaData when no metadata is present

Not yet addressed

useMetaData is now accepted as the default enum value in the nodedef, but reading wrap modes from texture file metadata is not yet implemented — a follow-up is noted with a TODO (#2899) comment in both the nodedef and the AddressMode enum.

Note: `useMetaData` requires more clarification and will not be included
in the current PR.
Renames CONSTANT→BLACK and PERIODIC→REPEAT in ImageSamplingProperties::AddressMode
to match standard GPU/USD terminology, and changes the default (UNSPECIFIED) address
mode from Repeat to ClampToBorder across GL, Metal, and Slang backends so unspecified
samplers black-border rather than tile.
@pixelsandpointers

Copy link
Copy Markdown
Contributor Author

I think this is up for review @ld-kerley and @jstone-lucasfilm.

I am not entirely sure if all the changes I introduced were necessary (still fairly new to contributing to MtlX). Therefore, I am also uncertain if the versioning code should still target 1.39, or 1.40.

The useMetaData is not targeted in this PR. I added fallthrough and fallback cases to black. I may need to read a bit more about how OpenUSD handles useMetaData to propose a solution.

Happy for feedback and comments.

@jstone-lucasfilm

Copy link
Copy Markdown
Member

@pixelsandpointers I haven't yet done a full review, but on my first read-through, it looks like you're renaming the address modes of all texture nodes, including the core image node in MaterialX, when you probably mean to restrict this change to the UsdUVTexture node alone.

@pixelsandpointers

pixelsandpointers commented Jun 15, 2026

Copy link
Copy Markdown
Contributor Author

@jstone-lucasfilm I was not sure which files concretely touch what. I grepped for the ND_UsdUVTexture23 and applied the changes there first and later looked into the ImageHandler defining the enumerations. Afterwards, I followed all the old enum values in all downstream definitions and changed them to use the new ones..

Concretely, that means I need to revert which changes? I assume I need to revert the gltf definitions, right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

UsdUVTexture node has different valid wrap modes

2 participants