Add fill-window example

README.md

@@ -30,6 +30,7 @@ The Minimum Supported Rust Version for `pixels` will always be made available in
 
 - [Conway's Game of Life](./examples/conway)
 - [Custom Shader](./examples/custom-shader)
+- [Fill arbitrary window sizes while maintaining the highest possible quality](./examples/fill-window)
 - [Dear ImGui example with `winit`](./examples/imgui-winit)
 - [Egui example with `winit`](./examples/minimal-egui)
 - [Minimal example for WebGL2](./examples/minimal-web)

examples/fill-window/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "fill-window"
+version = "0.1.0"
+authors = ["Jay Oster <jay@kodewerx.org>"]
+edition = "2021"
+publish = false
+
+[features]
+optimize = ["log/release_max_level_warn"]
+default = ["optimize"]
+
+[dependencies]
+bytemuck = "1.7"
+env_logger = "0.9"
+log = "0.4"
+pixels = { path = "../.." }
+ultraviolet = "0.8"
+winit = "0.26"
+winit_input_helper = "0.11"

examples/fill-window/README.md

@@ -0,0 +1,20 @@
+# Window-filling Example
+
+![Custom Shader Example](../../img/fill-window.png)
+
+## Running
+
+```bash
+cargo run --release --package fill-window
+```
+
+## About
+
+This example is based on `minimal-winit` and `custom-shader`. It adds a custom renderer that completely fills the screen while maintaining high quality.
+
+Filling the screen necessarily creates artifacts (aliasing) due to a mismatch between the number of pixels in the pixel buffer and the number of pixels on the screen. The custom renderer provided here counters this aliasing issue with a two-pass approach:
+
+1. First the pixel buffer is scaled with the default scaling renderer, which keeps sharp pixel edges by only scaling to integer ratios with nearest neighbor texture filtering.
+2. Then the custom renderer scales that result to the smallest non-integer multiple that will fill the screen without clipping, using bilinear texture filtering.
+
+This approach maintains the aspect ratio in the second pass by adding black "letterbox" or "pillarbox" borders as necessary. The two-pass method completely avoids pixel shimmering with single-pass nearest neighbor filtering, and also avoids blurring with single-pass bilinear filtering. The result has decent quality even when scaled up 100x.

examples/fill-window/shaders/fill.wgsl

@@ -0,0 +1,31 @@
+// Vertex shader bindings
+
+struct VertexOutput {
+    [[location(0)]] tex_coord: vec2<f32>;
+    [[builtin(position)]] position: vec4<f32>;
+};
+
+struct Locals {
+    transform: mat4x4<f32>;
+};
+[[group(0), binding(2)]] var<uniform> r_locals: Locals;
+
+[[stage(vertex)]]
+fn vs_main(
+    [[location(0)]] position: vec2<f32>,
+) -> VertexOutput {
+    var out: VertexOutput;
+    out.tex_coord = fma(position, vec2<f32>(0.5, -0.5), vec2<f32>(0.5, 0.5));
+    out.position = r_locals.transform * vec4<f32>(position, 0.0, 1.0);
+    return out;
+}
+
+// Fragment shader bindings
+
+[[group(0), binding(0)]] var r_tex_color: texture_2d<f32>;
+[[group(0), binding(1)]] var r_tex_sampler: sampler;
+
+[[stage(fragment)]]
+fn fs_main([[location(0)]] tex_coord: vec2<f32>) -> [[location(0)]] vec4<f32> {
+    return textureSample(r_tex_color, r_tex_sampler, tex_coord);
+}

examples/fill-window/src/main.rs

@@ -0,0 +1,143 @@
+#![deny(clippy::all)]
+#![forbid(unsafe_code)]
+
+use crate::renderers::FillRenderer;
+use log::error;
+use pixels::{Error, Pixels, SurfaceTexture};
+use winit::dpi::LogicalSize;
+use winit::event::{Event, VirtualKeyCode};
+use winit::event_loop::{ControlFlow, EventLoop};
+use winit::window::WindowBuilder;
+use winit_input_helper::WinitInputHelper;
+
+mod renderers;
+
+const WIDTH: u32 = 320;
+const HEIGHT: u32 = 240;
+const SCREEN_WIDTH: u32 = 1920;
+const SCREEN_HEIGHT: u32 = 1080;
+const BOX_SIZE: i16 = 64;
+
+/// Representation of the application state. In this example, a box will bounce around the screen.
+struct World {
+    box_x: i16,
+    box_y: i16,
+    velocity_x: i16,
+    velocity_y: i16,
+}
+
+fn main() -> Result<(), Error> {
+    env_logger::init();
+    let event_loop = EventLoop::new();
+    let mut input = WinitInputHelper::new();
+    let window = {
+        let size = LogicalSize::new(SCREEN_WIDTH as f64, SCREEN_HEIGHT as f64);
+        WindowBuilder::new()
+            .with_title("Fill Window")
+            .with_inner_size(size)
+            .with_min_inner_size(size)
+            .build(&event_loop)
+            .unwrap()
+    };
+
+    let mut pixels = {
+        let window_size = window.inner_size();
+        let surface_texture = SurfaceTexture::new(window_size.width, window_size.height, &window);
+        Pixels::new(WIDTH, HEIGHT, surface_texture)?
+    };
+    let mut world = World::new();
+    let mut fill_renderer = FillRenderer::new(&pixels, WIDTH, HEIGHT, SCREEN_WIDTH, SCREEN_HEIGHT);
+
+    event_loop.run(move |event, _, control_flow| {
+        // Draw the current frame
+        if let Event::RedrawRequested(_) = event {
+            world.draw(pixels.get_frame());
+
+            let render_result = pixels.render_with(|encoder, render_target, context| {
+                let fill_texture = fill_renderer.get_texture_view();
+                context.scaling_renderer.render(encoder, fill_texture);
+
+                fill_renderer.render(encoder, render_target);
+
+                Ok(())
+            });
+
+            if render_result
+                .map_err(|e| error!("pixels.render_with() failed: {}", e))
+                .is_err()
+            {
+                *control_flow = ControlFlow::Exit;
+                return;
+            }
+        }
+
+        // Handle input events
+        if input.update(&event) {
+            // Close events
+            if input.key_pressed(VirtualKeyCode::Escape) || input.quit() {
+                *control_flow = ControlFlow::Exit;
+                return;
+            }
+
+            // Resize the window
+            if let Some(size) = input.window_resized() {
+                pixels.resize_surface(size.width, size.height);
+
+                let clip_rect = pixels.context().scaling_renderer.clip_rect();
+                fill_renderer.resize(&pixels, clip_rect.2, clip_rect.3, size.width, size.height);
+            }
+
+            // Update internal state and request a redraw
+            world.update();
+            window.request_redraw();
+        }
+    });
+}
+
+impl World {
+    /// Create a new `World` instance that can draw a moving box.
+    fn new() -> Self {
+        Self {
+            box_x: 24,
+            box_y: 16,
+            velocity_x: 1,
+            velocity_y: 1,
+        }
+    }
+
+    /// Update the `World` internal state; bounce the box around the screen.
+    fn update(&mut self) {
+        if self.box_x <= 0 || self.box_x + BOX_SIZE > WIDTH as i16 {
+            self.velocity_x *= -1;
+        }
+        if self.box_y <= 0 || self.box_y + BOX_SIZE > HEIGHT as i16 {
+            self.velocity_y *= -1;
+        }
+
+        self.box_x += self.velocity_x;
+        self.box_y += self.velocity_y;
+    }
+
+    /// Draw the `World` state to the frame buffer.
+    ///
+    /// Assumes the default texture format: [`pixels::wgpu::TextureFormat::Rgba8UnormSrgb`]
+    fn draw(&self, frame: &mut [u8]) {
+        for (i, pixel) in frame.chunks_exact_mut(4).enumerate() {
+            let x = (i % WIDTH as usize) as i16;
+            let y = (i / WIDTH as usize) as i16;
+
+            let inside_the_box = x >= self.box_x
+                && x < self.box_x + BOX_SIZE
+                && y >= self.box_y
+                && y < self.box_y + BOX_SIZE;
+
+            let rgba = if inside_the_box {
+                [0x5e, 0x48, 0xe8, 0xff]
+            } else {
+                [0x48, 0xb2, 0xe8, 0xff]
+            };
+
+            pixel.copy_from_slice(&rgba);
+        }
+    }
+}