Document when get_current_texture() etc. block (and provide alternative?)

[kpreid]

I learned only by overhearing discussions that Surface::get_current_texture() blocks if the GPU hasn't finished previously presented work. Further experiment determined that this is true on native, but on the WebGL backend (on Chrome), instead it seems like submit() is the call that takes extra time. (I have not tested WebGPU.)

It would be useful to document which of these calls may block, when, so that applications can design around this. In my case, I primarily wanted to collect performance measurements, so it's useful to know which things are especially worth measuring, but additionally it may be useful to order steps such that as much CPU work is done as possible before entering get_current_texture(), to maximize concurrency between the CPU and GPU.

Additionally, it would be nice to have non-blocking alternatives, so that applications may spend time on other work rather than purely waiting for the GPU, without necessarily having to introduce multithreading at that point. (For example, consider the classic problem where something flashy happens on screen and produces Way Too Many Particle Effects for the available fillrate; if the simulation of those effects can proceed asynchronously, then the system will recover faster since it will have progressed past those effects sooner.)

[cwfitzgerald]

100% agree we need to document this behavior. Generally speaking only submit or get_current_texture() (i.e. acquire) block in practice. get_current_texture is what should block, by api logic, but drivers have other plans. For example: vulkan on all vendors blocks on get_current_texture. However, nvidia will start blocking on submit if it's trying to do weird stuff with presentation (for example running a gsync monitor).

additionally it may be useful to order steps such that as much CPU work is done as possible before entering get_current_texture(), to maximize concurrency between the CPU and GPU.

Do note, that in normal circumstances, after get_current_texture starts blocking, the gpu (or presentation engine in the FIFO case) is already up to three frames behind the cpu. There isn't therefore much benefit to further overlapping. This information is all very poorly explained in general and only really came up in my research for pacy.

Additionally, it would be nice to have non-blocking alternatives, so that applications may spend time on other work rather than purely waiting for the GPU, without necessarily having to introduce multithreading at that point.

Unfortunately, I don't know of an api that would let us do this asynchronously. The closes we get is - a if a frame is ready yet on DXGI/Win8.1+, but we can't do any "callback when thing is ready" deal that proper async needs. imo it's better to be upfront about the block-ey-ness of the call, and let the user multithread it if they want to.