@gnsx/three 0.186.4 → 0.186.6

package/examples/jsm/inspector/tabs/Settings.js

@@ -137,12 +137,20 @@ class Settings extends Parameters {
 		// WITH_GENESYS
 		// Values match Renderer.debug.view. Not stored with inspector settings.
 		const debugViewState = { view: 'none' };
+		const bufferState = { buffer: 'baseColor' };
 
 		this._debugViewState = debugViewState;
+		this._bufferState = bufferState;
 		this._debugViewControl = modesGroup.add( debugViewState, 'view', {
 			'Shaded': 'none',
 			'Shader Complexity': 'shaderComplexity',
-			'Lighting Complexity': 'lightingComplexity'
+			'Lighting Complexity': 'lightingComplexity',
+			'Quad Overdraw': 'quadOverdraw',
+			'Shader Complexity & Quads': 'shaderComplexityAndQuads',
+			'Buffer Visualization': 'bufferVisualization',
+			'Lighting Only': 'lightingOnly',
+			'Detail Lighting': 'detailLighting',
+			'Draw Call': 'drawCall'
 		} ).name( 'Debug View' ).onChange( ( view ) => {
 
 			const renderer = this.inspector.getRenderer();
@@ -150,9 +158,30 @@ class Settings extends Parameters {
 			if ( renderer === null || renderer.debug === undefined ) return;
 
 			renderer.debug.view = view;
+			this._syncBufferRow( view );
 			window.dispatchEvent( new Event( 'genesys-debug-view' ) );
 
-		} ).info( 'Shaded color, a shader-cost heatmap, or a direct-light count. Overdraw draws on top when both are enabled.' );
+		} ).info( 'Shaded color, a cost heatmap, per-pixel overdraw, shader cost times overdraw, one material channel, lighting on a flat gray surface, or one lit color per draw. The Overdraw toggle above draws on top when both are enabled.' );
+
+		this._bufferControl = modesGroup.add( bufferState, 'buffer', {
+			'Base Color': 'baseColor',
+			'World Normal': 'worldNormal',
+			'Roughness': 'roughness',
+			'Metallic': 'metallic',
+			'Ambient Occlusion': 'ambientOcclusion',
+			'Emissive': 'emissive'
+		} ).name( 'Buffer' ).onChange( ( buffer ) => {
+
+			const renderer = this.inspector.getRenderer();
+
+			if ( renderer === null || renderer.debug === undefined ) return;
+
+			renderer.debug.buffer = buffer;
+			window.dispatchEvent( new Event( 'genesys-debug-view' ) );
+
+		} ).info( 'Channel drawn by Buffer Visualization. Base color, world normal, roughness, metallic, ambient occlusion, or emissive.' );
+
+		this._bufferControl.hide();
 		// !WITH_GENESYS
 
 	}
