WebGPURenderer: Preserve material side during async compilation

Author: RenaudRohlinger

examples/screenshots/webgpu_loader_materialx.jpg

@@ -116,6 +116,17 @@ class NodeBuilder {
 		 */
 		this.material = ( object && object.material ) || null;
 
+		/**
+		 * The side of the material the shader is built for. Nodes must use this property
+		 * instead of `material.side` since the renderer temporarily overwrites the material's
+		 * side when it renders double-sided transparent materials in two passes. The value is
+		 * derived from the render object so it stays valid when the shader is built at a later
+		 * point (e.g. in `compileAsync()`).
+		 *
+		 * @type {?number}
+		 */
+		this.materialSide = this.material !== null ? this.material.side : null;
+
 		/**
 		 * The geometry of the 3D object.
 		 *

src/nodes/core/NodeBuilder.js

@@ -41,9 +41,7 @@ class FrontFacingNode extends Node {
 
 		//
 
-		const { material } = builder;
-
-		if ( material.side === BackSide ) {
+		if ( builder.materialSide === BackSide ) {
 
 			return 'false';
 
@@ -88,15 +86,13 @@ export const faceDirection = /*@__PURE__*/ float( frontFacing ).mul( 2.0 ).sub(
  * @param {Node<vec3>} vector - The vector to process.
  * @returns {Node<vec3>} The processed vector.
  */
-export const negateOnBackSide = /*@__PURE__*/ Fn( ( [ vector ], { material } ) => {
-
-	const side = material.side;
+export const negateOnBackSide = /*@__PURE__*/ Fn( ( [ vector ], { materialSide } ) => {
 
-	if ( side === BackSide ) {
+	if ( materialSide === BackSide ) {
 
 		vector = vector.mul( - 1.0 );
 
-	} else if ( side === DoubleSide ) {
+	} else if ( materialSide === DoubleSide ) {
 
 		vector = vector.mul( faceDirection );
 

src/nodes/display/FrontFacingNode.js

@@ -70,9 +70,9 @@ const applyIorToRoughness = /*@__PURE__*/ Fn( ( [ roughness, ior ] ) => {
 const viewportBackSideTexture = /*@__PURE__*/ viewportMipTexture();
 const viewportFrontSideTexture = /*@__PURE__*/ viewportOpaqueMipTexture();
 
-const getTransmissionSample = /*@__PURE__*/ Fn( ( [ fragCoord, roughness, ior ], { material } ) => {
+const getTransmissionSample = /*@__PURE__*/ Fn( ( [ fragCoord, roughness, ior ], { materialSide } ) => {
 
-	const vTexture = material.side === BackSide ? viewportBackSideTexture : viewportFrontSideTexture;
+	const vTexture = materialSide === BackSide ? viewportBackSideTexture : viewportFrontSideTexture;
 
 	const transmissionSample = vTexture.sample( fragCoord );
 	//const transmissionSample = viewportMipTexture( fragCoord );

src/nodes/functions/PhysicalLightingModel.js

@@ -119,6 +119,19 @@ class RenderObject {
 		 */
 		this.material = material;
 
+		/**
+		 * The side of the material this render object is rendered with.
+		 *
+		 * The renderer temporarily overwrites `material.side` when double-sided transparent
+		 * materials are rendered in two passes. Since render objects are unique per pass
+		 * (see the `backSide` pass ID), the side can be stored per render object which keeps
+		 * it valid even when the material has been restored in the meantime (e.g. when the
+		 * shader is built at a later point in `compileAsync()`).
+		 *
+		 * @type {number}
+		 */
+		this.materialSide = material.side;
+
 		/**
 		 * The scene the 3D object belongs to.
 		 *

src/renderers/common/RenderObject.js

@@ -113,6 +113,7 @@ class RenderObjects {
 			// update references
 
 			renderObject.camera = camera;
+			renderObject.materialSide = material.side;
 
 			//
 

src/renderers/common/RenderObjects.js

@@ -653,13 +653,13 @@ class Renderer {
 		this._initPromise = null;
 
 		/**
-		 * An array of compilation promises which are used in `compileAsync()`.
+		 * An array of render objects which are precompiled in `compileAsync()`.
 		 *
 		 * @private
-		 * @type {?Array<Promise>}
+		 * @type {?Array<RenderObject>}
 		 * @default null
 		 */
-		this._compilationPromises = null;
+		this._compilationRenderObjects = null;
 
 		/**
 		 * Whether the renderer is currently precompiling a render object in
@@ -921,7 +921,7 @@ class Renderer {
 		const previousRenderContext = this._currentRenderContext;
 		const previousRenderObjectFunction = this._currentRenderObjectFunction;
 		const previousHandleObjectFunction = this._handleObjectFunction;
-		const previousCompilationPromises = this._compilationPromises;
+		const previousCompilationRenderObjects = this._compilationRenderObjects;
 
 		//
 
@@ -939,14 +939,14 @@ class Renderer {
 		const renderContext = this._renderContexts.get( renderTarget, this._mrt );
 		const activeMipmapLevel = this._activeMipmapLevel;
 
-		const compilationPromises = [];
+		const compilationRenderObjects = [];
 
 		this._currentRenderContext = renderContext;
 		this._currentRenderObjectFunction = this.renderObject;
 
 		this._handleObjectFunction = this._createObjectPipeline;
 
-		this._compilationPromises = compilationPromises;
+		this._compilationRenderObjects = compilationRenderObjects;
 
 		nodeFrame.renderId ++;
 
@@ -1039,7 +1039,7 @@ class Renderer {
 
 		}
 
-		// process render lists - _createObjectPipeline will push async promises to _compilationPromises
+		// process render lists - _createObjectPipeline will push render objects to _compilationRenderObjects
 
 		const opaqueObjects = renderList.opaque;
 		const transparentObjects = renderList.transparent;
@@ -1056,19 +1056,15 @@ class Renderer {
 		this._currentRenderContext = previousRenderContext;
 		this._currentRenderObjectFunction = previousRenderObjectFunction;
 		this._handleObjectFunction = previousHandleObjectFunction;
-		this._compilationPromises = previousCompilationPromises;
+		this._compilationRenderObjects = previousCompilationRenderObjects;
 
 		// Process compilation work items sequentially to avoid freezing
 		// Yields between objects to keep animation smooth
 
-		const total = compilationPromises.length;
+		const total = compilationRenderObjects.length;
 		let loaded = 0;
 
-		for ( const item of compilationPromises ) {
-
-			const renderObject = this._objects.get( item.object, item.material, item.scene, item.camera, item.lightsNode, item.renderContext, item.clippingContext, item.passId );
-			renderObject.drawRange = item.object.geometry.drawRange;
-			renderObject.group = item.group;
+		for ( const renderObject of compilationRenderObjects ) {
 
 			// Use async node building to yield to main thread
 			await this._nodes.getForRenderAsync( renderObject );
@@ -1083,6 +1079,7 @@ class Renderer {
 			// Wait for pipeline creation
 			const pipelinePromises = [];
 			this._pipelines.getForRender( renderObject, pipelinePromises );
+
 			if ( pipelinePromises.length > 0 ) {
 
 				await Promise.all( pipelinePromises );
@@ -3906,31 +3903,24 @@ class Renderer {
 	 */
 	_createObjectPipeline( object, material, scene, camera, lightsNode, group, clippingContext, passId ) {
 
-		// If in async compilation mode, queue the work for sequential execution
-		if ( this._compilationPromises !== null ) {
+		// the render object must be requested during the traversal since the renderer temporarily
+		// overwrites `material.side` for the back side pass. `RenderObject.materialSide` preserves
+		// that value for the deferred compilation in `compileAsync()`.
 
-			// Store work items instead of promises - will be processed sequentially
-			this._compilationPromises.push( {
-				object,
-				material,
-				scene,
-				camera,
-				lightsNode,
-				group,
-				clippingContext,
-				passId,
-				renderContext: this._currentRenderContext
-			} );
+		const renderObject = this._objects.get( object, material, scene, camera, lightsNode, this._currentRenderContext, clippingContext, passId );
+		renderObject.drawRange = object.geometry.drawRange;
+		renderObject.group = group;
+
+		// if in async compilation mode, queue the render object for sequential execution
+
+		if ( this._compilationRenderObjects !== null ) {
+
+			this._compilationRenderObjects.push( renderObject );
 
 			return;
 
 		}
 
-		// Sync path
-		const renderObject = this._objects.get( object, material, scene, camera, lightsNode, this._currentRenderContext, clippingContext, passId );
-		renderObject.drawRange = object.geometry.drawRange;
-		renderObject.group = group;
-
 		//
 
 		this._nodes.updateBefore( renderObject );
@@ -3940,7 +3930,7 @@ class Renderer {
 		this._nodes.updateForRender( renderObject );
 		this._bindings.updateForRender( renderObject );
 
-		this._pipelines.getForRender( renderObject, this._compilationPromises );
+		this._pipelines.getForRender( renderObject );
 
 		this._nodes.updateAfter( renderObject );
 

src/renderers/common/Renderer.js

@@ -171,6 +171,7 @@ class NodeManager extends DataMap {
 
 		nodeBuilder.scene = renderObject.scene;
 		nodeBuilder.material = material;
+		nodeBuilder.materialSide = renderObject.materialSide;
 		nodeBuilder.camera = renderObject.camera;
 		nodeBuilder.context.material = material;
 		nodeBuilder.lightsNode = renderObject.lightsNode;

src/renderers/common/nodes/NodeManager.js

@@ -2087,7 +2087,7 @@ class WebGPUBackend extends Backend {
 
 		const data = this.get( renderObject );
 
-		const { object, material } = renderObject;
+		const { object, material, materialSide } = renderObject;
 
 		const utils = this.utils;
 
@@ -2108,7 +2108,7 @@ class WebGPUBackend extends Backend {
 			data.stencilWrite !== material.stencilWrite || data.stencilFunc !== material.stencilFunc ||
 			data.stencilFail !== material.stencilFail || data.stencilZFail !== material.stencilZFail || data.stencilZPass !== material.stencilZPass ||
 			data.stencilFuncMask !== material.stencilFuncMask || data.stencilWriteMask !== material.stencilWriteMask ||
-			data.side !== material.side || data.alphaToCoverage !== material.alphaToCoverage ||
+			data.side !== materialSide || data.alphaToCoverage !== material.alphaToCoverage ||
 			data.sampleCount !== sampleCount || data.colorSpace !== colorSpace ||
 			data.colorFormat !== colorFormat || data.depthStencilFormat !== depthStencilFormat ||
 			data.primitiveTopology !== primitiveTopology ||
@@ -2125,7 +2125,7 @@ class WebGPUBackend extends Backend {
 			data.stencilWrite = material.stencilWrite; data.stencilFunc = material.stencilFunc;
 			data.stencilFail = material.stencilFail; data.stencilZFail = material.stencilZFail; data.stencilZPass = material.stencilZPass;
 			data.stencilFuncMask = material.stencilFuncMask; data.stencilWriteMask = material.stencilWriteMask;
-			data.side = material.side; data.alphaToCoverage = material.alphaToCoverage;
+			data.side = materialSide; data.alphaToCoverage = material.alphaToCoverage;
 			data.sampleCount = sampleCount;
 			data.colorSpace = colorSpace;
 			data.colorFormat = colorFormat;
@@ -2150,7 +2150,7 @@ class WebGPUBackend extends Backend {
 	 */
 	getRenderCacheKey( renderObject ) {
 
-		const { object, material } = renderObject;
+		const { object, material, materialSide } = renderObject;
 
 		const utils = this.utils;
 		const renderContext = renderObject.context;
@@ -2169,7 +2169,7 @@ class WebGPUBackend extends Backend {
 			material.stencilWrite, material.stencilFunc,
 			material.stencilFail, material.stencilZFail, material.stencilZPass,
 			material.stencilFuncMask, material.stencilWriteMask,
-			material.side,
+			materialSide,
 			frontFaceCW,
 			utils.getSampleCountRenderContext( renderContext ),
 			utils.getCurrentColorSpace( renderContext ), utils.getCurrentColorFormat( renderContext ), utils.getCurrentDepthStencilFormat( renderContext ),

src/renderers/webgpu/WebGPUBackend.js

@@ -71,7 +71,7 @@ class WebGPUPipelineUtils {
 	 */
 	createRenderPipeline( renderObject, promises ) {
 
-		const { object, material, geometry, pipeline } = renderObject;
+		const { material, pipeline } = renderObject;
 		const { vertexProgram, fragmentProgram } = pipeline;
 
 		const backend = this.backend;
@@ -193,7 +193,7 @@ class WebGPUPipelineUtils {
 		const vertexModule = backend.get( vertexProgram ).module;
 		const fragmentModule = backend.get( fragmentProgram ).module;
 
-		const primitiveState = this._getPrimitiveState( object, geometry, material );
+		const primitiveState = this._getPrimitiveState( renderObject );
 		const depthCompare = this._getDepthCompare( material );
 		const depthStencilFormat = utils.getCurrentDepthStencilFormat( renderObject.context );
 
@@ -888,12 +888,12 @@ class WebGPUPipelineUtils {
 	 * for the pipeline creation.
 	 *
 	 * @private
-	 * @param {Object3D} object - The 3D object.
-	 * @param {BufferGeometry} geometry - The geometry.
-	 * @param {Material} material - The material.
+	 * @param {RenderObject} renderObject - The render object.
 	 * @return {Object} The primitive state.
 	 */
-	_getPrimitiveState( object, geometry, material ) {
+	_getPrimitiveState( renderObject ) {
+
+		const { object, geometry, material, materialSide } = renderObject;
 
 		const descriptor = {};
 		const utils = this.backend.utils;
@@ -910,15 +910,15 @@ class WebGPUPipelineUtils {
 
 		//
 
-		let flipSided = ( material.side === BackSide );
+		let flipSided = ( materialSide === BackSide );
 
 		if ( object.isMesh && object.matrixWorld.determinantAffine() < 0 ) flipSided = ! flipSided;
 
 		descriptor.frontFace = ( flipSided === true ) ? GPUFrontFace.CW : GPUFrontFace.CCW;
 
 		//
 
-		descriptor.cullMode = ( material.side === DoubleSide ) ? GPUCullMode.None : GPUCullMode.Back;
+		descriptor.cullMode = ( materialSide === DoubleSide ) ? GPUCullMode.None : GPUCullMode.Back;
 
 		return descriptor;