Struct pixels::PixelsBuilder

pub struct PixelsBuilder<'req, 'dev, 'win, W: HasRawWindowHandle> { /* fields omitted */ }

A builder to help create customized pixel buffers.

Implementations

impl<'req, 'dev, 'win, W: HasRawWindowHandle> PixelsBuilder<'req, 'dev, 'win, W>

pub fn new(
    width: u32,
    height: u32,
    surface_texture: SurfaceTexture<'win, W>
) -> Self

Create a builder that can be finalized into a Pixels pixel buffer.

Examples

use pixels::wgpu::{PowerPreference, RequestAdapterOptions};

let mut pixels = PixelsBuilder::new(256, 240, surface_texture)
    .request_adapter_options(RequestAdapterOptions {
        power_preference: PowerPreference::HighPerformance,
        force_fallback_adapter: false,
        compatible_surface: None,
    })
    .enable_vsync(false)
    .build()?;

Panics

Panics when width or height are 0.

pub fn request_adapter_options(
    self,
    request_adapter_options: RequestAdapterOptions<'req>
) -> Self

Add options for requesting a wgpu::Adapter.

pub fn device_descriptor(
    self,
    device_descriptor: DeviceDescriptor<'dev>
) -> Self

Add options for requesting a wgpu::Device.

pub fn wgpu_backend(self, backend: Backends) -> Self

Set which backends wgpu will attempt to use.

The default value is PRIMARY, which enables the well supported backends for wgpu.

pub fn enable_vsync(self, enable_vsync: bool) -> Self

Enable or disable Vsync.

Vsync is enabled by default.

The wgpu present mode will be set to Fifo when Vsync is enabled, or Immediate when Vsync is disabled. To set the present mode to Mailbox or another value, use the PixelsBuilder::present_mode method.

pub fn present_mode(self, present_mode: PresentMode) -> Self

Set the wgpu present mode.

This differs from PixelsBuilder::enable_vsync by allowing the present mode to be set to any value.

pub fn texture_format(self, texture_format: TextureFormat) -> Self

Set the texture format.

The default value is Rgba8UnormSrgb, which is 4 unsigned bytes in RGBA order using the sRGB color space. This is typically what you want when you are working with color values from popular image editing tools or web apps.

This is the pixel format of the texture that most applications will interact with directly. The format influences the structure of byte data that is returned by Pixels::get_frame.

pub fn render_texture_format(self, texture_format: TextureFormat) -> Self

Set the render texture format.

The default value is chosen automatically by the surface (if it can) with a fallback to Bgra8UnormSrgb (which is 4 unsigned bytes in BGRA order using the sRGB color space). Setting this format correctly depends on the hardware/platform the pixel buffer is rendered to. The chosen format can be retrieved later with Pixels::render_texture_format.

This method controls the format of the surface frame buffer, which has strict texture format requirements. Applications will never interact directly with the pixel data of this texture, but a view is provided to the render_function closure by Pixels::render_with. The render texture can only be used as the final render target at the end of all post-processing shaders.

The ScalingRenderer also uses this format for its own render target. This is because it assumes the render target is always the surface current frame. This needs to be kept in mind when writing custom shaders for post-processing effects. There is a full example of a custom-shader available that demonstrates how to deal with this.

pub fn clear_color(self, color: Color) -> Self

Set the default clear color.

Allows customization of the background color and the border drawn for non-integer scale values.

use pixels::wgpu::Color;

// Set clear color to bright magenta.
let mut pixels = PixelsBuilder::new(320, 240, surface_texture)
    .clear_color(Color {
        r: 1.0,
        g: 0.0,
        b: 1.0,
        a: 1.0,
    })
    .build()?;

pub fn build(self) -> Result<Pixels, Error>

Create a pixel buffer from the options builder.

This method blocks the current thread, making it unusable on Web targets. Use PixelsBuilder::build_async for a non-blocking alternative.

Errors

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

pub async fn build_async(self) -> Result<Pixels, Error>

Create a pixel buffer from the options builder without blocking the current thread.

Examples

use pixels::wgpu::{Backends, DeviceDescriptor, Limits};

let mut pixels = PixelsBuilder::new(256, 240, surface_texture)
    .enable_vsync(false)
    .build_async()
    .await?;

Errors

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