TSL: Introduce builtinAOContext and Enhance AO Post-Processing Example

[querielo]

Overview

This PR introduces a new TSL node materialTransparent builtinAOContext and demonstrates its usage by improving the ambient occlusion post-processing example to properly handle transparent materials.

The PR is based on this PR: #32276 (Cc. @sunag)

Dev:

output.mp4

PR:

output1.mp4

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	350.29 83.05	350.29 83.05	+0 B +0 B
WebGPU	613.38 170.32	613.5 170.38	+121 B +65 B
WebGPU Nodes	611.98 170.04	612.1 170.1	+121 B +61 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	482.23 117.82	482.23 117.82	+0 B +0 B
WebGPU	684.5 186.13	684.59 186.16	+96 B +33 B
WebGPU Nodes	634.32 173.31	634.42 173.35	+96 B +41 B

[Copilot]

Pull request overview

This PR introduces a new TSL node materialTransparent that exposes a material's transparent property to shaders, and demonstrates its usage in the ambient occlusion post-processing example to properly handle transparent materials by disabling AO on them.

• Added materialTransparent TSL node to access material transparency state in shaders
• Enhanced the AO post-processing example to conditionally apply AO based on material transparency
• Added GUI controls to adjust transparent mesh opacity for better demonstration

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/nodes/accessors/MaterialProperties.js	Adds the new materialTransparent uniform node that tracks the material's transparent property
src/Three.TSL.js	Exports the new materialTransparent node in the TSL namespace (correctly alphabetized)
examples/webgpu_postprocessing_ao.html	Demonstrates materialTransparent usage by conditionally applying AO (value of 1 for transparent materials, sampled AO for opaque), adds transparent mesh to scene with opacity controls

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

[sunag]

Instead of using a uniform, I would like to modify context.ao to context.getAO, with the signature getAO( node, builder ).

three.js/src/materials/nodes/NodeMaterial.js

Lines 1063 to 1077 in 77ebf27

	let aoNode = builder.context.ao || null;
	if ( this.aoNode !== null || builder.material.aoMap ) {
	const mtlAO = this.aoNode !== null ? this.aoNode : materialAO;
	aoNode = aoNode !== null ? aoNode.mul( mtlAO ) : mtlAO;
	}
	if ( aoNode !== null ) {
	materialLightsNode.push( new AONode( aoNode ) );
	}

Instead of context( { ao: ... } ) I think we can use context( { getAO: ... } )
I think it would look like this.

const aoSample = aoPassOutput.sample( screenUV ).r;

scenePass.contextNode = context( {

	getAO: ( node, { material } ) => {

		if ( material.transparent === true ) return node;

		return node !== null ? node.mul( aoSample ) : aoSample ;

	}

} );

---

I think to finish up we can create a internal(core) function to include the code above to use like:

scenePass.contextNode = bultinAOContext( aoPassOutput.sample( screenUV ).r );

The general idea is to eliminate the need for an additional uniform and, with the getAO function, provide more control over manipulation.

@Mugen87 I think we can do the same in the SSS example.

const aoSample = aoPassOutput.sample( screenUV ).r,;
scenePass.contextNode = bultinShadowContext( aoSample, light );

[Mugen87]

Sounds good! Definitely a step in the right direction.

[querielo]

@sunag I’ve just updated the PR. I’m still not completely confident I understand all of the context, though.

[Mugen87]

I like how these new functions simplify the setup on app level. Even NodeMaterial benefits from builtinAOContext() 🎉 .