From 967eab89bab048f699401b192a4ec0ad38f2d05f Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 27 Jan 2026 15:53:57 +0100 Subject: [PATCH 1/3] Re-order README It's more relevant to list actual features etc. at the top, than to list alternatives. --- README.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 5c59ee24..4c7a86c7 100644 --- a/README.md +++ b/README.md @@ -6,27 +6,6 @@ Softbuffer integrates with the [`raw-window-handle`](https://crates.io/crates/ra to allow writing pixels to a window in a cross-platform way while using the very high quality dedicated window management libraries that are available in the Rust ecosystem. -## Alternatives - -[minifb](https://crates.io/crates/minifb) also allows putting a 2D buffer/image on a window in a platform-independent way. -Minifb's approach to doing window management itself, however, is problematic code duplication. We already have very high quality -libraries for this in the Rust ecosystem (such as [winit](https://crates.io/crates/winit)), and minifb's implementation -of window management is not ideal. For example, it occasionally segfaults and is missing key features such as setting -a window icon on some platforms. While adding these features to minifb would be possible, it makes more sense to use -the standard window handling systems instead. - -What about [pixels](https://crates.io/crates/pixels)? Pixels accomplishes a very similar goal to Softbuffer, -however there are two key differences. Pixels provides some capacity for GPU-accelerated post-processing of what is -displayed, while Softbuffer does not. Due to not having this post-processing, Softbuffer does not rely on the GPU or -hardware accelerated graphics stack in any way, and is thus more portable to installations that do not have access to -hardware acceleration (e.g. VMs, older computers, computers with misconfigured drivers). Softbuffer should be used over -pixels when its GPU-accelerated post-processing effects are not needed. - -## License & Credits - -This library is dual-licensed under MIT or Apache-2.0, just like minifb and rust. Significant portions of code were taken -from the minifb library to do platform-specific work. - ## Platform support: Some, but not all, platforms supported in [raw-window-handle](https://crates.io/crates/raw-window-handle) are supported @@ -159,3 +138,24 @@ same MSRV policy. ## Changelog See the [changelog](CHANGELOG.md) for a list of this package's versions and the changes made in each version. + +## Alternatives + +[minifb](https://crates.io/crates/minifb) also allows putting a 2D buffer/image on a window in a platform-independent way. +Minifb's approach to doing window management itself, however, is problematic code duplication. We already have very high quality +libraries for this in the Rust ecosystem (such as [winit](https://crates.io/crates/winit)), and minifb's implementation +of window management is not ideal. For example, it occasionally segfaults and is missing key features such as setting +a window icon on some platforms. While adding these features to minifb would be possible, it makes more sense to use +the standard window handling systems instead. + +What about [pixels](https://crates.io/crates/pixels)? Pixels accomplishes a very similar goal to Softbuffer, +however there are two key differences. Pixels provides some capacity for GPU-accelerated post-processing of what is +displayed, while Softbuffer does not. Due to not having this post-processing, Softbuffer does not rely on the GPU or +hardware accelerated graphics stack in any way, and is thus more portable to installations that do not have access to +hardware acceleration (e.g. VMs, older computers, computers with misconfigured drivers). Softbuffer should be used over +pixels when its GPU-accelerated post-processing effects are not needed. + +## License & Credits + +This library is dual-licensed under MIT or Apache-2.0, just like minifb and rust. Significant portions of code were taken +from the minifb library to do platform-specific work. From 2c4005de3b39b391158faf2a324e38984a9801ba Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 27 Jan 2026 19:36:12 +0100 Subject: [PATCH 2/3] Rewrite introductory documentation Provide motivation and recommend `tiny-skia` and `vello_cpu` for drawing primitives. --- Cargo.toml | 2 +- README.md | 22 ++++++++++++++++++---- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index b18d9371..82a1ed2c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,7 +5,7 @@ members = ["run-wasm"] name = "softbuffer" version = "0.4.8" edition = "2021" -description = "Cross-platform software buffer" +description = "Cross-platform buffer for software rendering" license = "MIT OR Apache-2.0" documentation = "https://docs.rs/softbuffer" repository = "https://github.com/rust-windowing/softbuffer" diff --git a/README.md b/README.md index 4c7a86c7..ad4fa164 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,24 @@ # Softbuffer -Enables software rendering via drawing an image straight to a window. +Render an image on the CPU and show it on a window in a cross-platform manner. -Softbuffer integrates with the [`raw-window-handle`](https://crates.io/crates/raw-window-handle) crate -to allow writing pixels to a window in a cross-platform way while using the very high quality dedicated window management -libraries that are available in the Rust ecosystem. +There exist many libraries for doing realtime rendering on the GPU, such as `wgpu`, `blade`, +`ash`, etc. This is often the sensible choice, but there are a few cases where it makes sense to +render on the CPU, such as for learning purposes, drawing simple 2D scenes or GUIs, or as a +fallback rendering path when a GPU isn't available. Softbuffer allows you to do this. + +To use Softbuffer, first create a window using `winit`, `sdl3`, or any other crate that provides a +[`raw_window_handle::HasWindowHandle`]. + +Next, you create a [`Context`] and [`Surface`] from that window, and can now call +[`Surface::buffer_mut()`] to get a [`Buffer`] that you can draw into. Once you're done drawing, call +[`Buffer::present()`] to show the buffer on the window. + +Note that Softbuffer only provides the `&mut [...]` buffer, it does not provide any rendering +primitives for drawing rectangles, circles, curves and so on. For that, you'll want to use crates +like [`tiny-skia`](https://docs.rs/tiny-skia/) or [`vello_cpu`](https://docs.rs/vello_cpu/). + +[`raw_window_handle::HasWindowHandle`]: https://docs.rs/raw-window-handle/0.6.2/raw_window_handle/trait.HasWindowHandle.html ## Platform support: From 57835ece1e22b97f2b6e0f50958282425568d68e Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 27 Jan 2026 19:06:23 +0100 Subject: [PATCH 3/3] Add "how it works" section to README --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index ad4fa164..3202798d 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,23 @@ like [`tiny-skia`](https://docs.rs/tiny-skia/) or [`vello_cpu`](https://docs.rs/ [`raw_window_handle::HasWindowHandle`]: https://docs.rs/raw-window-handle/0.6.2/raw_window_handle/trait.HasWindowHandle.html +## How it works + +Most platforms have a compositor of some sort (WindowServer on macOS, Desktop Window Manager on +Windows, the Wayland compositor, etc). This is a separate process that applications communicate +with over IPC, and it is responsible for taking the various surfaces that applications send to it +and mash ("composite") them together in the right way to render the user's desktop on the +connected monitors. + +The role of Softbuffer then is to create a shared memory region (i.e. [`Buffer`]) that can be +written to from the CPU, and then handed to the compositor (in [`Buffer::present`]). Softbuffer +keeps a set of buffers around per surface to implement double-buffering (depending on platform +requirements). + +Softbuffer strives to present buffers in a zero-copy manner. One interesting wrinkle here is that +the compositor is often GPU-accelerated, so on platforms without a unified memory architecture, +some copying is inherently necessary (though when possible, it is done in hardware using DMA). + ## Platform support: Some, but not all, platforms supported in [raw-window-handle](https://crates.io/crates/raw-window-handle) are supported