From 51f29e04c8fb7a89f2b3c533ad0012d503d7fcdf Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Fri, 23 Jan 2026 18:29:35 +0100 Subject: [PATCH] Allow reading from buffers Disallowing reading is overly restrictive, and we don't use write-combined memory anywhere yet anyhow. --- src/lib.rs | 30 ++++-------------------------- 1 file changed, 4 insertions(+), 26 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5aeeaa8a..ad8f20d2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -271,33 +271,11 @@ impl HasWindowHandle for Surface /// /// # Reading buffer data /// -/// Reading from buffer data may perform very poorly, as the underlying storage of zero-copy -/// buffers, where implemented, may set options optimized for CPU writes, that allows them to bypass -/// certain caches and avoid cache pollution. +/// The API of this is simplified for writing to buffer data, so various `&self -> &[X]` methods are +/// intentionally not provided. You can still read from the buffer data via. the `&mut self` methods +/// though. /// -/// As such, when rendering, you should always set the pixel in its entirety: -/// -/// ``` -/// # use softbuffer::Pixel; -/// # let pixel = &mut Pixel::default(); -/// # let (red, green, blue) = (0x11, 0x22, 0x33); -/// *pixel = Pixel::new_rgb(red, green, blue); -/// ``` -/// -/// Instead of e.g. something like: -/// -/// ``` -/// # use softbuffer::Pixel; -/// # let pixel = &mut Pixel::default(); -/// # let (red, green, blue) = (0x11, 0x22, 0x33); -/// // DISCOURAGED! -/// *pixel = Pixel::default(); // Clear -/// pixel.r |= red; -/// pixel.g |= green; -/// pixel.b |= blue; -/// ``` -/// -/// To discourage reading from the buffer, `&self -> &[u8]` methods are intentionally not provided. +/// TODO: Add API for optimizing surface to only be written to (`kIOSurfaceMapWriteCombineCache`)? /// /// # Platform dependent behavior ///