Layers: Add recursive property

Co-Authored-By: Cody Bennett <cody.j.bennett@icloud.com>

Author: wrangelvid

examples/jsm/renderers/CSS2DRenderer.js

@@ -211,7 +211,7 @@ class CSS2DRenderer {
 
 		}
 
-		function renderObject( object, scene, camera ) {
+		function renderObject( object, scene, camera, inheritedLayers = null ) {
 
 			if ( object.visible === false ) {
 
@@ -221,12 +221,23 @@ class CSS2DRenderer {
 
 			}
 
+			const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
+			const layerVisible = effectiveLayers.test( camera.layers );
+
+			if ( layerVisible === false && effectiveLayers.recursive === true ) {
+
+				hideObject( object );
+
+				return;
+
+			}
+
 			if ( object.isCSS2DObject ) {
 
 				_vector.setFromMatrixPosition( object.matrixWorld );
 				_vector.applyMatrix4( _viewProjectionMatrix );
 
-				const visible = ( _vector.z >= - 1 && _vector.z <= 1 ) && ( object.layers.test( camera.layers ) === true );
+				const visible = ( _vector.z >= - 1 && _vector.z <= 1 ) && layerVisible;
 
 				const element = object.element;
 				element.style.display = visible === true ? '' : 'none';
@@ -255,9 +266,11 @@ class CSS2DRenderer {
 
 			}
 
+			const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;
+
 			for ( let i = 0, l = object.children.length; i < l; i ++ ) {
 
-				renderObject( object.children[ i ], scene, camera );
+				renderObject( object.children[ i ], scene, camera, childInheritedLayers );
 
 			}
 

examples/jsm/renderers/CSS3DRenderer.js

@@ -359,7 +359,7 @@ class CSS3DRenderer {
 
 		}
 
-		function renderObject( object, scene, camera, cameraCSSMatrix ) {
+		function renderObject( object, scene, camera, cameraCSSMatrix, inheritedLayers = null ) {
 
 			if ( object.visible === false ) {
 
@@ -369,9 +369,20 @@ class CSS3DRenderer {
 
 			}
 
+			const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
+			const layerVisible = effectiveLayers.test( camera.layers );
+
+			if ( layerVisible === false && effectiveLayers.recursive === true ) {
+
+				hideObject( object );
+
+				return;
+
+			}
+
 			if ( object.isCSS3DObject ) {
 
-				const visible = ( object.layers.test( camera.layers ) === true );
+				const visible = layerVisible;
 
 				const element = object.element;
 				element.style.display = visible === true ? '' : 'none';
@@ -431,9 +442,11 @@ class CSS3DRenderer {
 
 			}
 
+			const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;
+
 			for ( let i = 0, l = object.children.length; i < l; i ++ ) {
 
-				renderObject( object.children[ i ], scene, camera, cameraCSSMatrix );
+				renderObject( object.children[ i ], scene, camera, cameraCSSMatrix, childInheritedLayers );
 
 			}
 

src/core/Layers.js

@@ -26,6 +26,17 @@ class Layers {
 		 */
 		this.mask = 1 | 0;
 
+		/**
+		 * When set to `true`, this object's layer mask is propagated to all
+		 * descendants during rendering and raycasting traversal. If the layer
+		 * test fails, the entire subtree is skipped. If it passes, children
+		 * inherit this object's layers instead of using their own.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.recursive = false;
+
 	}
 
 	/**

src/core/Object3D.js

@@ -1080,6 +1080,37 @@ class Object3D extends EventDispatcher {
 
 	}
 
+	/**
+	 * Like {@link Object3D#traverseVisible}, but the callback will only be executed
+	 * for visible 3D objects that pass the layer test. Descendants of invisible
+	 * 3D objects and objects with recursive layers that fail the test are not traversed.
+	 *
+	 * Note: Modifying the scene graph inside the callback is discouraged.
+	 *
+	 * @param {Layers} cameraLayers - The camera layers to test against.
+	 * @param {Function} callback - A callback function that allows to process the current 3D object.
+	 */
+	traverseVisibleWithLayers( cameraLayers, callback, inheritedLayers = null ) {
+
+		if ( this.visible === false ) return;
+
+		const effectiveLayers = inheritedLayers ?? this.layers;
+		const layerVisible = effectiveLayers.test( cameraLayers );
+
+		if ( !layerVisible && effectiveLayers.recursive ) return;
+
+		if ( layerVisible ) callback( this );
+
+		const childInheritedLayers = this.layers.recursive ? this.layers : inheritedLayers;
+
+		for ( let i = 0, l = this.children.length; i < l; i ++ ) {
+
+			this.children[ i ].traverseVisibleWithLayers( cameraLayers, callback, childInheritedLayers );
+
+		}
+
+	}
+
 	/**
 	 * Like {@link Object3D#traverse}, but the callback will only be executed for all ancestors.
 	 *

src/core/Raycaster.js

@@ -233,11 +233,16 @@ function ascSort( a, b ) {
 
 }
 
-function intersect( object, raycaster, intersects, recursive ) {
+function intersect( object, raycaster, intersects, recursive, inheritedLayers = null ) {
+
+	const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
+	const visible = effectiveLayers.test( raycaster.layers );
+
+	if ( visible === false && effectiveLayers.recursive === true ) return;
 
 	let propagate = true;
 
-	if ( object.layers.test( raycaster.layers ) ) {
+	if ( visible ) {
 
 		const result = object.raycast( raycaster, intersects );
 
@@ -247,11 +252,13 @@ function intersect( object, raycaster, intersects, recursive ) {
 
 	if ( propagate === true && recursive === true ) {
 
+		const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;
+
 		const children = object.children;
 
 		for ( let i = 0, l = children.length; i < l; i ++ ) {
 
-			intersect( children[ i ], raycaster, intersects, true );
+			intersect( children[ i ], raycaster, intersects, true, childInheritedLayers );
 
 		}
 

src/renderers/WebGLRenderer.js

@@ -1373,9 +1373,9 @@ class WebGLRenderer {
 
 			// gather lights from both the target scene and the new object that will be added to the scene.
 
-			targetScene.traverseVisible( function ( object ) {
+			targetScene.traverseVisibleWithLayers( camera.layers, function ( object ) {
 
-				if ( object.isLight && object.layers.test( camera.layers ) ) {
+				if ( object.isLight ) {
 
 					currentRenderState.pushLight( object );
 
@@ -1391,9 +1391,9 @@ class WebGLRenderer {
 
 			if ( scene !== targetScene ) {
 
-				scene.traverseVisible( function ( object ) {
+				scene.traverseVisibleWithLayers( camera.layers, function ( object ) {
 
-					if ( object.isLight && object.layers.test( camera.layers ) ) {
+					if ( object.isLight ) {
 
 						currentRenderState.pushLight( object );
 
@@ -1797,11 +1797,14 @@ class WebGLRenderer {
 
 		};
 
-		function projectObject( object, camera, groupOrder, sortObjects ) {
+		function projectObject( object, camera, groupOrder, sortObjects, inheritedLayers = null ) {
 
 			if ( object.visible === false ) return;
 
-			const visible = object.layers.test( camera.layers );
+			const effectiveLayers = inheritedLayers !== null ? inheritedLayers : object.layers;
+			const visible = effectiveLayers.test( camera.layers );
+
+			if ( visible === false && effectiveLayers.recursive === true ) return;
 
 			if ( visible ) {
 
@@ -1839,7 +1842,7 @@ class WebGLRenderer {
 
 						if ( material.visible ) {
 
-							currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null );
+							currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null, effectiveLayers );
 
 						}
 
@@ -1883,15 +1886,15 @@ class WebGLRenderer {
 
 								if ( groupMaterial && groupMaterial.visible ) {
 
-									currentRenderList.push( object, geometry, groupMaterial, groupOrder, _vector4.z, group );
+									currentRenderList.push( object, geometry, groupMaterial, groupOrder, _vector4.z, group, effectiveLayers );
 
 								}
 
 							}
 
 						} else if ( material.visible ) {
 
-							currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null );
+							currentRenderList.push( object, geometry, material, groupOrder, _vector4.z, null, effectiveLayers );
 
 						}
 
@@ -1901,11 +1904,13 @@ class WebGLRenderer {
 
 			}
 
+			const childInheritedLayers = object.layers.recursive === true ? object.layers : inheritedLayers;
+
 			const children = object.children;
 
 			for ( let i = 0, l = children.length; i < l; i ++ ) {
 
-				projectObject( children[ i ], camera, groupOrder, sortObjects );
+				projectObject( children[ i ], camera, groupOrder, sortObjects, childInheritedLayers );
 
 			}
 
@@ -2020,9 +2025,9 @@ class WebGLRenderer {
 
 					const renderItem = transmissiveObjects[ i ];
 
-					const { object, geometry, material, group } = renderItem;
+					const { object, geometry, material, group, effectiveLayers } = renderItem;
 
-					if ( material.side === DoubleSide && object.layers.test( camera.layers ) ) {
+					if ( material.side === DoubleSide && effectiveLayers.test( camera.layers ) ) {
 
 						const currentSide = material.side;
 
@@ -2067,7 +2072,7 @@ class WebGLRenderer {
 
 				const renderItem = renderList[ i ];
 
-				const { object, geometry, group } = renderItem;
+				const { object, geometry, group, effectiveLayers } = renderItem;
 				let material = renderItem.material;
 
 				if ( material.allowOverride === true && overrideMaterial !== null ) {
@@ -2076,7 +2081,7 @@ class WebGLRenderer {
 
 				}
 
-				if ( object.layers.test( camera.layers ) ) {
+				if ( effectiveLayers.test( camera.layers ) ) {
 
 					renderObject( object, scene, camera, geometry, material, group );
 

src/renderers/common/RenderList.js

@@ -225,7 +225,7 @@ class RenderList {
 	 * @param {ClippingContext} clippingContext - The current clipping context.
 	 * @return {Object} The render item.
 	 */
-	getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext ) {
+	getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers ) {
 
 		let renderItem = this.renderItems[ this.renderItemsIndex ];
 
@@ -240,7 +240,8 @@ class RenderList {
 				renderOrder: object.renderOrder,
 				z: z,
 				group: group,
-				clippingContext: clippingContext
+				clippingContext: clippingContext,
+				effectiveLayers: effectiveLayers
 			};
 
 			this.renderItems[ this.renderItemsIndex ] = renderItem;
@@ -256,6 +257,7 @@ class RenderList {
 			renderItem.z = z;
 			renderItem.group = group;
 			renderItem.clippingContext = clippingContext;
+			renderItem.effectiveLayers = effectiveLayers;
 
 		}
 
@@ -276,10 +278,11 @@ class RenderList {
 	 * @param {number} z - Th 3D object's depth value (z value in clip space).
 	 * @param {?number} group - {?Object} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`.
 	 * @param {ClippingContext} clippingContext - The current clipping context.
+	 * @param {Layers} effectiveLayers - The effective layers for layer visibility testing.
 	 */
-	push( object, geometry, material, groupOrder, z, group, clippingContext ) {
+	push( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers ) {
 
-		const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext );
+		const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers );
 
 		if ( object.occlusionTest === true ) this.occlusionQueryCount ++;
 
@@ -310,10 +313,11 @@ class RenderList {
 	 * @param {number} z - Th 3D object's depth value (z value in clip space).
 	 * @param {?number} group - {?Object} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`.
 	 * @param {ClippingContext} clippingContext - The current clipping context.
+	 * @param {Layers} effectiveLayers - The effective layers for layer visibility testing.
 	 */
-	unshift( object, geometry, material, groupOrder, z, group, clippingContext ) {
+	unshift( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers ) {
 
-		const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext );
+		const renderItem = this.getNextRenderItem( object, geometry, material, groupOrder, z, group, clippingContext, effectiveLayers );
 
 		if ( material.transparent === true || material.transmission > 0 ||
 			( material.transmissionNode && material.transmissionNode.isNode ) ||

src/renderers/common/RenderObject.js

@@ -200,6 +200,15 @@ class RenderObject {
 		 */
 		this.group = null;
 
+		/**
+		 * The effective layers for layer visibility testing.
+		 * This accounts for recursive layer inheritance from ancestors.
+		 *
+		 * @type {?Layers}
+		 * @default null
+		 */
+		this.effectiveLayers = null;
+
 		/**
 		 * An array holding the vertex buffers which can
 		 * be buffer attributes but also interleaved buffers.