Rename/remove/redocument waitForGPU

[greggman]

Related issue: #31925 (comment)

Description

waitForGPU is a wrapper around onSubmittedWorkDone. You should never have to call onSubmittedWorkDone when using WebGPU. onSubmittedWorkDone is not for sychronization, it is for throttling. That's it. It is never used for synchronization. If calling it appears to fix a bug you have a different bug and the call is just hiding the actual bug.

Reproduction steps

grep for waitForGPU. See it's documented as "synchronize CPU operations with GPU tasks". This is FALSE!

Code

	/**
	 * Can be used to synchronize CPU operations with GPU tasks. So when this method is called,
	 * the CPU waits for the GPU to complete its operation (e.g. a compute task).
	 *
	 * @async
	 * @return {Promise} A Promise that resolves when synchronization has been finished.
	 */
	async waitForGPU() {

		await this.device.queue.onSubmittedWorkDone();

	}

Live example

N/A

Screenshots

N/A

Version

Top of Tree

Device

No response

Browser

No response

OS

No response

[Mugen87]

So to be clear onSubmittedWorkDone() is not the WebGPU pendant of gl.fenceSync()/gl.clientWaitSync() of WebGL?

[greggman]

Correct. It's not the same. And there are no fences in WebGPU. At least not yet.

[PoseidonEnergy]

In a project of mine, I am using waitForGPU() to block my animation loop until the <canvas> is actually updated. This way, my FPS counter actually gives me a true FPS measurement of frames drawn in the <canvas>.

However, when testing waitForGPU() in FireFox, it lags my scene big time (down to 10fps).

So, I think I probably shouldn’t be using waitForGPU() for waiting until the <canvas> has been updated.

Is my predicament related to this issue? I’m just trying to await until the canvas draws each new frame.

[Mugen87]

@RenaudRohlinger waitForGPU() isn't used in the core and examples once. Would you be okay if we remove the method? It seems it was added in #29686 under wrong assumptions (at least on the WebGPU side).

[RenaudRohlinger]

I agree the current doc text (“synchronize CPU operations with GPU tasks”) is misleading, we should update it. The intent of waitForGPU() is to wrap WebGPU’s GPUQueue.onSubmittedWorkDone()
together with our WebGL fallback _clientWaitAsync, so callers can await the queue’s work submitted up to the call. This is primarily for throttling/back-pressure, not a general CPU↔GPU synchronization primitive.

For readbacks, you should still await buffer.mapAsync(...) for correctness. waitForGPU() can be used as an optional throttle point; we don’t rely on it to make mapAsync complete. (The spec notes that resolution implies completion of prior mapAsync() only for buffers last used exclusively on that queue, which is a nuance we don’t depend on.)

References:

MDN: resolves when all work submitted to the queue at call time has been processed.

Spec: resolves once the queue finishes processing all work submitted up to this moment; resolution implies completion of prior mapAsync() on buffers last used exclusively on that queue.
https://www.w3.org/TR/webgpu/#dom-gpuqueue-onsubmittedworkdone
I don’t think of waitForGPU() as “sync with GPU,” but as “await the GPU’s in-flight work (so far).” I was confused by the naming at first myself when adding the feature, that’s why I called it out in the PR. If this interpretation proves wrong in practice, I’m fine renaming or removing it.

If we want a clearer name: waitForSubmittedWork, waitForQueueIdle, waitForGPUIdle, or awaitGPUWorkDone.

[greggman]

This is just my person opinion. I would remove it until such time as it has a point. Many people will likely mis-understand the point of the function and end up using it and, like #31925 they use it, find something gets fixed, and assume it's because they needed to call it when in reality, calling it was just hiding the real bug. If could go back in time I'd remove it or rename it in the WebGPU API too because this is not the first time I've seen this function mis-understood. It happens a lot 😔

[RenaudRohlinger]

Fine with me to remove it, it's pretty straightforward to implement it in user-land anyway.