Documentation of `StagingBelt::allocate` possibly inaccurate

[jgraef]

I was checking out the StagingBelt documentation and source code to understand how it works. The doc for allocate says:

You can then record your own GPU commands to perform with the slice, such as copying it to a texture or executing a compute shader that reads it

Unfortunately I think this isn't true. The buffers are allocated with MAP_WRITE | COPY_SRC so you can only copy from it (source).

My first thought was to let the user specify a BufferUsage at creation, but that wouldn't work either, since MAP_WRITE can usually only be paired with COPY_SRC, so reading it from a compute shader just doesn't work (it requires STORAGE, right?). You'd need to first copy it to a second buffer to read it with a compute shader.

[cwfitzgerald]

Hmm, that does seem to be the case. Yeah supporting more usages might be useful with the MAPPABLE_PRIMARY_BUFFERS feature though. @kpreid do you have thoughts about if this is worthwhile?

[kpreid]

Thought 1: I think I just wrote speculative over-ambitious documentation there, and it would be fine to change it to say “You can then record your own copy_buffer_to_* commands to perform with the slice.”

Thought 2: But if it’s possible to expand the set of usages, then it would make sense to add a parameter to StagingBelt::new() that lets you do that. I have no opinion on whether this is worthwhile.

My own use case was issuing copy_buffer_to_texture() commands.