@@ -163,7 +192,7 @@ class Settings extends Parameters {
 		const renderer = this.inspector.getRenderer();
 		const view = renderer !== null && renderer.debug !== undefined ? renderer.debug.view : null;
 
-		if ( view === 'none' || view === 'shaderComplexity' || view === 'lightingComplexity' ) {
+		if ( view === 'none' || view === 'shaderComplexity' || view === 'lightingComplexity' || view === 'quadOverdraw' || view === 'shaderComplexityAndQuads' || view === 'bufferVisualization' || view === 'lightingOnly' || view === 'detailLighting' || view === 'drawCall' ) {
 
 			if ( this._debugViewState.view !== view ) {
 
@@ -171,6 +200,17 @@ class Settings extends Parameters {
 
 			}
 
+			this._syncBufferRow( view );
+
+		}
+
+		const buffer = renderer !== null && renderer.debug !== undefined ? renderer.debug.buffer : null;
+		const buffers = [ 'baseColor', 'worldNormal', 'roughness', 'metallic', 'ambientOcclusion', 'emissive' ];
+
+		if ( buffers.includes( buffer ) && this._bufferState.buffer !== buffer ) {
+
+			this._bufferControl.setValue( buffer );
+
 		}
 		// !WITH_GENESYS
 
@@ -257,6 +297,27 @@ Shares the same state across any page within the current origin.` );
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shows the buffer channel row only while buffer visualization is the debug view.
+	 *
+	 * @param {string} view - `renderer.debug.view`.
+	 */
+	_syncBufferRow( view ) {
+
+		if ( view === 'bufferVisualization' ) {
+
+			this._bufferControl.show();
+
+		} else {
+
+			this._bufferControl.hide();
+
+		}
+
+	}
+	// !WITH_GENESYS
+
 	async setActiveExtension( name, value ) {
 
 		const extension = this.extensions[ name ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnsx/three",
-  "version": "0.186.4",
+  "version": "0.186.6",
   "description": "JavaScript 3D library",
   "type": "module",
   "main": "./build/three.cjs",

package/src/materials/nodes/MeshBasicNodeMaterial.js

@@ -118,6 +118,19 @@ class MeshBasicNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for {@link BasicLightingModel}.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 80;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/MeshLambertNodeMaterial.js

@@ -66,6 +66,19 @@ class MeshLambertNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for Lambert. Specular is forced off.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 140;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/MeshMatcapNodeMaterial.js

@@ -46,6 +46,19 @@ class MeshMatcapNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for matcap UV shading.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 50;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the matcap specific node variables.
 	 *

package/src/materials/nodes/MeshPhongNodeMaterial.js

@@ -95,6 +95,19 @@ class MeshPhongNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for Blinn-Phong.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 200;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/MeshPhysicalNodeMaterial.js

@@ -383,6 +383,31 @@ class MeshPhysicalNodeMaterial extends MeshStandardNodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * GGX base from {@link MeshStandardNodeMaterial}, plus each enabled physical feature.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		let cost = super.getShaderComplexity();
+
+		if ( this.useClearcoat === true ) cost += 30;
+
+		if ( this.useSheen === true ) cost += 30;
+
+		if ( this.useIridescence === true ) cost += 30;
+
+		if ( this.useAnisotropy === true ) cost += 30;
+
+		if ( this.useTransmission === true ) cost += 60;
+
+		return cost;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/MeshSSSNodeMaterial.js

@@ -146,6 +146,21 @@ class MeshSSSNodeMaterial extends MeshPhysicalNodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Physical complexity, plus the subsurface term when it is evaluated.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		const cost = super.getShaderComplexity();
+
+		return this.useSSS === true ? cost + 40 : cost;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/MeshStandardNodeMaterial.js

@@ -117,6 +117,19 @@ class MeshStandardNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for the Cook-Torrance GGX model.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 240;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/MeshToonNodeMaterial.js

@@ -50,6 +50,19 @@ class MeshToonNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for toon banding.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 170;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/NodeMaterial.js

@@ -26,7 +26,30 @@ import { vertexColor } from '../../nodes/accessors/VertexColorNode.js';
 import { premultiplyAlpha } from '../../nodes/display/PremultiplyAlphaFunctions.js';
 import { subBuild } from '../../nodes/core/SubBuildNode.js';
 // WITH_GENESYS
-import { DEBUG_VIEW_LIGHTING_COMPLEXITY, DEBUG_VIEW_SHADER_COMPLEXITY, getShaderComplexityBase, shaderComplexityOutput } from '../../nodes/display/ComplexityDebug.js';
+import { DEBUG_VIEW_LIGHTING_COMPLEXITY, DEBUG_VIEW_SHADER_COMPLEXITY, DEBUG_VIEW_SHADER_COMPLEXITY_AND_QUADS, debugDrawAccumulates, quadOverdrawOutput, shaderComplexityAndQuadsOutput, shaderComplexityOutput } from '../../nodes/display/ComplexityDebug.js';
+import { mrt } from '../../nodes/core/MRTNode.js';
+import { DEBUG_VIEW_BUFFER, assignBufferDefaults, bufferVisualizationOutput } from '../../nodes/display/BufferDebug.js';
+import { DEBUG_VIEW_DETAIL_LIGHTING, DEBUG_VIEW_LIGHTING_ONLY, applyLightingDebug, lightingOnlyNormal } from '../../nodes/display/LightingDebug.js';
+import { DEBUG_VIEW_DRAW_CALL, applyDrawCallDebug } from '../../nodes/display/DrawCallDebug.js';
+
+/**
+ * Replaces the color a material writes with a debug output. With MRT, only the `output`
+ * attachment is replaced so the other attachments keep their members. Converting the
+ * whole MRT struct to a color leaves WGSL with an empty output struct.
+ *
+ * @param {Node} resultNode - The material's fragment result, possibly an MRT node.
+ * @param {function(Node): Node} createOutput - Builds the debug color from the shaded color.
+ * @return {Node} The fragment result with the debug color in place.
+ */
+function replaceColorOutput( resultNode, createOutput ) {
+
+	if ( resultNode.isMRTNode !== true ) return createOutput( resultNode );
+
+	if ( resultNode.has( 'output' ) !== true ) return resultNode;
+
+	return resultNode.merge( mrt( { output: createOutput( resultNode.get( 'output' ) ) } ) );
+
+}
 // !WITH_GENESYS
 
 /**
@@ -527,10 +550,33 @@ class NodeMaterial extends Material {
 
 		if ( this.fragmentNode === null ) {
 
+			// WITH_GENESYS
+			// Fallback for materials that never write the channel. Lit materials overwrite these.
+			if ( renderer.debug.view === DEBUG_VIEW_BUFFER && this.isShadowPassMaterial !== true ) {
+
+				assignBufferDefaults( renderer.debug.buffer );
+
+			}
+			// !WITH_GENESYS
+
 			this.setupDiffuseColor( builder );
 			this.setupAmbientOcclusion( builder );
 			this.setupVariants( builder );
 
+			// WITH_GENESYS
+			// After the material writes its channels, so roughness and normals already exist
+			// for detail lighting and can be replaced for lighting only.
+			if ( ( renderer.debug.view === DEBUG_VIEW_LIGHTING_ONLY || renderer.debug.view === DEBUG_VIEW_DETAIL_LIGHTING ) && this.isShadowPassMaterial !== true ) {
+
+				applyLightingDebug( builder, this, renderer.debug.view );
+
+			} else if ( renderer.debug.view === DEBUG_VIEW_DRAW_CALL && this.isShadowPassMaterial !== true ) {
+
+				applyDrawCallDebug( builder, this );
+
+			}
+			// !WITH_GENESYS
+
 			const outgoingLightNode = this.setupLighting( builder );
 
 			if ( clippingNode !== null ) builder.stack.addToStack( clippingNode );
@@ -601,12 +647,32 @@ class NodeMaterial extends Material {
 		}
 
 		// WITH_GENESYS
-		// The screen output pass colorizes the accumulated ratio. Wrapping that pass
-		// would replace the heatmap with this material's own constant cost.
-		if ( renderer.debug.view === DEBUG_VIEW_SHADER_COMPLEXITY && this.isShadowPassMaterial !== true && renderer.isOutputTarget !== true ) {
+		// The screen output pass colorizes the accumulated ratio. Wrapping that pass, or a
+		// post-processing quad that copies the scene target, would replace the heatmap with
+		// that quad's own constant cost.
+		if ( debugDrawAccumulates( renderer, this, builder.object ) ) {
+
+			if ( renderer.debug.view === DEBUG_VIEW_SHADER_COMPLEXITY ) {
+
+				builder.shaderComplexityBase = this.getShaderComplexity();
+				resultNode = replaceColorOutput( resultNode, shaderComplexityOutput );
 
-			builder.shaderComplexityBase = getShaderComplexityBase( this );
-			resultNode = shaderComplexityOutput( resultNode );
+			} else if ( renderer.debug.view === DEBUG_VIEW_SHADER_COMPLEXITY_AND_QUADS ) {
+
+				builder.shaderComplexityBase = this.getShaderComplexity();
+				resultNode = replaceColorOutput( resultNode, shaderComplexityAndQuadsOutput );
+
+			} else {
+
+				resultNode = replaceColorOutput( resultNode, quadOverdrawOutput );
+
+			}
+
+		} else if ( renderer.debug.view === DEBUG_VIEW_BUFFER && this.isShadowPassMaterial !== true && this.fragmentNode === null ) {
+
+			// The fullscreen output pass sets fragmentNode. Scene materials do not, including
+			// when the scene is drawn straight to the canvas.
+			resultNode = replaceColorOutput( resultNode, () => bufferVisualizationOutput( renderer.debug.buffer ) );
 
 		}
 		// !WITH_GENESYS
@@ -621,6 +687,21 @@ class NodeMaterial extends Material {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Static shader-complexity proxy for this material's lighting model.
+	 * Fragment texture samples are counted later, while the shader is generated.
+	 * Derived materials override this instead of registering a type flag.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return this.lights === true ? 40 : 20;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the clipping node.
 	 *
@@ -945,9 +1026,18 @@ class NodeMaterial extends Material {
 	/**
 	 * Setups the normal node from the material.
 	 *
+	 * @param {NodeBuilder} builder - The current node builder.
 	 * @return {Node<vec3>} The normal node.
 	 */
-	setupNormal() {
+	setupNormal( builder ) {
+
+		// WITH_GENESYS
+		if ( ( builder.renderer.debug.view === DEBUG_VIEW_LIGHTING_ONLY || builder.renderer.debug.view === DEBUG_VIEW_DRAW_CALL ) && this.isShadowPassMaterial !== true && this.fragmentNode === null ) {
+
+			return lightingOnlyNormal();
+
+		}
+		// !WITH_GENESYS
 
 		return this.normalNode ? vec3( this.normalNode ) : materialNormal;
 
@@ -1144,6 +1234,16 @@ class NodeMaterial extends Material {
 
 		if ( ( emissiveNode && emissiveNode.isNode === true ) || ( material.emissive && material.emissive.isColor === true ) ) {
 
+			// WITH_GENESYS
+			// Lighting only and draw call substitute a plain lit material, so emissive is dropped.
+			// Detail lighting keeps it.
+			if ( ( builder.renderer.debug.view === DEBUG_VIEW_LIGHTING_ONLY || builder.renderer.debug.view === DEBUG_VIEW_DRAW_CALL ) && this.isShadowPassMaterial !== true ) {
+
+				return outgoingLightNode;
+
+			}
+			// !WITH_GENESYS
+
 			emissive.assign( vec3( emissiveNode ? emissiveNode : materialEmissive ) );
 
 			outgoingLightNode = outgoingLightNode.add( emissive );

package/src/materials/nodes/ShadowNodeMaterial.js

@@ -60,6 +60,19 @@ class ShadowNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for the shadow mask.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 110;
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Setups the lighting model.
 	 *

package/src/materials/nodes/VolumeNodeMaterial.js

@@ -70,6 +70,19 @@ class VolumeNodeMaterial extends NodeMaterial {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Shader-complexity proxy for volumetric ray integration.
+	 *
+	 * @return {number} The base cost, excluding texture samples.
+	 */
+	getShaderComplexity() {
+
+		return 280;
+
+	}
+	// !WITH_GENESYS
+
 	setupLightingModel() {
 
 		return new VolumetricLightingModel();

package/src/nodes/display/BufferDebug.js

@@ -0,0 +1,143 @@
+// WITH_GENESYS
+// Buffer visualization. Shows one material channel in place of the shaded color.
+// !WITH_GENESYS
+
+import { diffuseColor, ambientOcclusion, emissive, metalness, roughness } from '../core/PropertyNode.js';
+import { normalWorld } from '../accessors/Normal.js';
+import { float, vec3, vec4 } from '../tsl/TSLCore.js';
+
+/**
+ * Buffer visualization. The visible surface wins, and one material channel replaces the shaded color.
+ *
+ * @type {string}
+ */
+export const DEBUG_VIEW_BUFFER = 'bufferVisualization';
+
+/**
+ * Albedo before lighting, including maps and vertex colors.
+ *
+ * @type {string}
+ */
+export const BUFFER_BASE_COLOR = 'baseColor';
+
+/**
+ * Shading normal in world space, packed to RGB with `n * 0.5 + 0.5`.
+ *
+ * @type {string}
+ */
+export const BUFFER_WORLD_NORMAL = 'worldNormal';
+
+/**
+ * Scalar roughness used by the lighting model. Black is smooth.
+ *
+ * @type {string}
+ */
+export const BUFFER_ROUGHNESS = 'roughness';
+
+/**
+ * Scalar metalness. White is metal. Unreal calls this buffer Metallic.
+ *
+ * @type {string}
+ */
+export const BUFFER_METALLIC = 'metallic';
+
+/**
+ * Material ambient occlusion. White means no occlusion map.
+ *
+ * @type {string}
+ */
+export const BUFFER_AMBIENT_OCCLUSION = 'ambientOcclusion';
+
+/**
+ * Emissive color before it is added to the lit result.
+ *
+ * @type {string}
+ */
+export const BUFFER_EMISSIVE = 'emissive';
+
+/**
+ * Channel drawn when buffer visualization is first enabled.
+ *
+ * @type {string}
+ */
+export const DEFAULT_BUFFER = BUFFER_BASE_COLOR;
+
+/**
+ * Writes a defined value for channels a material may never assign.
+ * Standard and physical materials overwrite roughness and metalness in `setupVariants`,
+ * and emissive is overwritten when the material has one.
+ *
+ * @param {string} buffer - `renderer.debug.buffer`.
+ */
+export function assignBufferDefaults( buffer ) {
+
+	if ( buffer === BUFFER_ROUGHNESS ) {
+
+		roughness.assign( float( 0 ) );
+
+	} else if ( buffer === BUFFER_METALLIC ) {
+
+		metalness.assign( float( 0 ) );
+
+	} else if ( buffer === BUFFER_EMISSIVE ) {
+
+		emissive.assign( vec3( 0 ) );
+
+	}
+
+}
+
+/**
+ * The color for one buffer channel. Scalar channels are copied into RGB.
+ *
+ * @param {string} buffer - `renderer.debug.buffer`.
+ * @return {Node<vec3>} The channel color.
+ */
+export function bufferVisualizationColor( buffer ) {
+
+	if ( buffer === BUFFER_WORLD_NORMAL ) {
+
+		return normalWorld.mul( 0.5 ).add( 0.5 );
+
+	}
+
+	if ( buffer === BUFFER_ROUGHNESS ) {
+
+		return vec3( roughness );
+
+	}
+
+	if ( buffer === BUFFER_METALLIC ) {
+
+		return vec3( metalness );
+
+	}
+
+	if ( buffer === BUFFER_AMBIENT_OCCLUSION ) {
+
+		return vec3( ambientOcclusion );
+
+	}
+
+	if ( buffer === BUFFER_EMISSIVE ) {
+
+		return emissive;
+
+	}
+
+	return diffuseColor.rgb;
+
+}
+
+/**
+ * Replaces the shaded color with the selected buffer. Alpha stays the material's coverage
+ * so masked and transparent surfaces keep their shape.
+ *
+ * @param {string} buffer - `renderer.debug.buffer`.
+ * @return {Node<vec4>} The buffer color.
+ */
+export function bufferVisualizationOutput( buffer ) {
+
+	return vec4( bufferVisualizationColor( buffer ), diffuseColor.a );
+
+}