API reference

aster_blueprint::retarget

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.

Retained cross-plan replacement: move an adopted [RetainedInstance] from its compiled Plan to a newly compiled one while keeping the Scene nodes of every visual whose authored key and kind are still compatible.

The stable key is the caller's [NodeKey] (authored node key or asset-expansion key) carried by each [VisualSpec]. Per key, in one Scene edit: same key, same ModelKey and same content family retain the existing NodeId; keys absent from the new specs are retired (their nodes removed); new keys are inserted; a key whose model key or content family changed is retired and re-created, so a stale NodeId can never alias a different kind of node. Sibling order follows the new spec order, so pixels equal a cold rebuild of the new plan.

The new runtime is built and evaluated on the side. The old runtime, Scene contents, visual table and epoch are replaced only after the single Scene commit succeeds; any earlier failure (compile-shaped refusal, evaluation, fit, capacity, or the caller's update hook) leaves the previous adoption exactly as it was. No painter, router or layout solver is created.

Structs

structaster_blueprint::retarget::NodeEndpoint

pub struct NodeEndpoint { /* see fields */ }

Authority-free handle to one retained visual at one adopted plan epoch. Not a capability: it only lets a caller detect that its binding went stale.

Methods

  • fn key(&self) -> NodeKey
  • fn node(&self) -> NodeId

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

structaster_blueprint::retarget::PreparedRetarget

pub struct PreparedRetarget { /* see fields */ }

Everything fallible and Scene-free about one retarget, already done: specs resolved, the new runtime built and evaluated, node descriptions validated against the device and command budget, capacity checked. Produced by [RetainedInstance::prepare_retarget] (which only borrows the instance immutably); consumed by [PreparedRetarget::commit].

Dropping it has no effect on any instance. It is bound to the instance serial and epoch it was prepared against and is refused (StalePrepared) anywhere else, including after a different retarget was adopted.

Methods

  • fn plan(&self) -> &Arc<Plan>
  • fn retiring(&self) -> &[(NodeKey, NodeId)] — Keys whose node would be removed.
  • fn commit(self, instance: &mut RetainedInstance) -> Result<RetargetReport, RetargetError> — Apply to instance. See commit_with.
  • fn commit_with<R>(self, instance: &mut RetainedInstance, update: impl FnOnce(&Candidate, &mut Edit<'_>) -> Result<R, Error>) -> Result<(RetargetReport, R), RetargetError> — The single Scene commit plus adoption. This is the only remaining fallible step: the Scene transaction (and update) can still refuse, for example when caller-attached controls leave too little node room. A Scene transaction cannot be prepared separately, so it is not infallible; on Err the Scene, runtime, visual table and epoch are exactly as before (the failed Edit aborts). After the Scene commit succeeds the adoption is plain moves and field assignments: the next epoch was checked in prepare, and the new visual table and the retained/added lists are built (and sized) inside the Scene edit, before its final commit, where a failure still aborts everything.
  • fn commit_for_renderer(self, instance: &mut RetainedInstance, renderer: &mut Renderer) -> Result<RetargetReport, RetargetError> — As commit, but the single Scene edit is admitted against renderer with Edit::commit_for_renderer. A refusal (for example a finite but enormous Recording) aborts exactly like any other Scene refusal: nodes, runtime, visual table and epoch are unchanged. Direct render_scene only; PreparedScene affine/group composition is not covered.
  • fn commit_with_for_renderer<R>(self, instance: &mut RetainedInstance, renderer: &mut Renderer, update: impl FnOnce(&Candidate, &mut Edit<'_>) -> Result<R, Error>) -> Result<(RetargetReport, R), RetargetError> — commit_with plus renderer admission.

structaster_blueprint::retarget::RetargetReport

pub struct RetargetReport { /* see fields */ }

What one adopted retarget did. Only produced after success.

Public fields

fieldtype
retainedVec<(model::NodeKey, aster_ui::NodeId)>Keys whose existing NodeId survived.
retiredVec<(model::NodeKey, aster_ui::NodeId)>Keys whose old node was removed (including replaced kinds).
addedVec<(model::NodeKey, aster_ui::NodeId)>Keys given a fresh node (including replaced kinds).
stampaster_ui::SceneStamp

Methods

  • fn from_plan(&self) -> PlanId
  • fn to_plan(&self) -> PlanId
  • fn remap(&self, endpoint: &NodeEndpoint) -> Result<NodeEndpoint, StaleEndpoint> — Carry an endpoint taken before this retarget over to the new plan. Refuses endpoints older than the replaced adoption and removed nodes.
  • fn rebind_event(&self, old: &OwnedEndpoint, new_plan: &Arc<Plan>) -> Result<OwnedEndpoint, EndpointError> — Re-select an event/intent endpoint on the new plan. The old endpoint must belong to the replaced plan and the same output name must still exist on the new plan with the same declared type.

Trait implementations: Clone, Debug

Enums

enumaster_blueprint::retarget::RetargetError

pub enum RetargetError { SamePlan, CapacityExceeded, StalePrepared, EpochExhausted, Retained }

Variants

  • SamePlan — The target is the plan already adopted; use evaluate/commit instead.
  • CapacityExceeded — The new plan needs more visual nodes than the Scene's fixed capacity. Nothing was changed. Node ids cannot be kept across a larger Scene; the caller may choose [RetainedInstance::cold_rebuild] (or [edit_and_rebuild_cold]) and accept brand-new ids.
  • StalePrepared — A [PreparedRetarget] was committed to an instance that is not the one (or not the adoption state) it was prepared against.
  • EpochExhausted — The adoption epoch is at u64::MAX, so another retarget cannot be numbered. Refused in prepare; nothing was changed. The caller may resynchronise with [RetainedInstance::cold_rebuild], which restarts the epoch at 0.
  • Retained

Trait implementations: Debug, Display, Error, From<E>

enumaster_blueprint::retarget::StaleEndpoint

pub enum StaleEndpoint { Generation, Removed }

Why a node endpoint can no longer be used.

Variants

  • Generation — Taken from another plan or before the latest adopted retarget.
  • Removed — The keyed node was retired (or replaced by a different node).

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

enumaster_blueprint::retarget::StepRetargetError

pub enum StepRetargetError { Editor, Allocation, Retarget }

Failure of an undo/redo that also retargets. In every case the editor (Arcs, revision, history) and the Scene are exactly as before the call.

Variants

  • Editor — The editor refused the step (nothing to undo/redo, revision exhausted).
  • Allocation — The editor's history reserve failed before the retarget was attempted.
  • Retarget — The retarget (or its renderer admission) was refused; nothing moved.

Trait implementations: Debug, From<ApplyWithError<RetargetError>>

Functions

fnaster_blueprint::retarget::edit_and_rebuild_cold

pub fn edit_and_rebuild_cold(editor: &mut editor::Editor, expected_revision: u64, changes: &[editor::Change], specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, limits: retained::VisualLimits, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, retained::RetainedInstance), editor::ApplyWithError<retained::RetainedError>>

The caller-chosen capacity fallback, still atomic: the editor edit is admitted only if a larger Scene could be built cold for the candidate plan. On success the returned instance replaces the old one (the caller assigns it); on failure the editor and the old instance are untouched. Node ids and endpoints of the old instance do NOT carry over.

fnaster_blueprint::retarget::edit_and_retarget

pub fn edit_and_retarget(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, expected_revision: u64, changes: &[editor::Change], specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, RetargetReport), editor::ApplyWithError<RetargetError>>

One topology edit, atomic end to end. The editor compiles the candidate, then specs chooses the visuals for the candidate plan, then the retarget is prepared and, as the very last fallible step inside the admission callback, committed to the Scene. The editor adopts only after that returned Ok, and its adoption is infallible. So a refusal or failure in either step leaves the editor (Arcs, revision, history) and the Scene (contents, SceneStamp, node ids, epoch) in their previous adopted state. A CapacityExceeded refusal arrives as ApplyWithError::Admit. The only residual window is the infallible assignments between the Scene commit and returning from the callback; a panic inside the caller's specs closure happens before the Scene commit.

fnaster_blueprint::retarget::edit_and_retarget_for_renderer

pub fn edit_and_retarget_for_renderer(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, expected_revision: u64, changes: &[editor::Change], specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output, renderer: &mut aster_ui::Renderer) -> Result<(editor::EditOutcome, RetargetReport), editor::ApplyWithError<RetargetError>>

As [edit_and_retarget], but the Scene edit is admitted against renderer with Edit::commit_for_renderer. A candidate the renderer would refuse (for example a finite but enormous Recording) arrives as ApplyWithError::Admit(RetargetError::Retained(..)) and leaves the editor and the Scene unchanged. Direct render_scene only.

fnaster_blueprint::retarget::redo_and_retarget

pub fn redo_and_retarget(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>

As [undo_and_retarget], for Editor::redo_with.

fnaster_blueprint::retarget::redo_and_retarget_for_renderer

pub fn redo_and_retarget_for_renderer(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output, renderer: &mut aster_ui::Renderer) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>

As [redo_and_retarget], with renderer admission of the Scene edit.

fnaster_blueprint::retarget::undo_and_retarget

pub fn undo_and_retarget(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>

Editor::undo_with whose admission callback prepares and commits the retarget to the restored plan. Atomic like [edit_and_retarget]: a refused retarget (including CapacityExceeded) leaves the editor (revision, Arcs, both stacks) and the Scene unchanged; success moves both.

fnaster_blueprint::retarget::undo_and_retarget_for_renderer

pub fn undo_and_retarget_for_renderer(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output, renderer: &mut aster_ui::Renderer) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>

As [undo_and_retarget], with renderer admission of the Scene edit.