onBeforeRender,onAfterRender docs seem to imply they are not called on Scenes, but they are

[donhatch]

Description

The docs for onBeforeRender and onAfterRender (at https://threejs.org/docs/#api/en/core/Object3D, or dev branch) say this:

Please notice that this callback is only executed for renderable 3D objects. Meaning 3D objects which define their visual appearance with geometries and materials like instances of Mesh, Line, Points or Sprite. Instances of Object3D, Group or Bone are not renderable and thus this callback is not executed for such objects.

From that, I would guess that these two functions probably do not get called on Scenes, but that guess would be wrong.

This actual behavior is also mentioned by @Mugen87 in #19477 (comment)_ .

If this behavior is official and can be relied on, it would be good to state it in the docs.

Reproduction steps

doc issue

Code

doc issue

Live example

doc issue

Screenshots

No response

Version

dev branch

Device

No response

Browser

No response

OS

No response

[donhatch]

Also, it seems to be called differently from what the doc specifies:
if ( scene.isScene === true ) scene.onBeforeRender( _this, scene, camera, _currentRenderTarget );
whereas the doc says "This function is called with the following parameters: renderer, scene, camera, geometry, material, group."

[Mugen87]

Scene.onBeforeRender() was introduced for a special use case: #11582

It's probably best to add an entry for onBeforeRender() in the Scene documentation page and state that it overwrites Object3D.onBeforeRender() with a custom signature.

Maybe we should consider to remove Scene.onBeforeRender() since the tiled rendering example has been recently deleted (see #26092). AFAICS, at least in the repository the callback is not in use anymore.

[donhatch]

Maybe we should consider to remove Scene.onBeforeRender()

Oh no! I was hoping it would be made official so I could use it :-)

My use case is that I want to set scene.autoUpdateMatrixWorld=false
(thus preventing the rendere's call to scene.updateMatrixWorld() which seems to be hard to control and does a lot of odd unnecessary work in some cases),
and I would add scene.onBeforeRender = (renderer,scene,camera)=>MyUpdateMatrixWorld(scene);
where MyUpdateMatrixWorld() is a more careful top-down matrixWorld-updating traversal.

OTOH my use case isn't necessarily all that compelling, and perhaps doesn't justify the complication in the API, since I could just call my before-render function myself, explicitly, before each render, instead:

MyUpdateMatrixWorld(scene);
renderer.render(scene, camera);

[shindodkar]

is anyone is working on it?

[Mugen87]

This issue is primarily about updating docs.

However, I would like to know how other collaborators feel about removing onBeforeRender() and onAfterRender() from Scene and only execute the callbacks for actual render items. IMO, this is the more consistent policy.

The example that originally required both callbacks has been removed and the callbacks are also not required for post processing in XR, see #26160.

[shindodkar]

Considering the removal of onBeforeRender() and onAfterRender() callbacks from Scene objects, making them applicable only to actual renderable items. This approach aims to provide a more streamlined and consistent policy, reducing complexity while enhancing the efficiency of these callbacks.

[brandon-xyzw]

I believe they should be called at least for Groups, and maybe Scenes as well. The rationale for this is sometimes you may want to alter renderer state before the collection of renderable objects contained with that group/scene is rendered. For example, maybe you want to clear the depth buffer and set the render order for the group/items to be later, so this group will always be rendered on top.

[OndrejSpanel]

I find Scene.onBeforeRender useful, as it makes it possible to define a custom shadow rendering pass in a Scene without having to alter the place when renderer.render is called, which in my case is inside of an effect composer.

It is not critical, one could add a custom callbacks into the composer instead, but it is handy. If it is not removed, I think it should be documented, as it uses different parameters (WebGLRenderer, Scene, Camera, WebGLRenderTarget) compared to the Object3D version.