diff --git a/examples/conway/src/main.rs b/examples/conway/src/main.rs index ab4b366..1e89866 100644 --- a/examples/conway/src/main.rs +++ b/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(); diff --git a/examples/custom-shader/src/main.rs b/examples/custom-shader/src/main.rs index 34cb2ec..a0164bc 100644 --- a/examples/custom-shader/src/main.rs +++ b/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 diff --git a/examples/egui-winit/src/main.rs b/examples/egui-winit/src/main.rs index 08251a5..eefaf82 100644 --- a/examples/egui-winit/src/main.rs +++ b/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); } diff --git a/examples/imgui-winit/src/main.rs b/examples/imgui-winit/src/main.rs index e5036ab..068110a 100644 --- a/examples/imgui-winit/src/main.rs +++ b/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); diff --git a/examples/invaders/src/main.rs b/examples/invaders/src/main.rs index 263c252..895fce4 100644 --- a/examples/invaders/src/main.rs +++ b/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. diff --git a/examples/minimal-fltk/src/main.rs b/examples/minimal-fltk/src/main.rs index 87a4ffa..783bc7b 100644 --- a/examples/minimal-fltk/src/main.rs +++ b/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 = { diff --git a/examples/minimal-sdl2/src/main.rs b/examples/minimal-sdl2/src/main.rs index f244dd6..e12716f 100644 --- a/examples/minimal-sdl2/src/main.rs +++ b/examples/minimal-sdl2/src/main.rs @@ -44,7 +44,7 @@ fn main() -> Result<(), Box> { 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), _ => (), } diff --git a/examples/minimal-winit/src/main.rs b/examples/minimal-winit/src/main.rs index 799ba30..a48e7d0 100644 --- a/examples/minimal-winit/src/main.rs +++ b/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 diff --git a/examples/raqote-winit/src/main.rs b/examples/raqote-winit/src/main.rs index 298697e..83c9f2b 100644 --- a/examples/raqote-winit/src/main.rs +++ b/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 diff --git a/src/lib.rs b/src/lib.rs index b860a24..95d3f03 100644 --- a/src/lib.rs +++ b/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.