KramaFrame

A simple, generic, and flexible keyframe animation library for Rust.

KramaFrame provides a straightforward way to manage and update multiple animations, map their progress to value ranges, and apply various easing functions for smooth and dynamic transitions.

Features

• Manage multiple animations using string-based class names and numeric IDs.
• A rich set of built-in easing functions:
  • Linear
  • EaseIn, EaseOut, EaseInOut
  • Steps(n) for stepped animations
  • Custom CubicBezier curves
• Generic over time (TRES) and progress (PRES) data types for maximum flexibility.
• Easily map animation progress (from 0.0 to 1.0) to any numerical output range.
• Play animations forwards or in reverse.
• Update all active animations with a single call in your game or application loop.

Getting Started

Add kramaframe to your project's Cargo.toml:

[dependencies]
kramaframe = "0.1.0" # Replace with the latest version

Or, add it via the command line:

cargo add kramaframe

Usage

Here's a basic example of animating a value from 80 to 100 over a set duration.

use kramaframe::{BTclasslist, BTframelist, KramaFrame, keyframe::KeyFrameFunction};

fn main() {
    // 1. Create a new KramaFrame instance.
    // The type parameters define the storage for animation classes and instances.
    // Here, BTframelist<_, i32> uses a default time representation (f64) and i32 for progress.
    let mut kramaframe: KramaFrame<BTclasslist, BTframelist<_, i32>> = KramaFrame::default();

    // 2. Define an animation "class" with an easing function.
    // We'll call it "animation1" and use Linear easing for a constant speed.
    kramaframe.extend_iter_classlist([("animation1", KeyFrameFunction::Linear)]);

    // 3. Create a specific instance of the animation.
    // We give it a unique ID (1) and a duration (1.0 in abstract units).
    kramaframe.insert_new_id("animation1", 1, 1.0);

    // 4. Start the animation. This sets its progress to the beginning.
    kramaframe.restart_progress("animation1", 1);

    // 5. In your application's update loop, advance the animation time.
    println!("--- Forward Animation ---");
    for _ in 0..=120 {
        // Update all animations by a delta time.
        // Here, we simulate 120 frames for a total duration of 1.0.
        kramaframe.update_progress(1.0 / 120.0);

        // 6. Get the current animated value.
        // We map the animation's progress (0.0 to 1.0) to a target range (80.0 to 100.0).
        let progress = kramaframe.get_progress_f32("animation1", 1).unwrap_or(0.0);
        let value = kramaframe.get_value_byrange_inclusive("animation1", 1, 80f32..=100f32);

        println!("progress= {:.2}, value = {:.2}", progress, value);
    }

    // 7. You can also reverse the animation.
    kramaframe.reverse_animate("animation1", 1);

    println!("\n--- Reverse Animation ---");
    for _ in 0..=120 {
        kramaframe.update_progress(1.0 / 120.0);
        let progress = kramaframe.get_progress_f32("animation1", 1).unwrap_or(0.0);
        let value = kramaframe.get_value_byrange_inclusive("animation1", 1, 80f32..=100f32);

        println!("progress= {:.2}, value = {:.2}", progress, value);
    }
}

Easing Functions (KeyFrameFunction)

KramaFrame uses KeyFrameFunction to control the rate of change of an animation, allowing for more natural and interesting motion.

Available Functions

• KeyFrameFunction::Linear: Constant speed.
• KeyFrameFunction::EaseIn: Starts slow, then accelerates.
• KeyFrameFunction::EaseOut: Starts fast, then decelerates.
• KeyFrameFunction::EaseInOut: Starts and ends slow, with acceleration in the middle.
• KeyFrameFunction::Steps(n): Divides the animation into n discrete, instantaneous steps.
• KeyFrameFunction::new_cubic_bezier_f32(x1, y1, x2, y2): Defines a custom animation curve using Cubic Bezier control points, similar to CSS cubic-bezier().

Example

You can define multiple animation classes, each with its own easing function.

use kramaframe::{KramaFrame, keyframe::KeyFrameFunction, keylist::KeyList};

let mut kramaframe = KramaFrame::default();

// Define different animation classes
kramaframe.extend_iter_classlist([
    ("linear", KeyFrameFunction::Linear),
    ("easein", KeyFrameFunction::EaseIn),
    ("easeinout", KeyFrameFunction::EaseInOut),
    ("bounce", KeyFrameFunction::new_cubic_bezier_f32(0.0, 1.26, 1.0, -0.79)),
    ("staircase", KeyFrameFunction::Steps(5)),
]);

// Create instances for each animation class with a duration of 1.0
kramaframe.insert_new_id("linear", 1, 1.0);
kramaframe.insert_new_id("easein", 1, 1.0);
// ... and so on for the other classes

// In your update loop, you can get values for each:
kramaframe.update_progress(1.0 / 60.0); // ~60 FPS

let linear_val = kramaframe.get_value_byrange("linear", 1, 0..100);
let easein_val = kramaframe.get_value_byrange("easein", 1, 0..100);

println!("Linear: {}, EaseIn: {}", linear_val, easein_val);

More Examples

You can find more detailed examples in the /examples directory of the repository:

• iterrange.rs: A complete, runnable version of the basic usage example.
• allkeyframe.rs: Demonstrates and visualizes all available KeyFrameFunction types.

License

This project is licensed under

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

TODO:

• Add more examples
• no_std support
• ... can be more from commit.