Struct Renderer 

pub struct Renderer {
    pub clear_color: Color,
    /* private fields */
}

One window’s renderer: its surface, the pipelines and a GPU copy of the core’s glyph atlas.

Open one per window with Renderer::new (first window, on a device of its own) or Renderer::new_in (another window on a shared Gpu). Each frame, hand Renderer::render the display list and atlas from Core::output; call Renderer::resize when the window changes size. The crate root has the whole sequence.

Fields

clear_color: Color

The color a frame is cleared to before anything is drawn.

A runner usually sets it to the theme’s background each frame. It is written straight through: the renderer asks for a non-sRGB surface, so each component is the byte it lands as, the same way a quad’s color is.

Implementations

impl Renderer

pub async fn new( target: impl Into<SurfaceTarget<'static>>, width: u32, height: u32, ) -> Result<Renderer, Box<dyn Error>>

A renderer for one window, on a device of its own.

width and height are the window’s size in physical pixels. Fails when no adapter can present to target or the surface cannot be configured. Use Renderer::new_in for every window after the first, so they share the device.

pub async fn new_with( target: impl Into<SurfaceTarget<'static>>, width: u32, height: u32, options: GpuOptions, ) -> Result<Renderer, Box<dyn Error>>

Renderer::new on a device opened with options — what every window on it must be able to do (GpuOptions) — and, under GpuOptions::transparent, this window’s surface presented with alpha where it can be (Renderer::transparent).

pub fn transparent(&self) -> bool

Whether the surface is presented with alpha, so what is behind the window shows where a frame paints nothing and through a colour with alpha (Renderer::new_with, Renderer::new_in_with). The frame is premultiplied, which is what every quad and glyph already blends to; clear it to a transparent Renderer::clear_color for the window to show through.

pub fn new_in( gpu: &Gpu, target: impl Into<SurfaceTarget<'static>>, width: u32, height: u32, ) -> Result<Renderer, Box<dyn Error>>

A renderer for another window on an existing device, the one every window of the app shares. Get gpu from the first renderer’s Renderer::gpu.

pub fn new_in_with( gpu: &Gpu, target: impl Into<SurfaceTarget<'static>>, width: u32, height: u32, transparent: bool, ) -> Result<Renderer, Box<dyn Error>>

Renderer::new_in for a window whose surface is presented with alpha (transparent, backlog F126). Decided here, once, and not by a reconfigure: a D3D12 swapchain keeps the alpha mode it was made with, and resizing it later changes nothing — measured on Windows 11, where a surface reconfigured to premultiplied after it was made opaque went on compositing over black. Where the surface cannot take alpha — a D3D12 device not opened with GpuOptions::transparent, a Vulkan or GL surface that offers only opaque — it is opaque, and Renderer::transparent says so.

pub fn gpu(&self) -> &Gpu

The device this renderer draws with, to open another window on.

pub fn set_frame_latency(&mut self, frames: u32)

Sets how many frames may be queued ahead of the one on screen (at least one; see DEFAULT_FRAME_LATENCY). Reconfigures the surface when the value changes.

pub fn frame_latency(&self) -> u32

The frame latency the surface is configured with.

pub fn set_ground(&mut self, rgba: &[u8], width: u32, height: u32)

Draws rgba (width by height pixels, four bytes each, row by row from the top left, the bytes the surface takes as they are) over the clear and under everything a frame draws, opaque, stretched across the viewport and sampled with linear filtering — so a small picture reads as a soft one. What a runner draws as a window’s ground where the OS has no material to put behind it: the wallpaper, scaled down and blurred once (backlog F126). Which part of the picture shows is Renderer::set_ground_uv; all of it until that is called. A degenerate size, or pixels that are not that size, clear it.

pub fn set_ground_uv(&mut self, uv: [f32; 4])

Which part of the ground shows across the viewport: [u0, v0, u1, v1] in the picture’s own 0..1 coordinates, the top-left corner first. Outside 0..1 the picture’s edge is stretched. Nothing without a ground.

pub fn clear_ground(&mut self)

Takes the ground away (Renderer::set_ground).

pub fn has_ground(&self) -> bool

Whether a ground is drawn under the frame.

pub fn subpixel_text(&self) -> bool

Whether this device can draw LCD subpixel glyphs (QuadKind::GlyphSubpixel) as intended.

Pass it to Core::set_subpixel_text once after opening the renderer; when it is false the core keeps rasterizing grayscale masks, which every device blends correctly.

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

Reconfigures the swapchain for a new window size, in physical pixels.

The size is clamped to at least 1 (a minimized window reports zero, and a zero-sized surface is a validation error) and to the device’s largest texture (Windows hands out nonsense sizes mid-resize, and configuring past the limit panics inside wgpu). A clamped frame is one wrong picture; the next real size fixes it.

pub fn render( &mut self, dl: &DisplayList, atlas: &mut GlyphAtlas, ) -> Result<RenderReport, RenderError>

Draws one frame and presents it.

Uploads the atlas when it changed since the last frame (and clears its dirty flag), writes the list’s quads to the instance buffer, draws them over Renderer::clear_color in one render pass, and presents. Acquiring the swapchain image blocks while vsync holds the frame back; that time comes back as RenderReport::vsync_wait_ms so a runner can tell pacing from work.

Fails without presenting when the surface or the device cannot take the frame; each RenderError says what to do next.