Struct pixels::Pixels

pub struct Pixels { /* fields omitted */ }

Represents a 2D pixel buffer with an explicit image resolution.

See PixelsBuilder for building a customized pixel buffer.

Implementations

impl Pixels

pub fn new(
    width: u32,
    height: u32,
    surface_texture: SurfaceTexture
) -> Result<Pixels, Error>

Create a pixel buffer instance with default options.

Examples

let mut pixels = Pixels::new(320, 240, surface_texture)?;

Errors

Returns an error when a wgpu::Adapter cannot be found.

Panics

Panics when width or height are 0.

pub fn resize(&mut self, width: u32, height: u32)

Resize the surface upon which the pixel buffer 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.

Call this method in response to a resize event from your window manager. The size expected is in physical pixel units.

pub fn render(&mut self) -> Result<(), Error>

Draw this pixel buffer to the configured SurfaceTexture.

Errors

Returns an error when wgpu::SwapChain::get_next_texture times out.

Example

let mut pixels = Pixels::new(320, 240, surface_texture)?;

// Clear the pixel buffer
let frame = pixels.get_frame();
for pixel in frame.chunks_exact_mut(4) {
    pixel[0] = 0x00; // R
    pixel[1] = 0x00; // G
    pixel[2] = 0x00; // B
    pixel[3] = 0xff; // A
}

// Draw it to the `SurfaceTexture`
pixels.render();

pub fn render_with<F>(&mut self, render_function: F) -> Result<(), Error> where
    F: FnOnce(&mut CommandEncoder, &TextureView, &ScalingRenderer), 

Draw this pixel buffer to the configured SurfaceTexture using a custom user-provided render function.

Provides access to a wgpu::CommandEncoder, a wgpu::TextureView from the swapchain which you can use to render to the screen, and the default ScalingRenderer.

Errors

Returns an error when wgpu::SwapChain::get_next_texture times out.

Example

let mut pixels = Pixels::new(320, 240, surface_texture)?;

// Clear the pixel buffer
let frame = pixels.get_frame();
for pixel in frame.chunks_exact_mut(4) {
    pixel[0] = 0x00; // R
    pixel[1] = 0x00; // G
    pixel[2] = 0x00; // B
    pixel[3] = 0xff; // A
}

// Draw it to the `SurfaceTexture`
pixels.render_with(|encoder, render_target, scaling_renderer| {
    scaling_renderer.render(encoder, render_target);
    // etc...
});

pub fn get_frame(&mut self) -> &mut [u8]

Get a mutable byte slice for the pixel buffer. The buffer is not cleared for you; it will retain the previous frame's contents until you clear it yourself.

pub fn window_pos_to_pixel(
    &self,
    physical_position: (f32, f32)
) -> Result<(usize, usize), (isize, isize)>

Calculate the pixel location from a physical location on the window, dealing with window resizing, scaling, and margins. Takes a physical position (x, y) within the window, and returns a pixel position (x, y).

The location must be given in physical units (for example, winit's PhysicalLocation)

If the given physical position is outside of the drawing area, this function returns an Err value with the pixel coordinates outside of the screen, using isize instead of usize.

const WIDTH:  u32 = 320;
const HEIGHT: u32 = 240;

let mut pixels = Pixels::new(WIDTH, HEIGHT, surface_texture)?;

// A cursor position in physical units
let cursor_position: (f32, f32) = winit::dpi::PhysicalPosition::new(0.0, 0.0).into();

// Convert it to a pixel location
let pixel_position: (usize, usize) = pixels.window_pos_to_pixel(cursor_position)
    // Clamp the output to within the screen
    .unwrap_or_else(|pos| pixels.clamp_pixel_pos(pos));

pub fn clamp_pixel_pos(&self, pos: (isize, isize)) -> (usize, usize)

Clamp a pixel position to the pixel buffer 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.

const WIDTH:  u32 = 320;
const HEIGHT: u32 = 240;

let mut pixels = Pixels::new(WIDTH, HEIGHT, surface_texture)?;

let pixel_pos = pixels.clamp_pixel_pos((-19, 20));
assert_eq!(pixel_pos, (0, 20));

let pixel_pos = pixels.clamp_pixel_pos((11, 3000));
assert_eq!(pixel_pos, (11, 239));

pub fn device(&self) -> &Device

Provides access to the internal wgpu::Device.

pub fn queue(&self) -> &Queue

Provides access to the internal wgpu::Queue.

pub fn texture(&self) -> &Texture

Provides access to the internal source wgpu::Texture.

This is the pre-scaled texture copied from the pixel buffer.

Trait Implementations

impl Debug for Pixels

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.