Crate oxframe

Expand description

§oxframe

Status: oxframe is under very active development. The API is not stable yet and may change from version to version. Pin the exact version in your Cargo.toml and check the changelog before upgrading.

Procedural animation modelled after Motion Canvas: a scene is an async fn, and every .await on an animation is a frame boundary.

use oxframe::prelude::*;

#[oxframe::scene]
async fn intro(view: View) {
    let r = view.add(Rect::new().size(200.0).x(-300.0).fill(color!("#e13238")));
    all((r.x().to(300.0, 1.0), r.radius().to(100.0, 1.0))).await;
}

fn main() {
    Project::new("intro").scene(intro()).main();
}

Re-exports§

pub use Accent;
pub use Background;
pub use Danger;
pub use Fast;
pub use Lg;
pub use Md;
pub use Muted;
pub use Normal;
pub use OnAccent;
pub use Slow;
pub use Sm;
pub use Success;
pub use Surface;
pub use Text;
pub use Warning;
pub use Xl;
pub use Xs;
pub use oxframe_2d as nodes;
pub use oxframe_core as core;
pub use oxframe_protocol as protocol;
pub use oxframe_render as render;
pub use oxframe_text as text;

Modules§

feedback: check and inspect: a storyboard, a visual-lint report, and a scene dump.
lint: Visual lint over sampled scene graphs. Pure: no rendering, no files.
prelude: Everything a scene usually needs: use oxframe::prelude::*;.
presets: Named Bézier presets (values follow easings.net / CSS).
shaders: Preset shaders. A scene starts here and writes its own WGSL only when no preset fits.

Macros§

color: color!("#e13238") — a Color checked at compile time. Accepts #rgb, #rgba, #rrggbb and #rrggbbaa.
ease: ease!("slide") or ease!("slide", presets::OUT_BACK) — a named Bézier easing editable in the curve editor; the value lives in meta.json.
tune: tune!("speed", 1.4) — a number editable with a slider in the inspector; the value lives in meta.json.

Structs§

Affine: A 2D affine transform.
Audio: A soundtrack for Project::audio.
Axes: A plotting area: a box with ranges, a grid, axes with arrows, ticks and labels. Derefs to Node, so it moves and fades like any node.
Bars: Bars from Axes::bars.
BezPath: A Bézier path.
Blend: The two layers of one transition frame.
BulletList: Items appear one per next, after enter shows the stack.
Callout: A caption above target, with an arrow pointing down at it. next reveals the caption; the arrow comes in with enter.
Camera: Handle to a Camera node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
ChapterMarker: A short label pinned to the top safe area.
Circle: Handle to a Circle node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Code: Handle to a Code node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
CodeExplainer: Code with a caption. enter shows the code. Each next focuses one step and sets the caption.
CodeText: The source of a Code node.
CodeTheme: Colors of a code theme.
CodeTween: Diff tween returned by CodeText::to, Code::insert, Code::remove and Code::replace.
Color: sRGB color with straight (non-premultiplied) alpha, components in 0..=1.
CubicBezier: CSS-style cubic Bézier easing with control points (x1, y1), (x2, y2); the end points are fixed at (0, 0) and (1, 1).
Custom: Handle to geometry drawn by a closure. Derefs to Node.
DrawCtx: What a crate::Custom node draws into. Coordinates are the node’s own: the origin is the node center, positive x is right, positive y is down.
DrawRng: A generator from DrawCtx::rng.
Effect: Handle to a node’s shader effect, from Node::effect.
EndCard: Closing card. next reveals the note.
Engine: Runs a Project: knows the length of every scene and produces the state of any global frame.
Executor: Deterministic single-threaded executor: one step is one frame. The root future and every spawned task are polled once per step, in a fixed order (root, then tasks in spawn order). No wakers, no clocks, no threads — the same input always produces the same frames.
FlowDiagram: Nodes and arrows. The diagram places itself: left to right, or top to bottom after down. next highlights the next node.
Gradient: A gradient in the node’s local coordinates (origin at the node center).
Grid: Handle to a Grid node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Group: Handle to a Group node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Img: Handle to a Img node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Interval: A data range, min to max. Animates with .to(-10.0..10.0, 1.0).
JoinHandle: Awaiting it waits for the spawned task to finish.
LayerPose: How one of the two layers is drawn. Offsets are fractions of the frame (positive x moves the layer right, positive y moves it down). Scale is around the frame center. A wipe reveals that fraction of the layer from dir and hides the rest.
Layout: Handle to a Layout node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Line: Handle to a Line node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
LowerThird: Name and role pinned to the bottom safe area. next reveals the role.
Motion: Durations in seconds and the eases for entering, leaving and emphasis.
Node: Untyped node handle with the properties every node has.
NodeId: Index of a node in its SceneGraph. Assigned in creation order, so it is deterministic too.
NumberLine: A single horizontal axis with ticks, labels and an arrow.
Particles: Handle to a Particles node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Path: Handle to a Path node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Pen: A shape just added to a DrawCtx, waiting for a fill or a stroke.
Plot: A function plot. Derefs to its Path, so .draw_on(), .stroke() and .line_width() work as on any path.
Point: A 2D point.
Polygon: Handle to a Polygon node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
PreviewAdapter: An Engine plus a renderer, as seen by the preview session.
Project: A sequence of scenes plus output settings. Call main() from your binary’s main to get the render/info commands.
Rect: Handle to a Rect node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
RichSpan: A run of text with its own look; unset fields use the node’s style.
SafeArea: The rectangle to_edge keeps inside, in scene coordinates (origin at the center, y down).
SceneDef: A scene produced by #[oxframe::scene].
SceneGraph: Arena of nodes for one scene run. Node 0 is the view (root).
Series: A line through data points; see Axes::line_series.
Shader: Handle to a WGSL shader. Derefs to Node.
ShaderTransition: A transition drawn by a shader preset from both scenes’ pixels.
Signal: A reactive value.
SourceLocation: Where a scene was defined; used to find its <name>.meta.json.
Star: Handle to a Star node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Svg: Handle to a Svg node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Synthesis: Audio and word timings from a TtsProvider.
Theme: Colors, type, space, radii, shadows and motion for one look.
TimedWord: One word and where it sits inside the line.
TitleCard: A centered title. enter shows the card and the title, next shows the subtitle.
Transform: Decomposed 2D transform. Interpolates component-wise, so rotations turn instead of shearing through the matrix midpoint.
Transition: How the previous scene gives way to this one.
TtsRequest: What a provider is asked to speak.
Tween: Animates a Signal towards a target. Created by Signal::to.
Txt: Handle to a Txt node in the scene: cheap to copy, its methods return the node’s properties as Signals. Derefs to Node.
Vec2: A 2D vector.
View: Root of a scene. Origin is the center of the frame, y points down.

