Allow reading from buffers

[madsmtm]

In #313, I added a note that reading from the pixel buffer is discouraged, because I wanted to set kIOSurfaceMapWriteCombineCache on macOS once I got around to implementing proper IOSurface support. See e.g. the following links for a few places where it's used in the wild:

• WebKit on iOS: https://bugs.webkit.org/show_bug.cgi?id=130982
• Chromium (was later backed out though): https://chromium-review.googlesource.com/c/chromium/src/+/6575828

I thought this was fine, because I couldn't see a use-case where you'd need to read from the pixel buffer, but that was perhaps a bit hasty, I found at least one use-case: converting the alpha mode (premultiplying components or making the alpha channel opaque) by modifying the buffer in-place in a separate step before presenting it buffer.

This means that the argument for only having the mutable version instead of distinct pixels/pixels_mut, pixel_rows/pixel_rows_mut and pixels_iter/pixels_iter_mut methods is a bit weaker.

WDYT? Should we provide both immutable and mutable methods on Buffer<'_>?

[ids1024]

So it's not really "write only", but more optimized for not reading? Though I guess it should generally be treated the same...

Not sure if any other name would be more appropriate for this method. Maybe not.

[madsmtm]

Maybe write_optimized? Or read_penalized?

[madsmtm]

I just found gfx-rs/wgpu#8897, we might have to make this method unsafe because the write-combined memory seems to work weirdly with atomics? I'm unfamiliar with how write-combined memory actually works.

[madsmtm]

I've changed this PR to only be a docs update to allow reading from the buffer, we can reconsider the set_write_only API later.

[nicoburns]

My understanding is that on certain devices (usually mobile devices, but not sure about Apple mobile devices), there is a hardware fast path for rendering directly into the display controller (skipping the GPU), but that can't then be read back. So the performance gain here is likely from setting the flag on the IoSurface or whatever. Probably it makes sense to let users control this depending on their needs?

[madsmtm]

I'm not aware of any option for controlling this on Android? The closest I could find was AHARDWAREBUFFER_USAGE_CPU_READ_NEVER , but that seems to be used for a rwlock instead, it doesn't actually control the memory caching mode?

I think your understanding is about right on Apple mobile devices though, but it only matters if we can use IOSurface, which I don't currently see a good way to do.