Document softbuffer_quickstart 0.3.0

Author: pastthepixels

README.md

@@ -30,10 +30,14 @@ fn main() {
 }
 ```
 
+## I wanna know more!
+`cargo add softbuffer_quickstart` and read the documentation at `doc/`!
+
 
 ## Contributing
 PRs are welcome! As with any of my other projects it might take a while for me to respond to issues/pull requests. I recommend not squashing your commits before you submit a PR as doing so makes it a bit harder to review your code.  
 I'm looking for any ways to boost performance as much as possible while making the library simpler and more intuitive.
 
 ## Ideas:
 - Adding icons to WindowProperties (probably good for new contributors)
+- Supporting compiling to wasm (hell)

doc/ADVANCED.md

@@ -0,0 +1,134 @@
+Advanced Introduction to `softbuffer-quickstart`
+================================================
+<small>a.k.a, "Well, what *more* can I do?"</small>
+
+> [!NOTE]
+> This assumes that you've read the basic introduction first. If you haven't taken a look at it--and you have time--I encourage you to do so!`
+
+`softbuffer_quickstart`, at its core, actually provides utility functions for people who want to implement their own Winit windows. Let's work backwards. Say you want to implement your own Winit window. Then you'd certainly implement [`ApplicationHandler`](https://rust-windowing.github.io/winit/winit/application/trait.ApplicationHandler.html):
+
+```rust
+use winit::application::ApplicationHandler;
+use winit::event::WindowEvent;
+use winit::event_loop::ActiveEventLoop;
+use winit::window::WindowId;
+ 
+ 
+use softbuffer_quickstart::{init, WindowProperties};
+ 
+struct MyWindow {}
+ 
+impl ApplicationHandler for MyWindow {
+    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+        todo!()
+    }
+
+    fn window_event(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, event: WindowEvent) {
+        todo!()
+    }
+}
+```
+
+But wait! How does `softbuffer_quickstart` fit into this? Well, let's take a look at those TODOs.
+
+## 1. Initializing `softbuffer_quickstart`
+
+Initializing `softbuffer_quickstart` is simple. We'll call `init` with the given event loop and a set of initial window properties (remember `WindowProperties`?), which will give us a `RawWindow` and `RawSurface` to store ourselves:
+
+```rust
+use winit::application::ApplicationHandler;
+use winit::event::WindowEvent;
+use winit::event_loop::ActiveEventLoop;
+use winit::window::WindowId;
+ 
+ 
+use softbuffer_quickstart::{init, RawSurface, RawWindow, WindowProperties};
+ 
+struct MyWindow {
+    window: RawWindow,
+    surface: RawSurface
+}
+ 
+impl ApplicationHandler for MyWindow {
+    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+        (self.window, self.surface) = init(event_loop, &WindowProperties::default());
+    }
+
+    fn window_event(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, event: WindowEvent) {
+        todo!()
+    }
+}
+```
+
+## 2. Drawing to a window (and other handy functions)
+
+Under `window_event` we're given free rein to handle anything. There are two handy functions that can make handling some events simpler:
+- `softbuffer_quickstart::close(&event_loop, &event)` checks to see if a "close" event has been signalled, and closes the window if it has.
+- `softbuffer_quickstart::resize(&event, &mut surface)` check to see if a "resize" event has been signalled, and resizes the underlying buffer.
+
+We can of course omit these and implement those checks ourselves, if we'd like. (However, no one probably wants to unwrap and clone and get references a bunch of times.)
+
+Everything else is stupid simple. We update the buffer how we want, and then call `redraw` once we're done.
+- `softbuffer_quickstart::buffer_mut(surface: &mut RawSurface)` returns a mutable reference to a `RawSurface`. (Hey, just like in the basic tutorial!)
+- `softbuffer_quickstart::redraw(window: &mut RawWindow, surface: &mut RawSurface)` presents the `RawSurface` to the screen, using the `RawWindow`.
+
+The final piece of the puzzle is *running* the thing. All we have to do is call `softbuffer_quickstart::run()` with a mutable reference to our window.
+
+So if we recreated the code in the basic introduction, it'd look like this:
+
+```rust
+use winit::application::ApplicationHandler;
+use winit::event::WindowEvent;
+use winit::event_loop::ActiveEventLoop;
+use winit::window::WindowId;
+ 
+ 
+use softbuffer_quickstart::{init, RawSurface, RawWindow, WindowProperties};
+
+fn main() {
+    let mut window = MyWindow {
+        window: None,
+        surface: None,
+        size: (800, 600)
+    };
+    softbuffer_quickstart::run(&mut window).expect("Window can't run");
+}
+ 
+struct MyWindow {
+    window: RawWindow,
+    surface: RawSurface,
+    size: (usize, usize)
+}
+ 
+impl ApplicationHandler for MyWindow {
+    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+        (self.window, self.surface) = init(event_loop, &WindowProperties::default());
+    }
+
+    fn window_event(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, event: WindowEvent) {
+        softbuffer_quickstart::close(event_loop, &event);
+        softbuffer_quickstart::resize(&event, &mut self.surface);
+        
+        match event {
+            WindowEvent::Resized(size) => {
+                self.size = (size.width as usize, size.height as usize);
+            }
+            WindowEvent::RedrawRequested => {
+                let (width, height) = self.size;
+                let mut buffer = softbuffer_quickstart::buffer_mut(&mut self.surface);
+                for index in 0..(width * height) {
+                    let y = index / width;
+                    let x = index % width;
+                    let red = x % 255;
+                    let green = y % 255;
+                    let blue = (255 - (red + green).min(255)) % 255;
+
+                    buffer[index] = (blue | (green << 8) | (red << 16)).try_into().unwrap();
+                }
+                softbuffer_quickstart::redraw(&mut self.window, &mut self.surface);
+            }
+            _ => (),
+        }
+    }
+}
+```

doc/BASIC.md

@@ -0,0 +1,76 @@
+Basic Introduction to `softbuffer-quickstart`
+=============================================
+<small>a.k.a, "I just wanna make a window, dab nagit!"</small>
+
+If you want to make a simple window, `softbuffer-quickstart` has you covered. (I mean, that's its entire thing!) Keep in mind that you'll lose a bit of control over window/device events, so if having more control is important to you, check out the advanced guide.
+
+## Quick, gimmie the source code!
+```rust
+use softbuffer_quickstart::{SoftbufferWindow, WindowProperties};
+use winit::event::WindowEvent;
+
+fn main() {
+    let mut window = SoftbufferWindow::new(WindowProperties::default());
+    window
+        .run(move |window, event| match event {
+            WindowEvent::RedrawRequested => {
+                let (width, height) = window.inner_size();
+                let mut buffer = window.buffer_mut();
+                for index in 0..(width * height) {
+                    let y = index / width;
+                    let x = index % width;
+                    let red = x % 255;
+                    let green = y % 255;
+                    let blue = (255 - (red + green).min(255)) % 255;
+
+                    buffer[index] = (blue | (green << 8) | (red << 16)).try_into().unwrap();
+                }
+            }
+            _ => (),
+        })
+        .expect("window can't run :(");
+}
+```
+
+## What does this do?
+`softbuffer_quickstart` has a handy dandy `SoftbufferWindow` class that pretty much handles the pain of using Winit. To create a new window, just use `SoftbufferWindow::new()` with a `WindowProperties` struct.
+
+`WindowProperties` is a quick way to define things like the width, height, and title of a window. This will help `softbuffer_quickstart` to create a Winit window and resize the buffer. You can create a `WindowProperties` like this:
+
+```rust
+use softbuffer_quickstart::{SoftbufferWindow, WindowProperties};
+
+fn main() {
+    let properties = WindowProperties {
+        title: "My super cool window",
+        width: 800, // Measurements in pixels
+        height: 600
+    };
+}
+```
+
+or this:
+
+```rust
+use softbuffer_quickstart::{SoftbufferWindow, WindowProperties};
+
+fn main() {
+    let properties = WindowProperties {
+        title: "My super cool window",
+        ..
+        WindowProperties::default() // We can just tell Rust to
+                                    // make the rest of the properties
+                                    // default ones.
+    };
+}
+```
+
+Next. What does `window.run` do?
+
+When you run a window, you have to move ownership of every variable you used outside the loop function *into* the loop function with the `move` keyword. Then, that function is called every time Winit polls your operating system for new events. Handling `WindowEvents` is in the [Winit documentation](https://docs.rs/winit/latest/winit/event/enum.WindowEvent.html), but all we really need is to see when we're supposed to redraw a window. Winit caps this to the monitor's refresh rate.
+
+Inside the loop function, we get the window's width and height from Winit with `window.inner_size()`, get a mutable reference to the buffer with `window.buffer_mut()`, and then set each pixel to some weird thing. All that matters about the weird thing we do in the for loop is that the indices in the buffer are referenced and set to a `u32` value. What are some ways to define 32-bit color values? Look no further than hexadecimal notation, which you've probably seen when styling things with CSS. For instance, pure red can be defined with `0xff0000`. Each channel (R, G, B) is represented with two hexadecimal values that go up to 255.
+
+After the loop function has been run, `softbuffer_quickstart` will automatically show the buffer and clear it for the next loop.
+
+Finally, the `expect()` at the bottom is because Winit sometimes can't make a window. In this case--which is rare--we'll just print out some small message and Rust will handle a stack trace for us.

src/lib.rs

@@ -37,7 +37,7 @@ impl Default for WindowProperties {
     }
 }
 
-/// Shorthand to run a struct that implements `ApplicationHandler`
+/// Shorthand to run a struct that implements winit's [`ApplicationHandler`](https://rust-windowing.github.io/winit/winit/application/trait.ApplicationHandler.html)
 pub fn run<A: ApplicationHandler<()>>(window: &mut A) -> Result<(), EventLoopError> {
     let event_loop = EventLoop::new()?;
     event_loop.set_control_flow(ControlFlow::Poll);
@@ -47,11 +47,29 @@ pub fn run<A: ApplicationHandler<()>>(window: &mut A) -> Result<(), EventLoopErr
 /// Initialises and returns a new RawWindow and RawSurface given an `ActiveEventLoop` and `WindowProperties`.
 /// For instance, implementation within `ApplicationHandler::resumed` may look like:
 /// ```rust
-/// //...
-/// fn resumed(&mut self, event_loop: &ActiveEventLoop) {
-///     (self.window, self.surface) = init(event_loop, &self.properties);
+/// use winit::application::ApplicationHandler;
+/// use winit::event::WindowEvent;
+/// use winit::event_loop::ActiveEventLoop;
+/// use winit::window::WindowId;
+///  
+///  
+/// use softbuffer_quickstart::{init, RawSurface, RawWindow, WindowProperties};
+///  
+/// struct MyWindow {
+///     window: RawWindow,
+///     surface: RawSurface
+/// }
+///  
+/// impl ApplicationHandler for MyWindow {
+///     /// `ApplicationHandler::resumed()` implementation here
+///     fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+///         (self.window, self.surface) = init(event_loop, &WindowProperties::default());
+///     }
+///  
+///     fn window_event(&mut self, event_loop: &ActiveEventLoop, window_id: WindowId, event: WindowEvent) {
+///         todo!()
+///     }
 /// }
-/// //...
 /// ```
 pub fn init(event_loop: &ActiveEventLoop, properties: &WindowProperties) -> (RawWindow, RawSurface) {
     let window = {
@@ -78,7 +96,7 @@ pub fn close(event_loop: &ActiveEventLoop, event: &WindowEvent) {
     }
 }
 
-/// Shorthand to listen for and handle WindowEvent::Resized by resizing a buffer
+/// Shorthand to listen for and handle WindowEvent::Resized by resizing a buffer (`RawSurface`)
 pub fn resize(event: &WindowEvent, surface: &mut RawSurface) {
     if let WindowEvent::Resized(size) = event {
         surface
@@ -92,7 +110,8 @@ pub fn resize(event: &WindowEvent, surface: &mut RawSurface) {
     }
 }
 
-/// Redraws a RawSurface. Call this on `Window::RedrawRequested`.
+/// Redraws a `RawSurface`. Call this on `WindowEvent::RedrawRequested` inside `ApplicationHandler::window_event`,
+/// right after you've drawn everything to the `RawSurface`.
 pub fn redraw(window: &mut RawWindow, surface: &mut RawSurface) {
     surface
         .as_mut()
@@ -104,7 +123,9 @@ pub fn redraw(window: &mut RawWindow, surface: &mut RawSurface) {
     window.as_ref().unwrap().request_redraw();
 }
 
-/// Gets a mutable reference to a buffer from a `RawSurface`
+/// Gets a mutable reference to a buffer from a `RawSurface`. Colors are `u32`s.
+/// Accessing an array might look like `softbuffer_quickstart::buffer_mut(&mut self.surface)[y * width + x] = 0xffffff`.
+/// Keep in mind you have to keep track of the buffer width yourself--the RawBuffer type can't do that.
 pub fn buffer_mut(surface: &mut RawSurface) -> softbuffer::Buffer<'_, Rc<Window>, Rc<Window>> {
     surface.as_mut().unwrap().buffer_mut().unwrap()
 }

src/sb_window.rs

@@ -9,7 +9,7 @@ use winit::event_loop::{ActiveEventLoop, ControlFlow, EventLoop};
 use winit::window::{Window, WindowId};
 use crate::{close, init, redraw, resize, run, RawSurface, RawWindow, WindowProperties};
 
-/// Wrapper for Softbuffer and a Winit window
+/// Wrapper for Softbuffer and a Winit window.
 pub struct SoftbufferWindow {
     window: RawWindow,
     surface: RawSurface,