Rename resize to resize_surface (#149)

- Also cleanup documentation.
- Workaround FLTK window resize issues by disabling resizability.

examples/conway/src/main.rs

@@ -114,7 +114,7 @@ fn main() -> Result<(), Error> {
             }
             // Resize the window
             if let Some(size) = input.window_resized() {
-                pixels.resize(size.width, size.height);
+                pixels.resize_surface(size.width, size.height);
             }
             if !paused || input.key_pressed(VirtualKeyCode::Space) {
                 life.update();

examples/custom-shader/src/main.rs

@@ -81,7 +81,7 @@ fn main() -> Result<(), Error> {
 
             // Resize the window
             if let Some(size) = input.window_resized() {
-                pixels.resize(size.width, size.height);
+                pixels.resize_surface(size.width, size.height);
             }
 
             // Update internal state and request a redraw

examples/egui-winit/src/main.rs

@@ -100,7 +100,7 @@ fn main() -> Result<(), Error> {
 
             // Resize the window
             if let Some(size) = input.window_resized() {
-                pixels.resize(size.width, size.height);
+                pixels.resize_surface(size.width, size.height);
                 gui.resize(size.width, size.height);
             }
 

examples/imgui-winit/src/main.rs

@@ -101,7 +101,7 @@ fn main() -> Result<(), Error> {
             // Resize the window
             if let Some(size) = input.window_resized() {
                 // Resize the surface texture
-                pixels.resize(size.width, size.height);
+                pixels.resize_surface(size.width, size.height);
 
                 // Resize the world
                 let LogicalSize { width, height } = size.to_logical(scale_factor);

examples/invaders/src/main.rs

@@ -103,7 +103,7 @@ fn main() -> Result<(), Error> {
 
             // Resize the window
             if let Some(size) = input.window_resized() {
-                pixels.resize(size.width, size.height);
+                pixels.resize_surface(size.width, size.height);
             }
 
             // Get a new delta time.

examples/minimal-fltk/src/main.rs

@@ -27,7 +27,6 @@ fn main() -> Result<(), Error> {
         .with_size(WIDTH as i32, HEIGHT as i32)
         .with_label("Hello Pixels");
     win.end();
-    win.make_resizable(true);
     win.show();
 
     let mut pixels = {

examples/minimal-sdl2/src/main.rs

@@ -44,7 +44,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             Some(Event::Window(WindowEvent {
                 event: WindowEventEnum::Resized { w, h },
                 ..
-            })) => pixels.resize(w as u32, h as u32),
+            })) => pixels.resize_surface(w as u32, h as u32),
 
             _ => (),
         }

examples/minimal-winit/src/main.rs

@@ -66,7 +66,7 @@ fn main() -> Result<(), Error> {
 
             // Resize the window
             if let Some(size) = input.window_resized() {
-                pixels.resize(size.width, size.height);
+                pixels.resize_surface(size.width, size.height);
             }
 
             // Update internal state and request a redraw

examples/raqote-winit/src/main.rs

@@ -76,7 +76,7 @@ fn main() -> Result<(), Error> {
 
             // Resize the window
             if let Some(size) = input.window_resized() {
-                pixels.resize(size.width, size.height);
+                pixels.resize_surface(size.width, size.height);
             }
 
             // Update internal state and request a redraw

src/lib.rs

@@ -158,6 +158,14 @@ impl<'win, W: HasRawWindowHandle> SurfaceTexture<'win, W> {
 impl Pixels {
     /// Create a pixel buffer instance with default options.
     ///
+    /// Any ratio differences between the pixel buffer texture size and surface texture size will
+    /// result in a border being added around the pixel buffer texture to maintain an integer
+    /// scaling ratio.
+    ///
+    /// For instance, a pixel buffer with `320x240` can be scaled to a surface texture with sizes
+    /// `320x240`, `640x480`, `960x720`, etc. without adding a border because these are exactly
+    /// 1x, 2x, and 3x scales, respectively.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -183,7 +191,17 @@ impl Pixels {
         PixelsBuilder::new(width, height, surface_texture).build()
     }
 
-    /// Resize the pixel buffer, this doesn't resize the surface upon which the pixel buffer is rendered.
+    /// Resize the pixel buffer.
+    ///
+    /// This does not resize the surface upon which the pixel buffer texture is rendered. Use
+    /// [`Pixels::resize_surface`] to change the size of the surface texture.
+    ///
+    /// The pixel buffer will be fit onto the surface texture as best as possible by scaling to the
+    /// nearest integer, e.g. 2x, 3x, 4x, etc. A border will be added around the pixel buffer
+    /// texture for non-integer scaling ratios.
+    ///
+    /// Call this method to change the virtual screen resolution. E.g. when you want your pixel
+    /// buffer to be resized from `640x480` to `800x600`.
     pub fn resize_buffer(&mut self, width: u32, height: u32) {
         // Recreate the backing texture
         let (scaling_matrix_inverse, texture_extent, texture, scaling_renderer, pixels_buffer_size) =
@@ -208,14 +226,18 @@ impl Pixels {
             .resize_with(pixels_buffer_size, Default::default);
     }
 
-    /// Resize the surface upon which the pixel buffer is rendered.
+    /// Resize the surface upon which the pixel buffer texture is rendered.
     ///
-    /// This does not resize the pixel buffer. The pixel buffer will be fit onto the surface as
-    /// best as possible by scaling to the nearest integer, e.g. 2x, 3x, 4x, etc.
+    /// This does not resize the pixel buffer. Use [`Pixels::resize_buffer`] to change the size of
+    /// the pixel buffer.
+    ///
+    /// The pixel buffer texture will be fit onto the surface texture as best as possible by scaling
+    /// to the nearest integer, e.g. 2x, 3x, 4x, etc. A border will be added around the pixel buffer
+    /// texture for non-integer scaling ratios.
     ///
     /// Call this method in response to a resize event from your window manager. The size expected
     /// is in physical pixel units.
-    pub fn resize(&mut self, width: u32, height: u32) {
+    pub fn resize_surface(&mut self, width: u32, height: u32) {
         // Update SurfaceTexture dimensions
         self.surface_size.width = width;
         self.surface_size.height = height;
@@ -312,7 +334,6 @@ impl Pixels {
     where
         F: FnOnce(&mut wgpu::CommandEncoder, &wgpu::TextureView, &PixelsContext),
     {
-        // TODO: Center frame buffer in surface
         let frame = self
             .context
             .swap_chain
@@ -359,7 +380,9 @@ impl Pixels {
         Ok(())
     }
 
-    // Re-create the swap chain with its own values
+    /// Recreate the swap chain.
+    ///
+    /// Call this when the surface or presentation mode needs to be changed.
     pub(crate) fn recreate_swap_chain(&mut self) {
         self.context.swap_chain = builder::create_swap_chain(
             &mut self.context.device,
@@ -441,7 +464,7 @@ impl Pixels {
         }
     }
 
-    /// Clamp a pixel position to the pixel buffer size.
+    /// Clamp a pixel position to the pixel buffer texture size.
     ///
     /// This can be used to clamp the `Err` value returned by [`Pixels::window_pos_to_pixel`]
     /// to a position clamped within the drawing area.