USDMeshLight by ericmehl · Pull Request #6970 · GafferHQ/gaffer

ericmehl · 2026-06-11T15:39:05Z

This adds USDMeshLight support for Arnold and RenderMan. The USD spec, in the default mode, calls for taking the mesh light color texture from the surface shader, if one exists. There are a couple of other simpler modes I haven't implemented yet, but I can add those in a follow-up PR or add them on here.

There's also new support in this PR for visualising mesh light textures using the existing renderer-specific texture registration system. I didn't implement the surface texture swapping for those visulisations, but it can also be added once we're happy with the overall direction here.

Checklist

I have read the contribution guidelines.
I have updated the documentation, if applicable.
I have tested my change(s) in the test suite, and added new test cases where necessary.
My code follows the Gaffer project's prevailing coding style and conventions.

ericmehl · 2026-06-11T19:21:24Z

There was a test failure from GafferUSDUITest.DocumentationTest where it was finding the plugs on USDMeshLight were not documented. I believe that is because we are calling loadShader() in a lambda that is passed to the MeshLight constructor which means the plugs arr present for that test. Unlike other shaders which won't have been loaded yet.

I didn't see a particularly good fallback, but USD has updated their attribute descriptions in the USDLux schema, so I think it might be ready to use again.

That along with a placeholder description for the Arnold parameters satisfies the documentation requirement for all plugs.

johnhaddon