Enums§

Aspect: A frame shape. The project’s longer side stays the long side.
BlendMode: How a node’s layer is composited onto what is below it.
Dir: Edge a slide or a wipe moves toward.
Direction: Main axis of a Layout.
Edge: An edge of a node or of the safe area.
EngineError: Why a project could not be loaded.
Ink: A color role. Use it wherever a Color is accepted: .fill(Accent).
Input: What a shader reads besides its own parameters.
Justify: Main-axis distribution of children; only matters with a fixed size.
LayoutAlign: Cross-axis alignment of children in a Layout.
LineCap: Shape of the ends of open outlines.
LineJoin: Shape of outline corners.
MetaSection: A section of meta.json, for Engine::edit_meta.
Pace: How long a motion token lasts: .to(1.0, Normal).
Side: Which side of a neighbor Node::next_to uses.
Span: A length in pixels, or a percentage of the frame (or of a sized parent).
Step: A step on the space, radius and shadow scales: .padding(Md), .radius(Lg).
TextAlign: Horizontal alignment of lines.

Constants§

MONO: Built-in monospace family (JetBrains Mono).
SANS: Built-in sans-serif family (Inter).

Traits§

Ease: Maps linear progress t ∈ [0, 1] to eased progress.
Lerp: Linear interpolation; t is already eased and may leave [0, 1] (e.g. with back easings).
NodeBuilder: Describes a node before it is added to the scene.
Percent: A number that can be a percentage. pct(80) and pct(80.0) are the same.
TtsProvider: Turns a line into audio and word timings.

Functions§

all: Runs animations at the same time and completes when all of them have.
all_vecDeprecated: all for boxed futures.
any: Runs animations at the same time and completes as soon as the first one does; the others stop where they are. Returns the index of the one that finished. Takes the same arguments as all.
bounce_in: Bounces before leaving.
bounce_in_out: Bounces at both ends.
bounce_out: Bounces into place, like a dropped ball.
dt: Duration of one frame in seconds, 1 / fps.
ease_named: Named easing from meta.json; default is recorded there on first use. Use through the ease! macro.
elastic_in: Oscillates before leaving, like a spring being wound.
elastic_in_out: Spring at both ends.
elastic_out: Overshoots and oscillates into place, like a spring.
fps: Frames per second of the running project.
frame: Index of the frame being computed.
loop_while: Runs the animation make() returns again and again while keep_going() is true (checked before each run). Usually spawned for a background loop: spawn(loop_while(|| true, || pulse.scale().to(1.1, 0.5))).
next_frame: Yields until the next frame.
now: Time of the current frame, frame / fps seconds.
pct: 80 percent of the frame, or of the parent when it has a fixed size.
random: Uniform random number in [0, 1) from the scene’s seeded generator.
random_range: Uniform random number in [min, max) from the scene’s seeded generator.
register_font: Registers a font (TTF/OTF/TTC bytes, e.g. from include_bytes!). Returns the family names it provides.
repeat: Runs the animation make() returns times times in a row.
sequence: Starts animations one after another, delay seconds apart; they then run concurrently. Completes when all have. Takes a Vec, an array or an iterator of animations of one type. For “the same animation on many nodes”, stagger reads better.
sound: A sound effect from a file, starting at the current frame.
span: Shorthand for RichSpan::new.
spawn: Runs fut in the background, starting this frame. Background tasks stop when the scene ends.
stagger: Runs animate on every item, starting each delay seconds after the previous one; completes when all have finished:
time: Virtual time of the current task — where the next animation starts.
transition: Plays spec at the start of a scene.
tunable: Value of tunable name from meta.json; default is recorded there on first use. Use through the tune! macro.
voice: A line of speech, starting at the current frame.
wait_for: Waits seconds of scene time.
wait_until: Waits until marker name from meta.json. On first encounter the current time becomes the marker’s default, so it does not wait at all.
waves: The waves preset: a crest of foam over deep water.
with_rng: Runs f with the scene’s random generator. It is seeded from the project seed and the scene name, so results are reproducible; never use rand::rng() or other entropy sources in scenes.

Type Aliases§

BoxFuture: A boxed scene future, e.g. for sequence.

Attribute Macros§

scene: Turns async fn intro(view: View) { .. } into fn intro() -> SceneDef.

Crate oxframe

Crate oxframe Copy item path

§oxframe

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate oxframe