Skip to content

Rust camera and animation values

These services use the installed C core. They need no graphics backend. They do not load graphs or update a process automatically. Context-owned camera identities and process selection are available below.

use malvado::camera::Camera;
let mut camera = Camera::new(0.0, 0.0, None)?;
camera.center((200.0, 150.0), (800, 600))?;
let screen = camera.project((210.0, 160.0), (0.0, 0.0))?;
assert_eq!(screen, (410.0, 310.0));
# Ok::<(), malvado::Error>(())

Camera owns a copied native value. Copying it creates an independent camera. None in the constructor uses the full window. An explicit Viewport must have positive dimensions. Coordinates must be finite and within FLT_MAX / 64. Projection applies world minus camera minus local scroll plus viewport origin. clip intersects the viewport, optional region, and screen without projection; it returns None for an empty intersection. Screen dimensions must be positive. Invalid inputs return Error::InvalidArgument and preserve camera state. No allocation or cleanup is required. The game controls when to center or move its camera; these values do not add an update loop.

game.main_camera()? returns the canonical context-owned main camera. game.create_camera(value)? registers a copied Camera value and returns a CameraHandle. Clones share identity; snapshot() returns an independent Camera copy. replace, set_position and move_by update native values.

use malvado::{Game, Error, camera::{Camera, Selection}};
let game = Game::new()?;
let actor = game.spawn(Default::default(), |p| async move {loop {p.frame().await;}})?;
let view = game.create_camera(Camera::new(10.0, 20.0, None)?)?;
actor.set_camera(Selection::Explicit(view.clone()))?;
view.move_by(1.0, 2.0)?;
assert_eq!(actor.resolve_camera()?.position(), (11.0, 22.0));
view.close()?;
assert!(matches!(actor.resolve_camera(), Err(Error::NotFound)));
actor.set_camera(Selection::Screen)?;
assert_eq!(actor.resolve_camera()?.position(), (0.0, 0.0));
# Ok::<(), Error>(())

Use Selection::Main, Screen or Explicit(handle) with set_camera. camera_selection copies identity, including a closed explicit selection. resolve_camera copies the effective value; a closed selected view returns NotFound and hides that process in the native process drawing pass. Foreign context selection returns ForeignContext without changing the current selection. Main cannot be closed (InvalidArgument). Explicit close is idempotent. After engine shutdown camera operations return Closed.

The context owns registrations until close or shutdown. Dropping a handle does not close the view, so selected processes keep their camera when a temporary handle leaves scope. Use close to release an unneeded explicit view. Handles stay on the owner thread, while copied Camera snapshots remain independent. No window is needed for these services. Registration/selection never ticks, starts a scheduler, follows a target or changes process world coordinates.

frame.process_graphics(&engine)? now applies native selection and viewport. It composes and restores host clip/scroll; the default full-window case remains batched. Process region/scroll use the native descriptors below. The same pass draws retained process commands. Immediate frame drawing is still explicit; use a snapshot’s project/clip operations for custom drawing. Lua-owned and borrowed camera userdata use the same core; see the native ownership contract.

Follow::update_handle(&camera, window_size)? applies an existing Follow value to a registered camera. Both identities must belong to the same context. Call it after the native tick, as for copied cameras. Errors preserve native camera values; a closed camera returns NotFound even for an inactive follower. Manual camera writes do not clear the separate Follow object: call clear() to stop.

camera_registry.rs verifies identity, aliases versus snapshots, explicit close, main protection, selection/reset, foreign/dead/closed errors, follow updates and context cleanup with open cameras. Owner-thread and runnable doctests check the public usage. Native and Rust pixel fixtures verify main/explicit/screen views, closed-view hiding, viewport boundaries and host scope composition. Installed core/graphics consumers exercise registered selection through relocated SDKs.

Use handle methods to assign copied native descriptors. No window or tick is needed to read values or compose the effective view.

use malvado::{Game, camera::Viewport};
let game = Game::new()?;
let actor = game.spawn(Default::default(), |p| async move { loop { p.frame().await; } })?;
actor.set_scroll((3.0, 4.0))?;
actor.set_region(Some(Viewport { x: 10, y: 20, width: 30, height: 40 }))?;
assert_eq!(actor.view_offset()?, (-3.0, -4.0));
assert_eq!(actor.view_clip(None, (100, 80))?, actor.region()?);
# Ok::<(), malvado::Error>(())

set_region(None) clears clipping beyond the selected camera viewport. region() returns an independent optional value. Dimensions must be positive; origins can use the full i32 range. set_scroll((x, y)) copies finite f32 values with absolute values at most f32::MAX / 16; scroll() reads them back. Zero is the default and reset value. Invalid setters return InvalidArgument without changing stored state.

view_clip(host, screen) intersects camera viewport, process region, optional host clip and screen. Empty intersections return None. Screen and clip dimensions must be positive. view_offset() projects world origin through the selected camera and local scroll; host scroll stays separate. Projection uses the native numeric limits. A closed selected camera returns NotFound from composition, while stored descriptors remain accessible. Dead handles return NotFound; after engine shutdown they return Closed.

frame.process_graphics(&engine) applies these values immediately, including for frozen processes. It composes and restores host clip/scroll. These methods never change process world position, colliders, status or scheduling. See the shared native contract.

