pub struct GpuSurface { /* private fields */ }Expand description
A GPU presenter that draws every frame onto a wgpu surface.
The presenter renders the frame’s whole display list on every
GpuSurface::draw call, whatever its damage says: the GPU path redraws
the full frame. It owns the surface’s configuration and hands out surface
textures through GpuSurface::acquire, so a caller can time the wait
for a texture separately from the draw.
The surface is configured with the first format in the adapter’s capability order that the presenter supports, with FIFO present mode, a latency of two frames, and automatic alpha composition.
Implementations§
Source§impl GpuSurface
impl GpuSurface
Sourcepub fn new(
surface: Surface<'static>,
adapter: &Adapter,
device: Device,
queue: Queue,
width: u32,
height: u32,
) -> Result<GpuSurface, GpuError>
pub fn new( surface: Surface<'static>, adapter: &Adapter, device: Device, queue: Queue, width: u32, height: u32, ) -> Result<GpuSurface, GpuError>
Configures surface for adapter and returns a presenter for it.
The device’s texture limit must fit the surface; a larger surface
returns GpuError::SurfaceTooLarge instead of a renderer. Request
the device with device_limits: with the
default limits a large scene fails validation, which wgpu reports as
a panic.
§Errors
Returns GpuError::UnsupportedFormat when the surface offers no
format the presenter can render into, and
GpuError::SurfaceTooLarge when width or height exceeds the
device’s max_texture_dimension_2d limit.
§Panics
Panics when the device cannot create the vello pipelines, which means the device cannot run the shaders vello needs. That is a broken device state rather than input a caller can provoke.
Sourcepub fn resize(&mut self, width: u32, height: u32) -> Result<(), GpuError>
pub fn resize(&mut self, width: u32, height: u32) -> Result<(), GpuError>
Reconfigures the surface and the intermediate texture for a new size.
§Errors
Returns GpuError::SurfaceTooLarge when width or height
exceeds the device’s max_texture_dimension_2d limit. The presenter
keeps its old size in that case.
§Panics
Panics when width or height is zero, which cannot present: the
caller keeps the surface at its last size while the window has no
extent. Also panics, inside wgpu, when a texture from
GpuSurface::acquire is still alive, because a surface cannot be
reconfigured while one of its textures is out.
Sourcepub fn acquire(&mut self) -> Result<Option<SurfaceTexture>, GpuError>
pub fn acquire(&mut self) -> Result<Option<SurfaceTexture>, GpuError>
Waits for the next surface texture to draw onto.
Draw or drop the returned texture before the next
GpuSurface::resize, which cannot reconfigure the surface while it
is out. A surface that went out of date is reconfigured and asked once
more.
Returns Ok(None) when the frame must be skipped: the surface is
still out of date, is temporarily out of textures, or is covered.
Returns GpuError::SurfaceLost when the surface cannot present
anymore.
Sourcepub fn draw(
&mut self,
frame: &FrameOutput<'_>,
texture: SurfaceTexture,
) -> Result<(), GpuError>
pub fn draw( &mut self, frame: &FrameOutput<'_>, texture: SurfaceTexture, ) -> Result<(), GpuError>
Renders frame onto texture and presents it.
The whole display list is drawn and the whole surface is presented,
whatever FrameOutput::damage holds. The draw reaches the screen
asynchronously: the submission is queued when draw returns.
§Errors
Returns GpuError::Render when the device rejects the vello render,
which means it cannot run the shaders vello needs or has become
unusable. Nothing is presented then.