Layers: Add recursive property

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

Author: wrangelvid

examples/jsm/renderers/CSS2DRenderer.js

@@ -221,12 +221,22 @@ class CSS2DRenderer {
 
 			}
 
+			const layerVisible = object.layers.test( camera.layers );
+
+			if ( layerVisible === false && object.layers.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';

examples/jsm/renderers/CSS3DRenderer.js

@@ -369,9 +369,19 @@ class CSS3DRenderer {
 
 			}
 
+			const layerVisible = object.layers.test( camera.layers );
+
+			if ( layerVisible === false && object.layers.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';

src/core/Layers.js

@@ -26,6 +26,16 @@ class Layers {
 		 */
 		this.mask = 1 | 0;
 
+		/**
+		 * When set to `true`, if the layer test fails during rendering traversal,
+		 * the entire subtree of children will be skipped. This improves performance
+		 * by culling entire hierarchies that don't match the camera's layers.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.recursive = false;
+
 	}
 
 	/**

src/core/Raycaster.js

@@ -235,9 +235,13 @@ function ascSort( a, b ) {
 
 function intersect( object, raycaster, intersects, recursive ) {
 
+	const visible = object.layers.test( raycaster.layers );
+
+	if ( visible === false && object.layers.recursive === true ) return;
+
 	let propagate = true;
 
-	if ( object.layers.test( raycaster.layers ) ) {
+	if ( visible ) {
 
 		const result = object.raycast( raycaster, intersects );
 

src/renderers/WebGLRenderer.js

@@ -1803,6 +1803,8 @@ class WebGLRenderer {
 
 			const visible = object.layers.test( camera.layers );
 
+			if ( visible === false && object.layers.recursive === true ) return;
+
 			if ( visible ) {
 
 				if ( object.isGroup ) {

src/renderers/common/Renderer.js

@@ -2809,6 +2809,8 @@ class Renderer {
 
 		const visible = object.layers.test( camera.layers );
 
+		if ( visible === false && object.layers.recursive === true ) return;
+
 		if ( visible ) {
 
 			if ( object.isGroup ) {

src/renderers/webgl/WebGLShadowMap.js

@@ -509,6 +509,8 @@ function WebGLShadowMap( renderer, objects, capabilities ) {
 
 		const visible = object.layers.test( camera.layers );
 
+		if ( visible === false && object.layers.recursive === true ) return;
+
 		if ( visible && ( object.isMesh || object.isLine || object.isPoints ) ) {
 
 			if ( ( object.castShadow || ( object.receiveShadow && type === VSMShadowMap ) ) && ( ! object.frustumCulled || _frustum.intersectsObject( object ) ) ) {

test/unit/src/core/Layers.tests.js

@@ -123,6 +123,23 @@ export default QUnit.module( 'Core', () => {
 
 		} );
 
+		QUnit.test( 'recursive', ( assert ) => {
+
+			const a = new Layers();
+
+			// Default value should be false
+			assert.strictEqual( a.recursive, false, 'Default recursive is false' );
+
+			// Can be set to true
+			a.recursive = true;
+			assert.strictEqual( a.recursive, true, 'Can set recursive to true' );
+
+			// Can be set back to false
+			a.recursive = false;
+			assert.strictEqual( a.recursive, false, 'Can set recursive to false' );
+
+		} );
+
 	} );
 
 } );