docs: added most documentation

Wgpu Context now async + added docs

Author: pemattern

examples/demo/main.rs

@@ -0,0 +1,5 @@
+fn main() {
+    let _ = ratatui::init();
+
+    ratatui::restore();
+}

src/lib.rs

@@ -29,12 +29,25 @@
 
 mod wgpu_context;
 
+use pollster::FutureExt;
 use ratatui::layout::{Position, Rect};
 use ratatui::style::{Color, Style};
 use ratatui::widgets::StatefulWidget;
 
 use crate::wgpu_context::WgpuContext;
 
+/// `ShaderCanvas` is a unit struct which implements the `StatefulWidget` trait from Ratatui.
+/// It holds the logic for applying the result of GPU computation to the `Buffer` struct which
+/// Ratatui uses to display to the terminal.
+///
+/// ```rust,no_run
+/// let mut terminal = ratatui::init();
+/// let mut state = tui_shader::ShaderCanvasState::default();
+/// terminal.draw(|frame| {
+///     frame.render_stateful_widget(tui_shader::ShaderCanvas, frame.area(), &mut state);
+/// }).unwrap();
+/// ratatui::restore();
+/// ```
 pub struct ShaderCanvas;
 
 impl StatefulWidget for ShaderCanvas {
@@ -43,22 +56,23 @@ impl StatefulWidget for ShaderCanvas {
         let width = area.width;
         let height = area.height;
 
-        let raw_buffer = state.wgpu_context.execute(width, height);
+        let raw_buffer = state.wgpu_context.execute(width, height).block_on();
 
         for y in 0..height {
             for x in 0..width {
                 let index = (y * (width + WgpuContext::row_padding(width)) + x) as usize;
-                let pixel = raw_buffer[index];
+                let value = raw_buffer[index];
+                let position = (x, y);
                 let character = match state.options.character_rule {
                     CharacterRule::Always(character) => character,
-                    CharacterRule::Map(map) => map(pixel.into()),
+                    CharacterRule::Map(map) => map(Sample::new(value, position)),
                 };
-                let color = Color::Rgb(pixel[0], pixel[1], pixel[2]);
+                let color = Color::Rgb(value[0], value[1], value[2]);
                 let style = match state.options.style_rule {
                     StyleRule::ColorFg => Style::new().fg(color),
                     StyleRule::ColorBg => Style::new().bg(color),
                     StyleRule::ColorFgAndBg => Style::new().fg(color).bg(color),
-                    StyleRule::Map(map) => map(pixel.into()),
+                    StyleRule::Map(map) => map(Sample::new(value, position)),
                 };
                 let cell = buf.cell_mut(Position::new(x, y)).unwrap();
                 cell.set_style(style);
@@ -68,25 +82,45 @@ impl StatefulWidget for ShaderCanvas {
     }
 }
 
+/// State struct for [`ShaderCanvas`].
+///
+/// This struct holds values that may want to be altered at runtime.
 #[derive(Debug, Default, Clone, Eq, PartialEq)]
 pub struct ShaderCanvasState {
     wgpu_context: WgpuContext,
     options: ShaderCanvasOptions,
 }
 
 impl ShaderCanvasState {
+    /// Creates a new [`ShaderCanvasState`] by passing in the path to the desired fragment shader.
+    /// The shader must be written in WGSL. The [`ShaderCanvasOptions`] will be set to
+    /// [`Self::default()`].
     pub fn new(path_to_fragment_shader: &str) -> Self {
         Self::new_with_options(path_to_fragment_shader, ShaderCanvasOptions::default())
     }
 
+    /// Creates a new [`ShaderCanvasState`] by passing in the path to the desired fragment shader.
+    /// The shader must be written in WGSL. The [`ShaderCanvasOptions`] can be customized.
+    ///
+    /// ```rust,no_run
+    /// let state = tui_shader::ShaderCanvasState::new_with_options("path/to/shader.wgsl",
+    ///     tui_shader::ShaderCanvasOptions {
+    ///         style_rule: tui_shader::StyleRule::ColorFg,
+    ///         entry_point: String::from("fragment"),
+    ///         ..Default::default()
+    ///     }
+    /// );
+    /// ```
     pub fn new_with_options(path_to_fragment_shader: &str, options: ShaderCanvasOptions) -> Self {
         Self {
-            wgpu_context: WgpuContext::new(path_to_fragment_shader, &options.entry_point),
+            wgpu_context: WgpuContext::new(path_to_fragment_shader, &options.entry_point)
+                .block_on(),
             options,
         }
     }
 }
 
+/// Contains options to customize the behaviour of the ShaderCanvas.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct ShaderCanvasOptions {
     pub character_rule: CharacterRule,
@@ -104,6 +138,11 @@ impl Default for ShaderCanvasOptions {
     }
 }
 
+/// Determines which character to use for Cell.
+/// [`CharacterRule::Always`] takes a single char and applies it to all Cells in the [`ShaderCanvas`].
+/// [`CharacterRule::Map`] takes a function as an argument and allows you to map the input [`Sample`] to
+/// a character. For example, one might use the transparency value from the shader ([Sample::a]) and map
+/// it to a different character depending on the value.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum CharacterRule {
     Always(char),
@@ -127,9 +166,14 @@ pub enum StyleRule {
 
 pub struct Sample {
     value: [u8; 4],
+    position: (u16, u16),
 }
 
 impl Sample {
+    fn new(value: [u8; 4], position: (u16, u16)) -> Self {
+        Self { value, position }
+    }
+
     pub fn r(&self) -> u8 {
         self.value[0]
     }
@@ -145,11 +189,13 @@ impl Sample {
     pub fn a(&self) -> u8 {
         self.value[3]
     }
-}
 
-impl From<[u8; 4]> for Sample {
-    fn from(value: [u8; 4]) -> Self {
-        Self { value }
+    pub fn x(&self) -> u16 {
+        self.position.0
+    }
+
+    pub fn y(&self) -> u16 {
+        self.position.1
     }
 }
 
@@ -160,7 +206,7 @@ mod tests {
     #[test]
     fn default_wgsl_context() {
         let mut context = WgpuContext::default();
-        let raw_buffer = context.execute(64, 64);
+        let raw_buffer = context.execute(64, 64).block_on();
         assert!(raw_buffer.iter().all(|pixel| pixel == &[255, 0, 255, 255]));
     }
 }

src/wgpu_context.rs

@@ -24,12 +24,12 @@ pub struct WgpuContext {
 }
 
 impl WgpuContext {
-    pub fn new(path_to_fragment_shader: &str, entry_point: &str) -> Self {
+    pub async fn new(path_to_fragment_shader: &str, entry_point: &str) -> Self {
         let instance = wgpu::Instance::default();
 
         let adapter = instance
             .request_adapter(&wgpu::RequestAdapterOptions::default())
-            .block_on()
+            .await
             .unwrap();
 
         let (device, queue) = adapter
@@ -42,7 +42,7 @@ impl WgpuContext {
                 },
                 None,
             )
-            .block_on()
+            .await
             .unwrap();
 
         let vertex_shader =
@@ -188,7 +188,7 @@ impl WgpuContext {
         (bytes_per_row - row_size) / 4
     }
 
-    pub fn execute(&mut self, width: u16, height: u16) -> Vec<[u8; 4]> {
+    pub async fn execute(&mut self, width: u16, height: u16) -> Vec<[u8; 4]> {
         if Self::bytes_per_row(width) != Self::bytes_per_row(self.width) || height != self.height {
             self.texture = Self::create_texture(&self.device, width.into(), height.into());
             self.output_buffer = Self::create_buffer(&self.device, width.into(), height.into());
@@ -259,7 +259,7 @@ impl WgpuContext {
         let (sender, receiver) = flume::bounded(1);
         buffer_slice.map_async(wgpu::MapMode::Read, move |r| sender.send(r).unwrap());
         self.device.poll(wgpu::Maintain::wait()).panic_on_timeout();
-        receiver.recv_async().block_on().unwrap().unwrap();
+        receiver.recv_async().await.unwrap().unwrap();
         let slice: Vec<[u8; 4]>;
         {
             let view = buffer_slice.get_mapped_range();
@@ -272,6 +272,6 @@ impl WgpuContext {
 
 impl Default for WgpuContext {
     fn default() -> Self {
-        Self::new("src/shaders/default_fragment.wgsl", "magenta")
+        Self::new("src/shaders/default_fragment.wgsl", "magenta").block_on()
     }
 }