Struct pixels::PixelsBuilder

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

A builder to help create customized pixel buffers.

Implementations

impl<'req, 'dev, 'win, W: HasRawWindowHandle + HasRawDisplayHandle> 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 enables all backends, including the backends with “best effort” support in wgpu.

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

Enable or disable Vsync.

Vsync is enabled by default. It cannot be disabled on Web targets.

The wgpu present mode will be set to AutoVsync when Vsync is enabled, or AutoNoVsync 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::frame.

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

Set the render texture format.

This falls back on Pixels::surface_texture_format if not set.

The ScalingRenderer uses this format for its own render target. This is really only useful if you are running a custom shader pipeline and need different formats for the intermediary textures (such as Rgba16Float for HDR rendering). There is a full example of a custom-shader available that demonstrates how to deal with this.

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

Set the surface 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.

pub fn blend_state(self, blend_state: BlendState) -> Self

Set the blend state.

Allows customization of how to mix the new and existing pixels in a texture when rendering.

The default blend state is alpha blending with non-premultiplied alpha.

use pixels::wgpu::BlendState;

// Replace the old pixels with the new without mixing.
let mut pixels = PixelsBuilder::new(320, 240, surface_texture)
    .blend_state(wgpu::BlendState::REPLACE)
    .build()?;

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

Set the clear color.

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

The default value is pure black.

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.