API reference

aster_blueprint::headless

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.

Headless agent feedback loop: render, save, diff, snapshot-test, hit-test.

Everything here is CPU-only and deterministic. See docs/AGENT-LOOP.md.

use aster_blueprint::headless::Headless;
let shot = Headless::new(800, 600, 2.0)?.render_scene(scene)?; // 1600x1200 px
shot.write_png("/tmp/ui.png")?;

Structs

structaster_blueprint::headless::Headless

pub struct Headless { /* see fields */ }

Fixed-size headless CPU renderer configuration.

Methods

  • fn new(logical_width: u32, logical_height: u32, scale: f64) -> Result<Self> — logical_width x logical_height logical px at scale (e.g. 2.0 gives a 2x-dense picture). The default clear color is transparent.
  • fn with_clear(self, rgba: [u8; 4]) -> Self — Opaque or translucent clear color painted under the scene.
  • fn output(&self) -> Output
  • fn logical_size(&self) -> [u32; 2]
  • fn scale(&self) -> f64
  • fn physical_size(&self) -> [u32; 2]
  • fn render_scene(&self, scene: &Scene) -> Result<Image> — Render a scene to RGBA in one call.
  • fn render_png(&self, scene: &Scene, path: impl AsRef<Path>) -> Result<Image> — Render a scene and write a PNG; returns the image too.
  • fn render_instance(&self, instance: &RetainedInstance) -> Result<Image> — Render a retained blueprint instance (must have been committed with an Output of this size/scale).
  • fn hit(&self, scene: &Scene, pointer_keys: &[ModelKey], x: f64, y: f64) -> Result<Option<ModelKey>> — Which of pointer_keys is hit by a pointer at logical (x, y)?

Trait implementations: Clone, Copy, Debug

structaster_blueprint::headless::Image

pub struct Image { /* see fields */ }

An owned straight-alpha RGBA8 picture (the renderer's pixel format).

Public fields

fieldtype
widthu32
heightu32
rgbaVec<u8>

Methods

  • fn new(width: u32, height: u32, rgba: Vec<u8>) -> Result<Self>
  • fn pixel(&self, x: u32, y: u32) -> [u8; 4] — Pixel at (x, y) as [r, g, b, a]; panics out of range.
  • fn png_bytes(&self) -> Result<Vec<u8>> — Deterministic PNG bytes.
  • fn write_png(&self, path: impl AsRef<Path>) -> Result<()>
  • fn read_png(path: impl AsRef<Path>) -> Result<Self>
  • fn over(&self, background: [u8; 3]) -> Self — Source-over an opaque background (alpha becomes 255).
  • fn crop(&self, x: u32, y: u32, w: u32, h: u32) -> Result<Self> — Copy of the physical-pixel rectangle [x, y, w, h], clamped to the image.
  • fn diff(&self, other: &Self, tolerance: u8) -> ImageDiff — Per-pixel comparison; a channel differs when |a-b| > tolerance.
  • fn diff_image(&self, other: &Self, tolerance: u8) -> Result<Self> — A picture of the difference: mismatching pixels opaque red, others a dimmed grayscale of self. Sizes must match.

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

structaster_blueprint::headless::ImageDiff

pub struct ImageDiff { /* see fields */ }

Result of [Image::diff].

Public fields

fieldtype
size_mismatchbool
mismatchedusizePixels with any channel beyond tolerance.
bboxOption<[u32; 4]>Bounding box [x, y, w, h] of mismatching pixels in physical pixels.
max_deltau8Largest per-channel difference seen (255 on size mismatch).
totalusize

Methods

  • fn is_match(&self) -> bool

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

structaster_blueprint::headless::SnapshotMismatch

pub struct SnapshotMismatch { /* see fields */ }

Payload of [SnapshotError::Mismatch].

Public fields

fieldtype
goldenstd::path::PathBuf
actualstd::path::PathBuf
diff_imageOption<std::path::PathBuf>
diffImageDiff

Trait implementations: Debug

Enums

enumaster_blueprint::headless::SnapshotError

pub enum SnapshotError { Missing, Mismatch, Other }

Golden comparison failure. Display text is agent-readable.

Variants

  • Missing
  • Mismatch — Boxed so Result<_, SnapshotError> stays small.
  • Other

Trait implementations: Debug, Display, Error

enumaster_blueprint::headless::SnapshotOutcome

pub enum SnapshotOutcome { Written, Matched }

Outcome of a golden comparison.

Variants

  • Written — Golden written (update mode, or create_missing).
  • Matched

Trait implementations: Debug

Type aliases

typeaster_blueprint::headless::Result

pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;

Boxed error: every layer below already implements std::error::Error.

Functions

fnaster_blueprint::headless::assert_snapshot

pub fn assert_snapshot(golden: impl AsRef<std::path::Path>, image: &Image, tolerance: u8)

Panicking form for tests: assert_snapshot("tests/golden/home.png", &img, 0).

fnaster_blueprint::headless::check_snapshot

pub fn check_snapshot(golden: impl AsRef<std::path::Path>, image: &Image, tolerance: u8) -> std::result::Result<SnapshotOutcome, SnapshotError>

[check_snapshot_with] honoring ASTER_UPDATE_SNAPSHOTS.

fnaster_blueprint::headless::check_snapshot_with

pub fn check_snapshot_with(golden: impl AsRef<std::path::Path>, image: &Image, tolerance: u8, update: bool) -> std::result::Result<SnapshotOutcome, SnapshotError>

Compare image with the golden PNG at golden (explicit update flag).

On mismatch writes <stem>.actual.png and <stem>.diff.png next to the golden. On update, writes the golden and deletes stale actual/diff files.

fnaster_blueprint::headless::compile_text

pub fn compile_text(text: &str) -> Result<compiler::Plan>

Compile blueprint text (core catalog, default environment).

fnaster_blueprint::headless::parse_literal

pub fn parse_literal(value_type: model::ValueType, text: &str) -> Result<model::Literal>

Parse a NAME=VALUE override against a declared parameter type.

Scalars/lengths/seconds are decimal numbers, bools true|false, colors #rrggbb, #rrggbbaa or r,g,b,a, text is literal.

fnaster_blueprint::headless::render_blueprint

pub fn render_blueprint(text: &str, logical_width: u32, logical_height: u32, scale: f64, overrides: &[(String, String)], clear: [u8; 4]) -> Result<Image>

Render a single-visual blueprint (outputs bounds + one of drawing, label, paint) to an image.

LogicalLength parameters named width/height default to the logical size; overrides (name, text) set any declared parameter.

fnaster_blueprint::headless::update_requested

pub fn update_requested() -> bool

Whether ASTER_UPDATE_SNAPSHOTS asks for golden writing.

Constants

constaster_blueprint::headless::UPDATE_ENV

pub const UPDATE_ENV: &str

Environment variable that turns golden comparison into golden writing.