Object3D: Add onBeforeShadow and onAfterShadow callbacks

[RenaudRohlinger]

Fixed #14921.

This PR introduces two new optional callbacks to the Object3D class in three.js. The onBeforeShadow and onAfterShadow callbacks allow developers to execute custom code immediately before and after the shadow of a 3D object is rendered, respectively. These callbacks provide the following parameters: renderer, scene, camera, shadowCamera, geometry, depthMaterial, and group.

Example usage:

cube.onBeforeShadow = function ( renderer, scene, camera, shadowCamera, geometry, depthMaterial, group ) {

	anothercube.visible = true;
	anothercube.modelViewMatrix.multiplyMatrices( shadowCamera.matrixWorldInverse, anothercube.matrixWorld );
	renderer.renderBufferDirect( shadowCamera, null, anothercube.geometry, depthMaterial, anothercube, group );

};

cube.onAfterShadow = function ( ) {

	anothercube.visible = false;

};

These new callbacks offer developers more control and flexibility when working with shadows in their projects.

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

Filesize dev	Filesize PR	Diff
636.3 kB (157.7 kB)	636.5 kB (157.8 kB)	+173 B

🌳 Bundle size after tree-shaking

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

Filesize dev	Filesize PR	Diff
426.8 kB (103.6 kB)	427 kB (103.6 kB)	+173 B

[Mugen87]

Related: It was tried to implement this once via #17932. Based on the discussion in #14921 and the PR I'm not sure why the change was never merged. But maybe the signature of the callback was an issue...

[RenaudRohlinger]

Oh, didn't check the existing PRs, my bad.

[Mugen87]

I see you keep the signature similar to onBeforeRender() and onAfterRender(). I think that makes sense.

At first glance, the change looks good to me!

[Mugen87]

The names of the callback could maybe more compact. Meaning onBeforeShadow() and onAfterShadow(). I guess I prefer those but the ultimate decision is up to @mrdoob .

[Mugen87]

@sunag Just to clarify: Do you think these callbacks would also be useful in context of WebGPURenderer? Or does the node system enable other potential approaches to achieve the same (meaning influencing the shadow map rendering process).

@RenaudRohlinger We should clarify this because ideally new callbacks on Object3D level make sense for both renderers. If we merge this PR, we eventually have to add support to WebGPURenderer, too.

[RenaudRohlinger]

Renamed both methods to onBeforeShadow and onAfterShadow

[sunag]

@sunag Just to clarify: Do you think these callbacks would also be useful in context of WebGPURenderer? Or does the node system enable other potential approaches to achieve the same (meaning influencing the shadow map rendering process).

WebGPURenderer is more simplified to the point that we don't need a WebGPUShadowMap for example, and the controls are done in the nodes. We also don't have a renderBufferDirect() and if we implement it we would have to have more arguments, although in this example we could also replace the geometry in the object itself after it recovers once renderBufferDirect() is called anyway after onBeforeShadowMapRender() if the case is LOD only, we would have other use cases for that?

Or does the node system enable other potential approaches to achieve the same (meaning influencing the shadow map rendering process).

I think it makes sense for WebGPURenderer, maybe we need to add support for this in nodes. Maybe something like .depthNode could solve this.

[Mugen87]

In this case I suggest to stall this PR a bit until we a more confident on the WebGPU side.