Struct pixels::Pixels [−][src]
pub struct Pixels { /* fields omitted */ }
Expand description
Represents a 2D pixel buffer with an explicit image resolution.
See PixelsBuilder
for building a customized pixel buffer.
Implementations
pub fn new<W: HasRawWindowHandle>(
width: u32,
height: u32,
surface_texture: SurfaceTexture<'_, W>
) -> Result<Self, Error>
pub fn new<W: HasRawWindowHandle>(
width: u32,
height: u32,
surface_texture: SurfaceTexture<'_, W>
) -> Result<Self, Error>
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.
This method blocks the current thread, making it unusable on Web targets. Use
Pixels::new_async
for a non-blocking alternative.
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 async fn new_async<W: HasRawWindowHandle>(
width: u32,
height: u32,
surface_texture: SurfaceTexture<'_, W>
) -> Result<Self, Error>
pub async fn new_async<W: HasRawWindowHandle>(
width: u32,
height: u32,
surface_texture: SurfaceTexture<'_, W>
) -> Result<Self, Error>
Asynchronously create a pixel buffer instance with default options.
See Pixels::new
for more information.
Examples
let mut pixels = Pixels::new_async(320, 240, surface_texture).await?;
Errors
Returns an error when a wgpu::Adapter
cannot be found.
Panics
Panics when width
or height
are 0.
Resize the pixel buffer and zero its contents.
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
.
Panics
Panics when width
or height
are 0.
Resize the surface upon which the pixel buffer texture is rendered.
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. Does nothing when width
or height
are 0.
Draw this pixel buffer to the configured SurfaceTexture
.
Errors
Returns an error when wgpu::Surface::get_current_texture
fails.
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>(&self, render_function: F) -> Result<(), Error> where
F: FnOnce(&mut CommandEncoder, &TextureView, &PixelsContext) -> Result<(), Box<dyn Error + Send + Sync + 'static>>,
pub fn render_with<F>(&self, render_function: F) -> Result<(), Error> where
F: FnOnce(&mut CommandEncoder, &TextureView, &PixelsContext) -> Result<(), Box<dyn Error + Send + Sync + 'static>>,
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 surface
which you can use to render to the screen, and a PixelsContext
with all of the internal
wgpu
context.
The render function must return a Result
. This allows fallible render functions to be
handled gracefully. The boxed Error
will be made available in the Error::UserDefined
variant returned by render_with()
.
Errors
Returns an error when either wgpu::Surface::get_current_texture
or the provided render
function fails.
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, context| {
context.scaling_renderer.render(encoder, render_target);
// etc...
Ok(())
})?;
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.
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.
use winit::dpi::PhysicalPosition;
let mut pixels = Pixels::new(320, 240, surface_texture)?;
// A cursor position in physical units
let cursor_position: (f32, f32) = 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));
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.
let mut pixels = Pixels::new(320, 240, 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));
Provides access to the internal wgpu::Device
.
Provides access to the internal wgpu::Queue
.
Provides access to the internal source wgpu::Texture
.
This is the pre-scaled texture copied from the pixel buffer.
Provides access to the internal PixelsContext
.
Get the render texture format.
This texture format may be chosen automatically by the surface. See
PixelsBuilder::render_texture_format
for more information.