Skip to content

Commit

Permalink
New README
Browse files Browse the repository at this point in the history
  • Loading branch information
@i509VCB
i509VCB committed Mar 14, 2023
1 parent 1381217 commit 4e867ca
Showing 1 changed file with 86 additions and 57 deletions.
143 changes: 86 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,71 +1,38 @@
Overview
==
As the popularity of the library [minifb](https://crates.io/crates/minifb) shows, it is useful to put 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 on some platforms and is missing key features such as the ability to set a window
icon. While it would be possible to add these features to minifb, it makes more sense to instead use the standard
window handling systems.

Softbuffer integrates with the [raw-window-handle](https://crates.io/crates/raw-window-handle) crate
to allow writing 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.

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
==
# Softbuffer - Library for displaying pixel buffers in pure Rust.

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
by Softbuffer. Pull requests are welcome to add new platforms! **Nonetheless, all major desktop platforms that winit uses
on desktop are supported.**
[![Crates.io](https://img.shields.io/crates/v/softbuffer.svg)](https://crates.io/crates/softbuffer)
[![Docs.rs](https://docs.rs/softbuffer/badge.svg)](https://docs.rs/softbuffer)
[![CI Status](https://github.com/rust-windowing/softbuffer/workflows/CI/badge.svg)](https://github.com/rust-windowing/softbuffer/actions)

For now, the priority for new platforms is:
1) to have at least one platform on each OS working (e.g. one of Win32 or WinRT, or one of Xlib, Xcb, and Wayland) and
2) for that one platform on each OS to be the one that winit uses.

(PRs will be accepted for any platform, even if it does not follow the above priority.)

✅: Present | ❌: Absent
- AndroidNdk ❌
- AppKit ✅ (Thanks to [Seo Sanghyeon](https://github.com/sanxiyn) and [lunixbochs](https://github.com/lunixbochs)!)
- Orbital ✅
- UiKit ❌
- Wayland ✅ (Wayland support in winit is immature at the moment, so it might be wise to force X11 if you're using winit)
- Web ✅ (Thanks to [Liamolucko](https://github.com/Liamolucko)!)
- Win32 ✅
- WinRt ❌
- Xcb ❌
- Xlib ✅

WebAssembly
-----------
Softbufer allows displaying a 2D pixel buffer on a window in a cross-platform way.

To run an example with the web backend: `cargo run-wasm --example winit`
Softbuffer integrates with [raw-window-handle](https://crates.io/crates/raw-window-handle). This means softbuffer
does not depend on any particular windowing library and can be used with any of the high quality windowing
libraries such as [winit](https://crates.io/crates/winit).

Example
==
## Example
```rust,no_run
// This example uses winit.
//
// Any other library which supports raw-window-handle can also be used.
use winit::event::{Event, WindowEvent};
use winit::event_loop::{ControlFlow, EventLoop};
use winit::window::WindowBuilder;
fn main() {
// Create a window with winit.
let event_loop = EventLoop::new();
let window = WindowBuilder::new().build(&event_loop).unwrap();
// A context communicates with the display server to initialize any state
// shared between windows.
//
// This must not outlive the display server.
let context = unsafe { softbuffer::Context::new(&window) }.unwrap();
// A surface is used to display a buffer on the window.
//
// This is created per window and the surface must not outlive the window and context.
let mut surface = unsafe { softbuffer::Surface::new(&context, &window) }.unwrap();
event_loop.run(move |event, _, control_flow| {
Expand All @@ -77,6 +44,12 @@ fn main() {
let size = window.inner_size();
(size.width, size.height)
};
// Create a gradient to display in the window.
//
// You might use a drawing library such as tiny-skia instead of
// directly setting pixel colors and reuse this buffer if a resize
// has not occured.
let buffer = (0..((width * height) as usize))
.map(|index| {
let y = index / (width as usize);
Expand All @@ -91,6 +64,9 @@ fn main() {
})
.collect::<Vec<_>>();
// Display the buffer on the window.
//
// The width and height should be determined by using your windowing library.
surface.set_buffer(&buffer, width as u16, height as u16);
}
Event::WindowEvent {
Expand All @@ -105,7 +81,60 @@ fn main() {
}
```

Changelog
---------
## Platform support

Not every platform is supported, that [raw-window-handle](https://crates.io/crates/raw-window-handle) supports. Pull requests are welcome to add new platforms!

**Nonetheless, all major desktop platforms that winit uses on desktop are supported.**

For now, the priority for new platforms is:
1. At least one platform for each OS (e.g. one of Win32 or WinRT, or one of Xlib, Xcb, and Wayland)
2. Any other platform supported by winit.
3. Any other platform

| Platform | ✅ (Present) ❌ (Absent) |
|-|-|
| AndroidNdk | ❌ |
| AppKit | ✅ |
| Orbital | ✅ |
| UiKit | ❌ |
| Wayland | ✅ |
| Web | ✅ |
| Win32 | ✅ |
| WinRt | ❌ |
| Xcb | ❌ |
| Xlib | ✅ |

### Thanks to

- AppKit: [Seo Sanghyeon](https://github.com/sanxiyn) and [lunixbochs](https://github.com/lunixbochs)
- Web: [Liamolucko](https://github.com/Liamolucko)

## WebAssembly

To run an example with the web backend: `cargo run-wasm --example winit`

## 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 for the platform-specific implementation.

## Comparison with other crates

### [minifb](https://crates.io/crates/minifb)

minifb is the primary inspiration for this crate. It is easy to present some pixels with minifb but minifb
has quite limited window management capabilities. Softbuffer integrates better with the rust windowing ecosystem
and does not force a specific window management scheme.

### [pixels](https://crates.io/crates/pixels)

Pixels has a similar goal to softbuffer but includes some features that may not be nessecary if the goal is to display
a buffer and nothing else. pixels provides GPU post processing and therefore requires a GPU. This makes pixels unsuitable for
systems where hardware accelerated graphics are not available (e.g. VMs, older computers, computers with
misconfigured or work in progress drivers). Softbuffer should be used over pixels when its GPU-accelerated
post-processing effects are not needed.

# Changelog

See the [changelog](CHANGELOG.md) for a list of this package's versions and the changes made in each version.

0 comments on commit 4e867ca

Please sign in to comment.