`renderAsync()` should internally call `waitForGPU()`

[PoseidonEnergy]

Description

I think it's confusing to users to find out that just calling await renderer.renderAsync() alone does not actually wait until the image in the <canvas> element has been updated. If a user wants to render a frame and truly wait until the <canvas> has been updated, they have to do the following:

await renderer.renderAsync(scene, camera);
await renderer.waitForGPU();

Couldn't renderAsync() already do this internally? When would a user want await a call to render a frame, but not wait until the frame is actually visible?

In three.js examples across the internet I rarely will see an example that calls waitForGPU(), but a proper FPS counter or frame rate limiter must have that line, or else it will not be accurate. This is because callbacks passed to requestAnimationFrame(callback) will be fired faster than the <canvas> can update, which messes up a "true" FPS measurement.

This is very noticeable in a moderately complicated scene that has a bit of lag. First, record your scene with a screen recorder (e.g. Bandicam, etc.) with a super high capture rate (e.g. 120Hz). Make sure you are printing out each frame number to the canvas as well as the "measured" FPS. If you record for a few seconds, then play back the recording frame-by-frame, you will notice that the actual number of unique frames rendered in the <canvas> in one second will be much lower than the reported FPS.

Reproduction steps

Make a laggy three.js scene and make sure you are printing the frame number and FPS to the screen on each frame. Do not call renderer.waitForGPU() on each frame. Record the <canvas> with a screen recorder (e.g. Bandicam, etc.) with a high capture rate (e.g. 120Hz) for a few seconds, play the recording back frame-by-frame, and count the number of actual different frames in one second. Compare that to your reported FPS. The actual frame count in one second will be much lower than reported FPS. As soon as you add the line renderer.waitForGPU() after each render, your reported FPS will match the actual frame count.

Version

r180

[Mugen87]

Couldn't renderAsync() already do this internally? When would a user want await a call to render a frame, but not wait until the frame is actually visible?

If the renderer is initialized via await renderer.init(), render() and renderAsync() should behave identical. We can't add waitForGPU() inside renderAsync() because more than one render calls might produce the frame. E.g.

renderer.render(scene, camera);
renderer.render(sceneUI, cameraUI);

In this case, you don't want to call waitForGPU() after each render.

[PoseidonEnergy]

Since render() (the non-async version) internally calls renderAsync(), what is the use of having the non-async version?

Let's assume we get rid of the non-async render() method, and make renderAsync() call waitForGPU() internally.

I would assume that if the user wanted to make several render calls to produce a frame, they could just await the last call:

renderer.renderAsync(scene, camera);
renderer.renderAsync(scene, camera);
await renderer.renderAsync(sceneUI, cameraUI);

Would that not work?

[Mugen87]

The important call is _renderScene() which is sync and the same for both render() and renderAsync(). renderAsync() only exists because unlike WebGLRenderer, WebGPURenderer is initialized in an async fashion.

[PoseidonEnergy]

Even though the _renderScene() method may be synchronous, the act of rendering a frame to the <canvas> element from start to finish is not, from what I've found. If render() in the WebGPU version is just a non-awaitable alias for renderAsync(), couldn't we just remove render() from the WebGPU build? Why not add await this.waitForGPU() after it? Like this:

async renderAsync(scene, camera) {
    if (this._initialized === false) {
        await this.init();
    }
    this._renderScene(scene, camera);
    await this.waitForGPU();
}

Is the WebGPU version required to have both render() and renderAsync()? If we think of rendering a frame as being asynchronous, it doesn't matter if _renderScene() is sync or async, since we need to call await this.waitForGPU() anyway.

With the change above, awaiting or not awaiting renderAsync() actually has tangible effects. Currently, awaiting renderAsync() only matters on the first call, when init() is triggered. After that, awaiting it doesn't do anything useful.

[gkjohnson]

Generally you should not be waiting for the GPU to finish and display a frame before starting the next one since that will lead to an idle GPU and it being used less effectively than it could be. As Mugen mentioned, renderAsync is a convenience function for users that will await the asynchronous WebGPU initialization before actually rendering. Outside of specific use cases users should be using the synchronous render command to issue draw commands. This is a separate discussion but I do wonder if the presence of a renderAsync function is confusing and whether it's better to require users to await init before calling render if they want this behavior.

If you're seeing an issue please make a simple reproduction demonstrating the problem so it can be more easily understood.

[Mugen87]

This is a separate discussion but I do wonder if the presence of a renderAsync function is confusing and whether it's better to require users to await init before calling render if they want this behavior.

Indeed. I have the feeling the method name raises wrong expectations.

[PoseidonEnergy]

If I shouldn't use waitForGPU() for getting an accurate FPS measurement, is there an alternative pattern I can use?