API reference

aster_blueprint::event_motion

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.

Application-owned binding from one graph event endpoint to one existing caller-clock motion command.

This module is a narrow seam between two capabilities that already exist:

  • the graph event endpoint seam ([crate::event_binding]), which binds one compiled Plan event/intent output to an actual acknowledged input context, and
  • the caller-clock motion state machine ([crate::motion]), whose playback commands are start / pause / resume / seek / reverse / cancel and whose only time source is a caller-supplied [Seconds].

The application owns the mapping: exactly one [OwnedEndpoint] is paired with exactly one existing [Command]. Nothing here routes an event to a command, infers a mapping, schedules a tick, reads a clock, keeps a state protocol or authenticates anything.

[MotionBinding::dispatch] validates the observation that the caller's action is an exact acknowledgement of the caller's actual acknowledged context, by reusing [OwnedEndpoint::complete] with the exact active Arc<Plan>, the actual [AcknowledgedContext] and the existing [BoundAction] of the [GraphEndpoint]. That is a statement about what the caller observed; it is never a proof of authorization:

  • [AcknowledgedContext::bind] binds a value to a node that really was presented. It does not activate anything.
  • The deliberate input (a real button gesture) or the backend authority has to be admitted by the application before an action is bound. This module cannot see, admit, replay or vouch for that admission.

A stale acknowledgement, a foreign plan, an action bound to another endpoint, or a motion command the playback state machine refuses, never touch the playback state: the phase, the position and needs_tick are

(documentation continues in the source)

Structs

structaster_blueprint::event_motion::MotionBinding

pub struct MotionBinding { /* see fields */ }

One explicit application mapping: a graph event endpoint and the single existing motion command its acknowledgement drives.

The pairing is the application's own decision. The binding holds exactly one endpoint and exactly one command, so an action that was bound to a different endpoint, plan or output can never drive the command: the existing endpoint seam refuses it first.

Methods

  • fn new(endpoint: OwnedEndpoint, command: Command) -> Self — Pair exactly one endpoint with exactly one existing motion command.
  • fn endpoint(&self) -> &OwnedEndpoint — The endpoint this binding is mapped to.
  • fn command(&self) -> Command — The single existing motion command this endpoint drives.
  • fn plan(&self) -> &Arc<Plan> — The plan this binding was built against.
  • fn dispatch(&self, active: &Arc<Plan>, ctx: &AcknowledgedContext<'_>, action: &BoundAction<GraphEndpoint>, motion: &mut Motion) -> Result<CommandReport, MotionBindError> — Drive the mapped motion command from an observed, acknowledged action.

structaster_blueprint::event_motion::RetainedTarget

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

Borrowed application inputs for one retained-scene composition. This holds no new state or authority: the application supplies the actual instance, parameter map, resource resolver, graph clock and output for this call.

Public fields

fieldtype
instance&'a mut retained::RetainedInstance
parameters&'a mut std::collections::BTreeMap<model::Symbol, model::Literal>
resources&'a dyn ResourceResolver
clockOption<f64>
outputaster_ui::Output

Enums

enumaster_blueprint::event_motion::ComposeError

pub enum ComposeError { Motion, Scene }

Why a composed scene update was refused.

Variants

  • Motion — The existing motion seam refused the caller clock reading; the motion is unchanged and the callback never ran.
  • Scene — The caller's retained scene refused the composed update; the motion is unchanged and the caller's parameters are restored.

Trait implementations: Debug, Display, Error

enumaster_blueprint::event_motion::MotionBindError

pub enum MotionBindError { Endpoint }

Why an observed graph endpoint could not drive the motion command it is mapped to.

Every variant is an observation failure. None of them is a statement about authorization, and none of them changes the playback state.

Variants

  • Endpoint — The existing endpoint seam refused the observed binding: a stale acknowledgement, a foreign plan, an action bound to another endpoint or output, or a context that no longer accepts the action.

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

Functions

fnaster_blueprint::event_motion::advance

pub fn advance(motion: &mut motion::Motion, now: motion::Seconds, target: RetainedTarget<'_>, update: impl FnOnce(&motion::TickOutcome, &mut std::collections::BTreeMap<model::Symbol, model::Literal>)) -> Result<motion::TickOutcome, ComposeError>

Advance the caller's motion by one caller clock reading and compose the sampled parameter update into the caller's actual retained instance scene.

The advance and the scene commit are one transaction:

  • the existing [Motion::tick_with] simulates the advance under its own stack guard and hands the simulated outcome to update, which writes the caller's own parameter update into a private copy of parameters;
  • the composed parameters are evaluated and committed into instance — the actual retained scene, not a copy of it;
  • a refused evaluation or commit leaves parameters and the motion exactly as they were, so the same clock reading can be retried;
  • only an accepted commit lets the playback state be adopted, so the motion and the scene never disagree about the sampled value.

The caller keeps the clock, the resources, the parameter policy and the output: update is the application's own projection of the sampled value into its parameters, and nothing here schedules the next reading. A panic from update also leaves these parameters and the motion unchanged; other effects the caller performs inside that closure cannot be rolled back.