API reference

aster_ui::accel

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Optional frame accelerator hook (experimental, unstable).

A Renderer draws every frame on the CPU unless an accelerator is installed with Renderer::set_accelerator. Nothing in this crate implements [RasterAccelerator]; the hook does nothing until a plugin (for example the separate gpu/ workspace at the repository root) registers one, so the default build draws exactly as before and has no graphics API dependency.

When one is installed, a full render (first frame, resize, theme switch, large damage and, if [RasterAccelerator::takes_overlay_frames] says so, full-screen overlay fades) is offered to it after the usual full-scene preflight. The accelerator sees the frame as an ordered list of [AccelItem]s: rectangle fills it may draw itself, and everything else as opaque items it can ask the CPU to rasterise into a small transparent tile ([AccelFrame::rasterize]) and then composite. Its result is written into a private staging plane and becomes the frame only when it returns Ok; on any error the CPU renderer draws the frame instead, so no failed or partial candidate frame is ever published.

The offer happens on the renderer's command path. A scene whose commands are all plain source-over fills is drawn from the compiled fill stream instead, and that frame stays with the CPU.

The accelerator's pixels are not the CPU's byte for byte. Byte-exact references (snapshot tests, headless rendering) must not install one.

Structs

structaster_ui::accel::AccelError

pub struct AccelError { /* see fields */ }

Why an accelerator declined or failed a frame. The CPU draws the frame instead.

Methods

  • fn new(message: impl Into<String>) -> Self
  • fn message(&self) -> &str

Trait implementations: Clone, Debug, Display, Eq, Error, From<Error>, PartialEq, StructuralPartialEq

structaster_ui::accel::AccelFill

pub struct AccelFill { /* see fields */ }

A rounded-rectangle fill in device pixels ([x, y, width, height]). Coverage follows the CPU rule: per pixel centre, horizontal edge coverage on rows inset by the corner circle.

Public fields

fieldtype
rect[f32; 4]
clip[f32; 4]Device clip rectangle (the whole output when the fill has none).
radiusf32Corner radius in device pixels, not yet limited to half the shorter side.
paintAccelPaint
blendBlendMode

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_ui::accel::AccelFrame

pub struct AccelFrame<'a> { /* see fields */ }

One frame offered to an accelerator: its output, clear colour and ordered items.

Methods

  • fn output(&self) -> Output
  • fn size(&self) -> [u32; 2] — Device size [width, height].
  • fn clear(&self) -> [u8; 4] — The clear colour every pixel starts as (sRGB bytes, straight alpha).
  • fn len(&self) -> usize
  • fn is_empty(&self) -> bool
  • fn item(&self, i: usize) -> AccelItem
  • fn direct_image(&self, i: usize) -> Option<&ImageResource> — Borrow an existing full-output image for direct GPU upload instead of CPU tile painting.
  • fn rasterized(&self) -> u64 — Number of tiles [AccelFrame::rasterize] has drawn for this frame.
  • fn rasterize(&mut self, i: usize, tile: &mut Vec<u8>) -> Result<[u32; 2], AccelError> — Rasterise item i on the CPU into tile: its device box (device_box of the item) as a tightly packed straight-alpha RGBA8 image, painted with its own blend mode over transparent pixels, so compositing the tile with that mode over the frame draws the item.
  • fn rasterize_many(&mut self, picks: &[usize], tiles: &mut Vec<Vec<u8>>) -> Result<Vec<[u32; 2]>, AccelError> — [AccelFrame::rasterize] for several items at once (tiles[k] receives item picks[k]), spread over the renderer's band workers when that pays off. The pixels do not depend on how the work was split. Returns each tile's [width, height].

structaster_ui::accel::AccelItem

pub struct AccelItem { /* see fields */ }

Public fields

fieldtype
kindAccelItemKind
device_box[u32; 4]Conservative integer device box [x0, y0, x1, y1] of the item's ink, inside the output.
blendBlendMode
keyOption<u64>Content key of the tile [AccelFrame::rasterize] returns, or None when it must not be cached. Equal keys within one output scale and colour mode give equal tile pixels, placed at the box's own origin (a command moved by whole device pixels keeps its key).

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

Enums

enumaster_ui::accel::AccelItemKind

pub enum AccelItemKind { Fill, Raster }

One frame item, in paint order.

Variants

  • Fill — Drawable natively; [AccelFrame::rasterize] works for it too.
  • Raster — An image, effect, vector or text command: rasterise it on the CPU into a tile.

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

enumaster_ui::accel::AccelPaint

pub enum AccelPaint { Solid, Linear }

Paint of an [AccelFill]; colours are sRGB bytes with straight alpha.

Variants

  • Solid
  • Linear — Linear gradient across the rectangle (left to right when horizontal, else top to bottom).

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

Traits

traitaster_ui::accel::RasterAccelerator

pub trait RasterAccelerator

A frame renderer that may replace the CPU rasteriser for full renders. Send so that installing one does not change the thread affinity of Renderer, which is bound to its owner thread by its surface pool.

Required and provided methods

  • fn render_frame(&mut self, frame: &mut AccelFrame<'_>, out: &mut [u8]) -> Result<(), AccelError> — Draw the whole frame into out: tightly packed RGBA8 sRGB, straight alpha, top-left origin, width * height * 4 bytes (already sized). Return Ok only when every pixel was written. Any Err (no device, device lost, out of memory, unsupported item) makes the CPU renderer draw this frame; out is then discarded.
  • fn takes_overlay_frames(&self) -> bool — Whether frames the CPU would draw as a retained base layer plus a repainted full-screen overlay (a fading scrim and dialog) should be drawn by the accelerator as full frames.
  • fn is_available(&self) -> bool — false once the accelerator has given up for the session (for example after a lost device): frames then go straight to the CPU without being offered.