From 03ae91dda0031b6aeaf11fd5dbf7646b74d4c19b Mon Sep 17 00:00:00 2001 From: Stephen D <webmaster@scd31.com> Date: Sat, 22 Feb 2025 20:35:10 -0500 Subject: [PATCH] add readme --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..fdbd00f --- /dev/null +++ b/README.md @@ -0,0 +1,61 @@ +# rapidriter-cat + +This is a simple Rust program to animate a silly cat on the [Rapid Riter](https://github.com/gregsadetsky/rapidriteros) at the [Recurse Center](https://www.recurse.com/). I hope it also serves as a useful template. + +Aside from the meat and potatoes that actually animates the cat, it also includes a simulator for the Rapid Riter. This simulator allows viewing the frames in your terminal, or creating a gif. + +## Demo + +[Demo!!](https://peertube.scd31.com/w/8882FFZ2qgLJ8B2khbTgX9) (This is already out of date) + +But don't worry, there's also a gif! + + + +The gif is generated from Gitlab CI, so it will always be up-to-date with the code. + +## What the Rapid Riter Expects + +From the documentation: + +> implement a `next_frame` function with the signature: next_frame(frame: u16, ptr: *mut u8) -> u8 +> - first input is the current (zero-indexed) frame +> - second input is a pointer to the 456-byte array +> - return value is zero if you have more frames to render, one if you're done rendering things +> - But you only get 100 frames, don't be greedy! + +In this repo, this function lives in `lib.rs`. + +## Building + +Just run `make`. The WAT (WebAssembly Text) file will be created at `target/rapidriter-cat.wat`, which you can then upload to the Rapid Riter. + +## Simulating + +There's a simulator available by running `cargo run`. By default it will run your animation in the terminal. Alternatively, you can pass in a `-i` flag (i.e. `cargo run -- -i`) to run the simulator in interactive mode. This lets you step through frame by frame, which can be useful for ensuring everything is pixel-perfect. + +Finally, you can specify an output (`cargo run -- --out output.gif`) to create a gif of your animation. This will run at 10 FPS, just like as it does on the Rapid Riter. + +## Compile-time image munging and build.rs + +This script relies on two images, which can be found in the `src/assets` directory. At compile-time, the `build.rs` script takes in these files and turns them into a bit array which represents the image's pixels. This is then used in `lib.rs` at runtime to actually create the animation. + +Notably, the two image file names (cat and meow) are hardcoded both in `build.rs` as well as `lib.rs`. It would be nice to clean up the former to be more generic but the latter is likely always going to need to be hardcoded (but that, imo, is fine). + +## Using this project as a template + +This project handles a lot of boilerplate that you may want for your own Rapid Riter projects. As such, it may be useful as a template! + +Notably, this project provides: +- A simple build system +- Gitlab CI/CD +- Compile-time image parsing into a bit format (the exact format the Rapid Riter expects) +- A simulator + +To use this project as a template, you probably want to do the following things: +1. Change the package name in `Cargo.toml` +2. Update `build.rs` to reflect your asset names, or remove `build.rs` entirely if you have no assets +3. Update `lib.rs` to match your vision +4. Bon appetit! + +Have fun and don't forget to meow! Meow meow meow meow -- GitLab