Thanks Eric! Comments inline as usual. In addition to those, I think it's also worth adding a conversion to 3Delight, since folks have been asking for better support on Discord recently. Similarly I think there's a decent case for adding for Cycles too, since the existing CyclesMeshLight is a bit of a weird anomaly (it doesn't actually make a light).

johnhaddon · 2026-06-15T11:34:29Z

+	def testVisibilityAttributes( self ) :
+
+		# Visibility attributes are renderer-specific. They are handled and tested
+		# by the renderer `Attributes` methods.


Does this refer to Renderer::attributes(), or something else?

Yes, that's what I was getting at. I clarified it in bff4c97

It seems a bit of an odd test then given the method name - all it's really asserting is that there's just one attribute, and it's called light. Can we just put that assertion in one of the other tests?

johnhaddon · 2026-06-15T11:53:58Z

@@ -1345,11 +1337,32 @@ class ArnoldAttributes : public IECoreScenePreview::Renderer::AttributesInterfac

 				m_surfaceShader = newLightSurface ? shaderCache->get( newLightSurface.get(), surfaceName, attributes ) : nullptr;
 				m_lightShader = newLightShader;
+
+				modifiedAttributes = attributes->copy();
+				modifiedAttributes->members().try_emplace( g_cameraVisibilityAttributeName, new IECore::BoolData( true ) );
+				modifiedAttributes->members().try_emplace( g_shadowVisibilityAttributeName, new IECore::BoolData( false ) );
+				modifiedAttributes->members().try_emplace( g_diffuseReflectVisibilityAttributeName, new IECore::BoolData( false ) );
+				modifiedAttributes->members().try_emplace( g_specularReflectVisibilityAttributeName, new IECore::BoolData( false ) );
+				modifiedAttributes->members().try_emplace( g_diffuseTransmitVisibilityAttributeName, new IECore::BoolData( false ) );
+				modifiedAttributes->members().try_emplace( g_specularTransmitVisibilityAttributeName, new IECore::BoolData( false ) );
+				modifiedAttributes->members().try_emplace( g_volumeVisibilityAttributeName, new IECore::BoolData( false ) );
+				modifiedAttributes->members().try_emplace( g_subsurfaceVisibilityAttributeName, new IECore::BoolData( false ) );
+				attributes = modifiedAttributes.get();


I think this is a bit weird from a separation-of-concerns point of view. We have logic here to determine that it's a mesh light and will need some processing, and to find the surface shader for processing. Then we defer to a function to deal with thos, and then add on the processing of the attributes ourselves. Can we instead have the entire thing behind a single function?

ConstCompoundObjectPtr convertUSDMeshLights( const CompoundObject *attributes ) { if( notAMeshLight ) { return inputAttributes; } CompoundObjectPtr result = attributes->copy(); // Modify light shader. // Assign visibility attributes. return result; }

This structure would also extend easily to dealing with materialSyncMode, allowing us to hide all the details of that from ArnoldAttributes.

I've moved the conversion code and all of the attribute handling to a separate function in ec5787c

I was kindof thinking the single function would be the one exposed by ShaderNetworkAlgo. If we want to extend to respect materialSyncMode then currently things are awkward because we don't have all the information in one place. ShaderNetworkAlgo is technically public API, so it's worth getting the signature right now. Having all the functionality in there may also make testing easier, since we can test the output data instead of querying an Arnold universe.

johnhaddon · 2026-06-15T13:15:27Z

+		)
+		{
+			glowColorParameter = { handle, g_glowColorParameter };
+			glowIntensityParameter = { handle, g_glowGainParameter };


I'm not seeing any effect from changing PxrSurface.glowGain.

That was a victim of my move-glow-to-light approach. It's fixed now with 97f4044

I'm still seeing behaviour I don't expect :

The light colour is affecting the colour I see in primary rays.

The PxrSurface glowGain is having no effect in primary rays.

Here's what I get when changing glowGain :

Just to double check terminology, primary rays are camera rays, so the directly visible intensity (not reflections or illumination) isn't changing for you?

Yeah glowGain is having no effect on the directly visible (to the camera) intensity for me. I can set it to zero and still see the light, and set it to lots and get the same render. Maybe I'm doing something wrong? Happy to share a screen if it would help...

johnhaddon · 2026-06-15T13:17:56Z

+
+		if( glowColorParameter )
+		{
+			newSurfaceShader->parameters()[glowColorParameter.name] = new Color3fData( Color3f( 0.f ) );


As for the Arnold case, I'm not sure why we need to modify the surface shader. But on the other hand, I am seeing the glow color in the camera-visible light, so I assume something is different in RenderMan. Can you explain exactly what we're doing?

In theory, 97f4044 should fix this by leaving the surface shader alone.

I'm not sure why the glow color in the camera-visible light is still showing up. If I recreate the post-conversion USD light setup using RenderMan shaders (PxrSurface and RenderManMeshLight) I can't see where we could make the emission part not visible to the camera. The surface and light colors seem to be additive for camera rays.

The surface and light colors seem to be additive for camera rays.

Can we check what happens with a MeshLight/PxrSurface combo in usdview? I'm wondering if there's something wrong with the way I was handling PxrMeshLight in the first place.

johnhaddon · 2026-06-15T13:22:45Z

+			modifiedAttributes = attributes->copy();
+			modifiedAttributes->members().try_emplace( g_visibilityIndirectAttributeName, new BoolData( false ) );
+			modifiedAttributes->members().try_emplace( g_visibilityTransmissionAttributeName, new BoolData( false ) );
+			modifiedAttributes->members().try_emplace( g_visibilityCameraAttributeName, new BoolData( true ) );
+			attributes = modifiedAttributes.get();


Came comment as for Arnold - I think we can encapsulate all this logic in one ShaderNetworkAlgo function.

Done in 97f4044

Same comment as for Arnold again.

johnhaddon · 2026-06-15T13:29:29Z

-			# various parameters are actually intended to do.
-			description = description.replace( "TODO: clarify semantics", "" )
-		return description
+		return property.GetDocumentation()


The "clarify semantics" stuff has gone from USD, and GetDocumentation() calls GetMetadata( "documentation" ), so this all makes sense. But it doesn't seem to match the commit message.

I can update the commit message after I squash the other commits down. I think something like USDShaderUI : Add description for MeshLight parameters. GetDocumentation() checks for userDocBrief before falling back to documentation, so it picks up some additional metadata that GetMetadata( "documentation" ) misses out on.

Thanks for the explanation - I had mistakenly been looking at UsdObject::GetDocumentation() (which doesn't use userDocBrief rather than UsdPrimDefinition::Property::GetDocumentation(), which does.

These match our current descriptions for Arnold light plugs.

ericmehl · 2026-06-17T21:50:11Z

This is in good shape now for a look at the existing fixups. I added one more commit for Arnold : github.com//pull/6970/commits/6afc7e75cfc387638757eeab12165ed7635d0885. That corrects the behavior to multiply the light color with the surface glow response, creating a new multiply shader when needed.

We decided that if a mesh light has an input to color, we leave it alone as the user is probably intending for that shader to be the final light result, not multiplied by any surface glow that may exist.

I'll take care of the Cycles and 3Delight conversions next.

johnhaddon · 2026-06-18T14:02:11Z

We decided that if a mesh light has an input to color, we leave it alone as the user is probably intending for that shader to be the final light result, not multiplied by any surface glow that may exist.

Sorry, I should have read the UsdLux docs when we were having this discussion. They seem to be fairly clear that we should multiply the two together in this case :

the base color seen by light rays (which is then modulated by all of the other LightAPI controls) is the multiplication of the color feeding the emission/glow input of the Material (i.e. its surface or volume shader) with the scalar or pattern input to inputs:color

Might be worth checking via usdview though, to see what the behaviour is in practice.

ericmehl force-pushed the usdMeshLight branch from 0a718f7 to 434ef85 Compare June 11, 2026 19:16

johnhaddon reviewed Jun 15, 2026

View reviewed changes

ericmehl force-pushed the usdMeshLight branch from 434ef85 to 0f4ed3f Compare June 15, 2026 21:53

ericmehl added 15 commits June 17, 2026 16:53

USDMeshLight : Add node to make light from mesh

bf7db4e

Arnold : Add support for USD mesh lights

3f27a51

USDMeshLight : Add renderer icons to parameters

ebed736

RenderMan : Add support for USD mesh lights

db04548

StandardLightVisualiser : Textured mesh lights

454cc4f

RenderMan : USD mesh light visibility attributes

18f25a8

Arnold : USD mesh light visibility attributes

6d60ebe

USDShaderUI : Remove outdated description tweak

9dc7b3b

USDMeshLightUI : Add Arnold plug descriptions

d6a88ba

These match our current descriptions for Arnold light plugs.

fixup! USDMeshLight : Add node to make light from mesh

a73c11f

fixup! USDMeshLight : Add node to make light from mesh

bff4c97

fixup! Arnold : Add support for USD mesh lights

8648a43

fixup! Arnold : Add support for USD mesh lights

ec5787c

fixup! RenderMan : Add support for USD mesh lights

97f4044

fixup! Arnold : Add support for USD mesh lights

6afc7e7

ericmehl force-pushed the usdMeshLight branch from 5f7c795 to 6afc7e7 Compare June 17, 2026 21:01

Conversation

ericmehl commented Jun 11, 2026

Checklist

Uh oh!

ericmehl commented Jun 11, 2026

Uh oh!

johnhaddon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericmehl Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnhaddon Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericmehl commented Jun 17, 2026

Uh oh!

johnhaddon commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ericmehl Jun 17, 2026 •

edited

Loading

johnhaddon Jun 18, 2026 •

edited

Loading