process_view.rs checks defaults, copied/shared handle values, frozen state, composition, boundary/error atomicity and dead/closed lifetimes. The graphics fixture checks local scroll, region/host intersections, host scope restoration, offscreen hiding and reset pixels. Installed core and graphics consumers use all six safe methods. The runnable example also runs as a doctest.

Follow::new(&actor)? selects a live context-bound handle without moving a camera. Call follow.update(&mut camera, (width, height))? after the existing engine tick. It reads native x/y, uses viewport centering and returns true while the target exists. Sleep and freeze do not stop explicit follow updates. When the target ends, update clears the target, returns false and preserves the last camera position. It does not tick or poll any future.

use malvado::{Game, camera::{Camera, Follow}};
let mut game = Game::new()?;
let actor = game.spawn(Default::default(), |p| async move {
loop { p.frame().await; }
})?;
actor.set_position(100.0, 80.0)?;
let mut camera = Camera::new(0.0, 0.0, None)?;
let mut follow = Follow::new(&actor)?;
game.tick()?;
assert!(follow.update(&mut camera, (100, 80))?);
assert_eq!(camera.position(), (50.0, 40.0));
# Ok::<(), malvado::Error>(())

Follow owns a handle, not the target process or its resources. Creating it from a dead/closed handle returns NotFound/Closed. Invalid dimensions or out-of-range geometry return InvalidArgument; errors preserve camera and follow state. After engine shutdown, an active update returns Closed. Call clear() to stop and release the handle. A cleared follower returns false on update with positive dimensions, even after engine shutdown. is_following() reports whether a target remains selected, before the next update checks its liveness.

Camera values remain independently copied. Follow state is separate: moving or centering a Rust camera does not clear it. Call clear() when switching to manual control, or replace the follower with Follow::new(&other)? to retarget. Followers stay on the owner thread. Independent followers can select the same target without retaining process state. Context-owned camera identity and process selection are available above; following still uses the explicit host update flow.

camera.rs tests follow the C/Lua golden trace and check viewport behavior, sleep/freeze, invalid geometry/dimensions, independent follow state, explicit clear, closed engines and natural process cleanup. A compile-fail doctest checks thread ownership; a runnable doctest checks the tick/update sequence. The installed probe checks mv_camera_follow_step; the relocated external consumer exercises real follow centering without source-tree SDK paths.

use malvado::animation::{Animation, Frame};
let animation = Animation::new(&[
Frame { graph_id: 1, duration_us: 100_000 },
Frame { graph_id: 2, duration_us: 100_000 },
], true)?;
let mut playback = animation.playback();
// Call once in the game's existing simulation tick.
let sample = playback.advance(60)?;
assert_eq!(sample.graph_id, 1);
# Ok::<(), malvado::Error>(())

The definition copies 1..8192 frames into native storage and frees it on drop. Graph IDs must be positive; durations are 1..3600000000 microseconds. Invalid frames return InvalidArgument; native allocation failure returns OutOfMemory. Graph IDs do not load or retain graphical assets. Definitions stay on their creating thread and can be held by the existing Resource<Animation> manager.

sample(elapsed_us) samples without changing state. Each playback() starts at zero and borrows its definition, so it cannot outlive the native allocation. advance(rate) calls the native fixed-tick accumulator; rates are 1..1000000. Fractional microseconds carry across ticks without drift. Call reset() before changing rate. Invalid rates leave state unchanged. Looping playback wraps; non-looping playback holds its last frame. This service does not assign a graph or advance automatically when a process runs, sleeps, or freezes.

actor.set_animation_clock(&animation)? retains the definition in the native process and resets its playback clock. The original Animation can be dropped immediately. actor.animation_clock()? returns a copied ProcessClock with elapsed_us and sample, or None when no clock is attached. Cloned handles observe the same state. clear_animation_clock() stops it without changing the graphic. Set always resets, including reassignment of the same definition.

The clock uses Game’s 60 Hz native ticks. Process FPS controls async activation, not animation speed. Sleep and freeze pause without catch-up. Assignment during a tick skips that tick. Return, kill and context shutdown release the retained definition. Dead handles return NotFound; closed contexts return Closed. Failed operations preserve the clock. No borrowed native state escapes.

use malvado::{Game, Error, animation::{Animation, Frame}};
let mut game = Game::new()?;
let actor = game.spawn(Default::default(), |p| async move {
loop { p.frame().await; }
})?;
let animation = Animation::new(&[
Frame { graph_id: 7, duration_us: 50_000 },
Frame { graph_id: 42, duration_us: 50_000 },
], true)?;
actor.set_animation_clock(&animation)?;
drop(animation);
game.tick()?;
assert_eq!(actor.animation_clock()?.unwrap().elapsed_us, 16_666);
actor.clear_animation_clock()?;
# Ok::<(), Error>(())

Graph IDs remain metadata. This API does not load textures, select a process image or draw. Use the sampled ID with an explicit host mapping. Automatic image selection uses sprite animations. A bound visual animation owns its clock; standalone clock assignment/clear returns Busy until that graph is replaced or cleared. This service adds no scheduler or timer.