Struct Surface 

pub struct Surface<M: SurfaceModel> { /* private fields */ }

A surface in model M (Cells or Pixels). See the module docs.

Implementations

impl Surface<Pixels>

pub fn blit_clipped( &mut self, x: i32, y: i32, image: Image<'_>, clip: Area, blend: bool, )

Draws image with its top-left corner at (x, y), clipped to clip and to the surface: only pixels inside both are written and marked dirty, so a sprite drawn into a viewport never spills out of it. With blend each pixel is drawn over what is there with its alpha; without, it replaces it. A short rgba draws the rows it holds.

pub fn fill_rect_at(&mut self, x: f32, y: f32, w: f32, h: f32, colour: Rgba)

A rectangle at a fractional position and size, its edges antialiased: a paddle or a ball that moves by less than a pixel per frame moves smoothly.

pub fn label_scaled( &mut self, x: i32, y: i32, text: &str, colour: Rgba, scale: u32, ) -> u32

Text in the built-in 5x7 font at an integer scale (1 is 5x7 pixels per glyph). Returns the pixels advanced.

impl Surface<Cells>

pub fn put(&mut self, x: u32, y: u32, character: char, style: Style) -> u32

Writes one character at (x, y). Returns the columns it took: 1, 2 for a wide character, 0 when nothing was written (out of bounds, or a character a cell never shows). A wide character that does not fit before the right edge leaves one empty cell instead (the viewer would drop it).

pub fn text(&mut self, x: u32, y: u32, text: &str, style: Style) -> u32

Writes text from (x, y) along one row, grapheme by grapheme, clipped at the right edge. Returns the columns written. Each grapheme shows as its first character (see the module docs).

Examples found in repository

examples/together_ui.rs (line 57)

    fn paint(&mut self) {
        let (cols, _) = self.card.size();
        self.card.clear();
        let line = format!("{} · {} builds", self.status.state, self.status.builds);
        self.card.text(0, 0, &line, Style::fg(Colour::FG));
        let hint = "rebuild";
        let x = cols.saturating_sub(hint.len() as u32);
        self.card
            .text(x, 0, hint, Style::fg(Colour::ACCENT).underline());
        let _ = self.card.commit();
    }

examples/clock_card.rs (line 43)

    fn frame(&mut self, frame: &Frame) {
        let second = frame.now_ms() / 1000;
        if self.shown != Some(second) {
            self.shown = Some(second);
            let (cols, _) = self.card.size();
            let time = format!(
                "{:02}:{:02}:{:02}",
                second / 3600 % 24,
                second / 60 % 60,
                second % 60
            );
            self.card.text(0, 0, &time, Style::fg(Colour::FG).bold());
            let fraction = (second % 60) as f32 / 60.0;
            let track = Style::fg(Colour::RECEDE_FG);
            self.card.bar(
                Area::new(0, 1, cols, 1),
                fraction,
                Style::fg(Colour::ACCENT),
                track,
            );
            // Publishes only the cells that changed.
            let _ = self.card.commit();
        }
        // The next second boundary: an idle viewer wakes once a second.
        frame.wake_at((second + 1) * 1000);
    }

pub fn fill(&mut self, rect: Rect, character: char, style: Style)

Fills rect with character in style (clipped).

pub fn clear(&mut self)

Empties every cell (theme text on a transparent background). The whole surface is dirty; the previous frame is not copied forward.

Examples found in repository

examples/together_ui.rs (line 55)

    fn paint(&mut self) {
        let (cols, _) = self.card.size();
        self.card.clear();
        let line = format!("{} · {} builds", self.status.state, self.status.builds);
        self.card.text(0, 0, &line, Style::fg(Colour::FG));
        let hint = "rebuild";
        let x = cols.saturating_sub(hint.len() as u32);
        self.card
            .text(x, 0, hint, Style::fg(Colour::ACCENT).underline());
        let _ = self.card.commit();
    }

pub fn clear_with(&mut self, style: Style)

Empties every cell with style (its background shows).

pub fn cell(&self, x: u32, y: u32) -> Option<Cell>

The cell at (x, y) as it will be committed next.

pub fn row_text(&self, y: u32) -> String

One row as text: each cell’s character, a space for an empty cell, nothing for the right half of a wide character. For tests.

impl Surface<Pixels>

pub fn set_pixel(&mut self, x: u32, y: u32, colour: Rgba)

Sets one pixel (no blending). Outside the surface nothing happens.

pub fn blend_pixel(&mut self, x: i32, y: i32, colour: Rgba)

Draws colour over one pixel with its alpha.

pub fn pixel(&self, x: u32, y: u32) -> Option<Rgba>

The pixel at (x, y) as it will be committed next.

pub fn clear(&mut self, colour: Rgba)

Fills the whole surface with colour. The previous frame is not copied forward.

Examples found in repository

examples/shapes_stage.rs (line 39)

    fn frame(&mut self, frame: &Frame) {
        let (w, h) = self.stage.size();
        if w == 0 || h == 0 {
            // No pixel geometry yet: a resize will follow.
            return;
        }
        let theme = view::theme();
        let (fg, bg, accent) = (
            Rgba::hex(theme.fg),
            Rgba::hex(theme.bg),
            Rgba::hex(theme.accent),
        );
        let t = (frame.now_ms() % 4000) as f32 / 4000.0;

        // A full repaint: nothing is carried forward from the last frame.
        self.stage.clear(bg);
        let panel = Area::new(8, 8, w.saturating_sub(16), h.saturating_sub(16));
        self.stage
            .fill_rounded_rect(panel, 12, Rgba::hex(theme.recede_bg));
        self.stage
            .rounded_rect(panel, 12, Rgba::hex(theme.recede_fg));

        let (cx, cy) = (w as f32 / 2.0, h as f32 / 2.0);
        let radius = (w.min(h) / 4) as f32;
        let angle = t * core::f32::consts::TAU;
        // `no_std` has no `f32::sin`: the SDK re-exports `libm`. The dot
        // moves between pixels; the shapes antialias it there.
        let dot = (
            cx + radius * libm::cosf(angle),
            cy + radius * libm::sinf(angle),
        );
        self.stage
            .circle((cx, cy), radius, Rgba::hex(theme.recede_fg));
        self.stage
            .line((cx as i32, cy as i32), (dot.0 as i32, dot.1 as i32), accent);
        self.stage.fill_circle(dot, 6.0, accent);

        let bar = Area::new(24, h as i32 - 40, w.saturating_sub(48), 8);
        self.stage
            .bar(bar, t, accent, Rgba::hex(theme.recede_fg).with_alpha(96));
        self.stage.label(24, 24, "shapes", fg);
        let _ = self.stage.commit();

        match frame.power() {
            Power::Mains => frame.request_frame(),
            Power::SavePower => frame.wake_after(1000),
        }
    }

pub fn blit(&mut self, x: i32, y: i32, width: u32, height: u32, rgba: &[u8])

Copies an RGBA8 image of width by height pixels (width * 4 bytes per row) to (x, y), clipped to the surface; no blending. A short rgba copies the rows it holds. Surface::blit_clipped clips to a rectangle too and can blend.

pub fn pixels_mut(&mut self) -> RefMut<'_, [u8]>

The whole frame being painted, as RGBA8 bytes, holding what was last committed. The whole surface is marked dirty; for a small change prefer the drawing methods or Surface::mark_dirty after Surface::pixels_untracked. Empty while the surface has no pixels.

pub fn pixels_untracked(&mut self) -> RefMut<'_, [u8]>

As Surface::pixels_mut, recording nothing: mark what you change with Surface::mark_dirty.

pub fn repaint_all(&mut self) -> RefMut<'_, [u8]>

The whole frame for a full repaint: its contents are stale (what was committed two frames ago), nothing is copied forward, and the whole surface is dirty. The cheapest way to draw an animation that repaints every pixel.

impl<M: SurfaceModel> Surface<M>

pub fn new(id: &str) -> Self

The manifest’s surface id. Binds at once when the viewer has laid it out, else on its first crate::Event::Resize.

Examples found in repository

examples/shapes_stage.rs (line 20)

    fn activate(_cx: &mut Context) -> Self {
        Self {
            stage: Surface::new("stage"),
        }
    }

examples/clock_card.rs (line 27)

    fn activate(_cx: &mut Context) -> Self {
        Self {
            card: Surface::new("card"),
            shown: None,
        }
    }

examples/together_ui.rs (line 70)

    fn activate(cx: &mut Context) -> Self {
        let _ = cx.events().on("together.*");
        let mut plugin = Self {
            card: Surface::new("card"),
            status: Status::default(),
        };
        plugin.reload(cx);
        plugin
    }

pub fn offscreen(geometry: Geometry) -> Self

A surface of the plugin’s own that the host never sees: for tests, and to draw into a buffer before blitting it. Commits are recorded (Surface::last_commit) but go nowhere.

pub fn resize_offscreen(&mut self, geometry: Geometry)

Resizes an offscreen surface as a viewer resize would: a new zeroed region, the next commit fully dirty. No-op for a host surface (the host resizes those).

pub fn id(&self) -> String

pub fn geometry(&self) -> Option<Geometry>

The current geometry; None until the viewer lays the surface out.

pub fn size(&self) -> (u32, u32)

Width and height in the model’s units: cells, or pixels.

Examples found in repository

examples/together_ui.rs (line 54)

    fn paint(&mut self) {
        let (cols, _) = self.card.size();
        self.card.clear();
        let line = format!("{} · {} builds", self.status.state, self.status.builds);
        self.card.text(0, 0, &line, Style::fg(Colour::FG));
        let hint = "rebuild";
        let x = cols.saturating_sub(hint.len() as u32);
        self.card
            .text(x, 0, hint, Style::fg(Colour::ACCENT).underline());
        let _ = self.card.commit();
    }

examples/clock_card.rs (line 36)

    fn frame(&mut self, frame: &Frame) {
        let second = frame.now_ms() / 1000;
        if self.shown != Some(second) {
            self.shown = Some(second);
            let (cols, _) = self.card.size();
            let time = format!(
                "{:02}:{:02}:{:02}",
                second / 3600 % 24,
                second / 60 % 60,
                second % 60
            );
            self.card.text(0, 0, &time, Style::fg(Colour::FG).bold());
            let fraction = (second % 60) as f32 / 60.0;
            let track = Style::fg(Colour::RECEDE_FG);
            self.card.bar(
                Area::new(0, 1, cols, 1),
                fraction,
                Style::fg(Colour::ACCENT),
                track,
            );
            // Publishes only the cells that changed.
            let _ = self.card.commit();
        }
        // The next second boundary: an idle viewer wakes once a second.
        frame.wake_at((second + 1) * 1000);
    }

examples/shapes_stage.rs (line 25)

    fn frame(&mut self, frame: &Frame) {
        let (w, h) = self.stage.size();
        if w == 0 || h == 0 {
            // No pixel geometry yet: a resize will follow.
            return;
        }
        let theme = view::theme();
        let (fg, bg, accent) = (
            Rgba::hex(theme.fg),
            Rgba::hex(theme.bg),
            Rgba::hex(theme.accent),
        );
        let t = (frame.now_ms() % 4000) as f32 / 4000.0;

        // A full repaint: nothing is carried forward from the last frame.
        self.stage.clear(bg);
        let panel = Area::new(8, 8, w.saturating_sub(16), h.saturating_sub(16));
        self.stage
            .fill_rounded_rect(panel, 12, Rgba::hex(theme.recede_bg));
        self.stage
            .rounded_rect(panel, 12, Rgba::hex(theme.recede_fg));

        let (cx, cy) = (w as f32 / 2.0, h as f32 / 2.0);
        let radius = (w.min(h) / 4) as f32;
        let angle = t * core::f32::consts::TAU;
        // `no_std` has no `f32::sin`: the SDK re-exports `libm`. The dot
        // moves between pixels; the shapes antialias it there.
        let dot = (
            cx + radius * libm::cosf(angle),
            cy + radius * libm::sinf(angle),
        );
        self.stage
            .circle((cx, cy), radius, Rgba::hex(theme.recede_fg));
        self.stage
            .line((cx as i32, cy as i32), (dot.0 as i32, dot.1 as i32), accent);
        self.stage.fill_circle(dot, 6.0, accent);

        let bar = Area::new(24, h as i32 - 40, w.saturating_sub(48), 8);
        self.stage
            .bar(bar, t, accent, Rgba::hex(theme.recede_fg).with_alpha(96));
        self.stage.label(24, 24, "shapes", fg);
        let _ = self.stage.commit();

        match frame.power() {
            Power::Mains => frame.request_frame(),
            Power::SavePower => frame.wake_after(1000),
        }
    }

pub fn request_size(&self, cols: u32, rows: u32) -> Result<()>

Asks the viewer for cols by rows cells (0: its choice in that dimension) instead of the manifest’s size; see Context::request_size.

pub fn set_label(&self, label: Option<&str>) -> Result<()>

Sets the short label the viewer shows at the right end of this surface’s chrome title; see Context::set_label.

pub fn set_caret(&self, caret: Option<(u32, u32)>) -> Result<()>

Places the viewer’s text cursor at (col, row) of this surface while it takes keys, or removes it; see Context::set_caret.

pub fn is_attached(&self) -> bool

pub fn is_dirty(&self) -> bool

Whether anything was drawn since the last commit (or the next commit is the first at a new size).

pub fn mark_dirty(&mut self, rect: Rect)

Records a rectangle as changed, after writing through a raw slice.

pub fn commit(&mut self) -> Result<bool>

Publishes what was drawn since the last commit and switches slots. Ok(false) when nothing changed (no host call, no frame). The first commit after a (re)bind covers the whole surface.

Examples found in repository

examples/together_ui.rs (line 62)

    fn paint(&mut self) {
        let (cols, _) = self.card.size();
        self.card.clear();
        let line = format!("{} · {} builds", self.status.state, self.status.builds);
        self.card.text(0, 0, &line, Style::fg(Colour::FG));
        let hint = "rebuild";
        let x = cols.saturating_sub(hint.len() as u32);
        self.card
            .text(x, 0, hint, Style::fg(Colour::ACCENT).underline());
        let _ = self.card.commit();
    }

examples/clock_card.rs (line 53)

    fn frame(&mut self, frame: &Frame) {
        let second = frame.now_ms() / 1000;
        if self.shown != Some(second) {
            self.shown = Some(second);
            let (cols, _) = self.card.size();
            let time = format!(
                "{:02}:{:02}:{:02}",
                second / 3600 % 24,
                second / 60 % 60,
                second % 60
            );
            self.card.text(0, 0, &time, Style::fg(Colour::FG).bold());
            let fraction = (second % 60) as f32 / 60.0;
            let track = Style::fg(Colour::RECEDE_FG);
            self.card.bar(
                Area::new(0, 1, cols, 1),
                fraction,
                Style::fg(Colour::ACCENT),
                track,
            );
            // Publishes only the cells that changed.
            let _ = self.card.commit();
        }
        // The next second boundary: an idle viewer wakes once a second.
        frame.wake_at((second + 1) * 1000);
    }

examples/shapes_stage.rs (line 65)

    fn frame(&mut self, frame: &Frame) {
        let (w, h) = self.stage.size();
        if w == 0 || h == 0 {
            // No pixel geometry yet: a resize will follow.
            return;
        }
        let theme = view::theme();
        let (fg, bg, accent) = (
            Rgba::hex(theme.fg),
            Rgba::hex(theme.bg),
            Rgba::hex(theme.accent),
        );
        let t = (frame.now_ms() % 4000) as f32 / 4000.0;

        // A full repaint: nothing is carried forward from the last frame.
        self.stage.clear(bg);
        let panel = Area::new(8, 8, w.saturating_sub(16), h.saturating_sub(16));
        self.stage
            .fill_rounded_rect(panel, 12, Rgba::hex(theme.recede_bg));
        self.stage
            .rounded_rect(panel, 12, Rgba::hex(theme.recede_fg));

        let (cx, cy) = (w as f32 / 2.0, h as f32 / 2.0);
        let radius = (w.min(h) / 4) as f32;
        let angle = t * core::f32::consts::TAU;
        // `no_std` has no `f32::sin`: the SDK re-exports `libm`. The dot
        // moves between pixels; the shapes antialias it there.
        let dot = (
            cx + radius * libm::cosf(angle),
            cy + radius * libm::sinf(angle),
        );
        self.stage
            .circle((cx, cy), radius, Rgba::hex(theme.recede_fg));
        self.stage
            .line((cx as i32, cy as i32), (dot.0 as i32, dot.1 as i32), accent);
        self.stage.fill_circle(dot, 6.0, accent);

        let bar = Area::new(24, h as i32 - 40, w.saturating_sub(48), 8);
        self.stage
            .bar(bar, t, accent, Rgba::hex(theme.recede_fg).with_alpha(96));
        self.stage.label(24, 24, "shapes", fg);
        let _ = self.stage.commit();

        match frame.power() {
            Power::Mains => frame.request_frame(),
            Power::SavePower => frame.wake_after(1000),
        }
    }

pub fn last_commit(&self) -> Option<CommitInfo>

What the last commit published.

pub fn pending_dirty(&self) -> Vec<Rect>

The rectangles the next commit would send (without the fully dirty first commit’s).

pub fn detach(&mut self) -> Result<()>

Unbinds the surface from the host. Dropping the surface does this.

Trait Implementations

impl<M: Debug + SurfaceModel> Debug for Surface<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M: SurfaceModel> Drop for Surface<M>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Shapes for Surface<Cells>

fn fill_rect(&mut self, area: Area, ink: Style)

Full blocks in the style’s foreground. For a background panel use Surface::fill with a space and a background colour.

fn bar(&mut self, area: Area, fraction: f32, fill: Style, track: Style)

Full blocks in fill, one eighth block for the partial cell, and ░ in track for the rest.

fn fill_rounded_rect(&mut self, area: Area, radius: u32, ink: Style)

Full blocks, with quarter blocks in the corners when radius > 0.

type Ink = Style

fn stroke_rect(&mut self, area: Area, ink: Style)

A one-unit outline of area.

fn line(&mut self, from: (i32, i32), to: (i32, i32), ink: Style)

A line from from to to, both ends included.

fn rounded_rect(&mut self, area: Area, radius: u32, ink: Style)

The outline of area with corners of radius (cells round their corners with arcs whatever the radius; a zero radius is square).

fn circle(&mut self, centre: (f32, f32), radius: f32, ink: Style)

A circle’s outline around centre, in continuous coordinates: the unit at (x, y) spans x..x + 1, so (x + 0.5, y + 0.5) is its centre, and a moving shape can sit between units (pixels antialias it; cells round to the nearest cell). Cells are about twice as tall as wide, so in cells the radius counts rows and spans twice as many columns.

fn fill_circle(&mut self, centre: (f32, f32), radius: f32, ink: Style)

A filled circle (see Shapes::circle).

fn label(&mut self, x: i32, y: i32, text: &str, ink: Style) -> u32

Text from (x, y), clipped: cells write graphemes; pixels draw the built-in 5x7 font (GLYPH_ADVANCE pixels per character, ASCII; other characters show as a box). Returns the units advanced.

impl Shapes for Surface<Pixels>

type Ink = Rgba

fn stroke_rect(&mut self, area: Area, ink: Rgba)

A one-unit outline of area.

fn fill_rect(&mut self, area: Area, ink: Rgba)

area, filled.

fn line(&mut self, from: (i32, i32), to: (i32, i32), ink: Rgba)

A line from from to to, both ends included.

fn bar(&mut self, area: Area, fraction: f32, fill: Rgba, track: Rgba)

A horizontal bar across area: the left fraction (0 to 1) in fill, the rest in track. Partial units are shown with eighth blocks (cells) or coverage (pixels).

fn rounded_rect(&mut self, area: Area, radius: u32, ink: Rgba)

The outline of area with corners of radius (cells round their corners with arcs whatever the radius; a zero radius is square).

fn fill_rounded_rect(&mut self, area: Area, radius: u32, ink: Rgba)

area filled, with corners of radius.

fn circle(&mut self, centre: (f32, f32), radius: f32, ink: Rgba)

A circle’s outline around centre, in continuous coordinates: the unit at (x, y) spans x..x + 1, so (x + 0.5, y + 0.5) is its centre, and a moving shape can sit between units (pixels antialias it; cells round to the nearest cell). Cells are about twice as tall as wide, so in cells the radius counts rows and spans twice as many columns.

fn fill_circle(&mut self, centre: (f32, f32), radius: f32, ink: Rgba)

A filled circle (see Shapes::circle).

fn label(&mut self, x: i32, y: i32, text: &str, ink: Rgba) -> u32

Text from (x, y), clipped: cells write graphemes; pixels draw the built-in 5x7 font (GLYPH_ADVANCE pixels per character, ASCII; other characters show as a box). Returns the units advanced.