Quickly jump sections of this text by searching forward/reverse for --- --- Overview: rototiller implements a corpus of software-rendered real-time graphics rendering modules, integrated into a single program. For a sample of what sort of outputs rototiller produces, a YouTube playlist of short captures may be found here: https://www.youtube.com/playlist?list=PLIA5njm7IjTJlVkKaEUYpbR-Ka7f2Fuuk It can be used as a static library (libtil.a) embedded in other programs, or it can be used as a standalone CLI tool for displaying stuff realtime via libdrm and/or SDL2. If you wish to see some eye candy, just build it in the conventional autotools project fashion: `./bootstrap; mkdir build; cd build; ../configure; make` If successful, run build/src/rototiller with no arguments for an interactive dialog to choose what to see. You can just smash a bunch for defaults and it will probably work. You can also just pass "--defaults" on the command-line to achieve the same thing: `./build/src/rototiller --defaults` If you wish to hack on rototiller modules see HACKING.txt. See https://rototiller.pengaru.com for more information, including videos, and screenshots. The current rototiller source is browsable on the web @ https://git.pengaru.com/cgit/rototiller/.git or the github mirror @ https://github.com/vcaputo/rototiller/ Everything below pertains to the CLI `rototiller` program, but much will probably overlap with anything utilizing libtil.a. --- Modules: The list of currently available modules is found by running the CLI tool `rototiller` without any flags. This enters an interactive setup mode, beginning with selecting the module to use from a list. Here's what's output as of writing this document: ``` $ build/src/rototiller /module: Renderer module: 0: blinds: Retro 80s-inspired window blinds (threaded) 1: checkers: Checker-patterned overlay (threaded) 2: compose: Layered modules compositor 3: drizzle: Classic 2D rain effect (threaded (poorly)) 4: flow: 3D flow field (threaded) 5: flui2d: Fluid dynamics simulation in 2D (threaded (poorly)) 6: julia: Julia set fractal morpher (threaded) 7: meta2d: Classic 2D metaballs (threaded) 8: mixer: Module blender (threaded) 9: moire: 2D Moire interference patterns (threaded) 10: montage: Rototiller montage (threaded) 11: pixbounce: Pixmap bounce (threaded) 12: plasma: Oldskool plasma effect (threaded) 13: plato: Platonic solids rendered in 3D 14: ray: Ray tracer (threaded) 15: rkt: GNU Rocket module sequencer 16: roto: Anti-aliased tiled texture rotation (threaded) 17: rtv: Rototiller TV 18: shapes: Procedural 2D shapes (threaded) 19: snow: TV snow / white noise (threaded) 20: sparkler: Particle system with spatial interactions (threaded (poorly)) 21: spiro: Spirograph emulator 22: stars: Basic starfield 23: strobe: Strobe light (threaded) 24: submit: Cellular automata conquest game sim (threaded (poorly)) 25: swab: Colorful perlin-noise visualization (threaded) 26: swarm: "Boids"-inspired particle swarm in 3D 27: voronoi: Voronoi diagram (threaded) 28: blank: Blanker (built-in) 29: none: Disabled (built-in) 30: noop: Nothing-doer (built-in) 31: ref: Context referencer (built-in) Enter a value 0-31 [17 (rtv)]: ``` Most modules are simple rendering modules, implementing a single real-time graphics algorithm. Some are more complex "composite" or "meta" modules, which play more of a compositing or orchestrating role, utilizing other modules as unwitting participants in a larger production. At this time, rtv, rkt, compose, mixer, and montage, are the primary compositing/meta modules. The default module selected by simply pressing at the list above's prompt, or running with "--defaults", is rtv. This module cycles through randomly configured modules on a regular interval. The participating modules are configurable via its channels= setting. The default is channels=compose, which results in a huge variety of randomly configured compositions pulling from all available modules. This is a good way to see what's available in rototiller in a hands-off, automated fashion. Shortening the rtv channel durations, e.g. duration=1,context_duration=1 as rtv settings can make it more entertaining by increasing the pace. Other modules sit in a sort of middle-ground between the purely meta/composite, and implementing a graphics algorithm of their own. This is due to their use of other modules as a sort of brush within their own rendering. Some examples of these include roto and checkers, which both support optional fill_module= settings for drawing an aspect of their output using another module. The montage module kind of straddles the boundary between these and the purely meta/composite modules, due to the simplicity of its tiled layout and its output being otherwise entirely determined by other modules. At the bottom of the list above, there's a few entries labeled (built-in). These are basic low-level modules that don't really implement anything aesthetically interesting or particularly substantial, but should always be present in libtil builds. They're not generally interesting to use, unless testing things as a developer, or in composing larger works. The ref module in particular plays an important role in combination with rkt. When starting rototiller, the top-level module to use may be specified via the "--module=" flag. e.g. `rototiller --module=roto`. For information on how modules are implemented, see HACKING.txt. --- Execution: The CLI UX is heavily biased towards module developers iterating on and experimenting with their creations. As a result it's all rather text/shell-centric, and works best with proficiency at quickly editing shell command-lines in-situ. If you're not familiar with your shell's command-line editing features, it might be quite frustrating and cumbersome to work with. For me personally, GNU bash in vi-mode (anything readline-based should offer this) makes quick work of editing rototiller command-lines. YMMV All rototiller flags are of the GNU long-form style prefixed by "--", there are no short "-" variants. They also expect a trailing "=" separator if they accept a parameter, a space separator is not supported. e.g. "--video=sdl" is valid, but "--video sdl" is not. To see what flags are currently supported, there is a "--help" flag which prints a summary: ``` $ build/src/rototiller --help Run without any flags or partial settings for interactive mode. Supported flags: --defaults use defaults for unspecified settings --go start rendering immediately upon fulfilling all required settings --help this help --module= module settings --print-module-contexts print active contexts on-stream to stdout --print-pipes print active pipes on-stream to stdout --seed= seed to use for all PRNG in hexadecimal (e.g. 0xdeadbeef) --title= title to use where applicable (e.g. window title) --video= video settings ``` When you run rototiller without any flags, it enters an interactive setup dialog mode, as shown in the Modules section. You can skip this by specifying "--defaults" to automatically accept all defaults, the equivalent of pressing at every prompt the interactive setup would have presented. When you specify some flags, but omit others, without "--defaults", the interactive setup dialog will be performed for only what's missing. This is done on a granular, per-setting basis, not per-flag. Flags like "--module=" and "--video=" accept variadic, value-dependent settings in their argument. Specifying "--video=sdl" for instance, partially specifies the video settings in that it says what fb backend to use (sdl), but no settings for that backend. Without "--defaults" this results in an interactive dialog for specifying sdl's needed settings: ``` $ build/src/rototiller --module=blank --video=sdl /video/sdl/fullscreen: SDL fullscreen mode: 0: off 1: on Enter a value 0-1 [0 (off)]: /video/sdl/size: SDL window size [640x480]: Configured settings as flags: --seed=0x64f9cb30 '--module=blank' '--video=sdl,fullscreen=off,size=640x480' Press enter to continue, add --go to skip this step... ``` In the above example, was pressed at the two setting prompts accepting the defaults for "fullscreen=off" and "size=640x480". If the command-line had specified "--video=sdl,size=300x300", only the "fullscreen" setting would have been asked about interactively, in lieu of "--defaults". The same thing applies to "--module=", any settings omitted that the module wants will be asked for, in lieu of "--defaults". Before rototiller proceeds after completing the setup phase, it normally waits for you to press at a prompt showing the completed settings being used, in CLI argument format, as shown above after "Configured settings as flags". This provides an opportunity for review, copy-and-paste for saving into a script or pasting into another command-line, or simply a convenient log sitting in scrollback should you need to reproduce the invocation. Suppress this review prompt by specifying "--go". The complete settings will still be shown, just without the wait. Note that whatever is shown under "Configured settings as flags:" should always be comprehensive and reproduce the same results. If placing those in wrapper scripts, by not adding "--defaults", it should never enter an interactive setup mode unless new settings were introduced in a newer build of rototiller. This is useful for detecting when something relevant changes, so in scripted invocations it's useful to not use "--defaults". One power of this granular per-setting interactive fallback is you can always just strip things off an existing invocation to receive guidance on changing the stripped parts to something else. It's especially useful during the development/creative process to use a partially specified "--module=" flag, with some settings present, but the ones you're experimenting with absent, then just keep re-running from the shell history the same underspecified invocation. You can also utilize the "rtv" module to automate the process of exploring a module's possibility space by specifying the module of interest as the sole "channels=" argument, since rtv randomizes settings on every channel switch. Its "log_channels=on" mode is useful in keeping track of which permutation you're looking at, and is printed in the same CLI-appropriate format as "Configured settings as flags:" shows. --- Sequencing: With the addition of the "rkt" module rototiller now integrates with GNU Rocket[0] for supporting sequencing of variables that have been exposed by modules as "taps". These taps show up in a Rocket Editor as tracks you can control on a timeline, for easily choreographing what's happening visually in a convenient, tracker-style GUI[1]. This opens up the possibility of using rototiller as a sort of demo[2] engine, where the rendering modules are composed and sequenced via the rkt module. For now, your demo would then be a .bat/.sh wrapper containing the rototiller incantation for establishing all the scenes via rkt settings, accompanied by Rocket tracks on the filesystem exported as part of the Rocket Editor sequencing process. You can explore this interesting space by simply running with "--module=rkt". It will by default attempt to connect to the Rocket Editor on localhost, as well as listen for telnet connects on port 54321. The Rocket Editor is responsible for sequencing the taps, one of which is the scene selection track, treated as an integer index into the active scenes. The telnet interface is what's currently offered for interactively creating and editing scenes, which you can access via `telnet localhost 54321`. When you trigger an export from the Rocket Editor, rototiller, via the rkt module, will export the track data into a directory named by rkt's "base=" setting (default is rkt). Note this does not trigger saving the rototiller incantation needed for reproducing the scenes. That command-line is found using the telnet interface, and must be copy-and-pasted into a .sh/.bat wrapper to accompany the exported track data and rototiller binary, to produce a reproducible work. Also note that when you trigger an export from the Editor, it's only instructing the Demo to dump the binary form, Demo-native tracks, local to the Demo. These aren't usable by the Editor to import for future editing, for that you want to Save the tracks with the Editor, which will save an Editor-native format the Editor can load and edit, local to the Editor. These are GNU Rocket-isms, and take some getting used to. This area of rototiller is still very experimental, and GNU Rocket needs some work before it's a better, more polished/ergonomic experience, which I am working towards with upstream. There is also a need for music integration. I have an experimental SchismTracker branch[3] integrating GNU Rocket support that already mostly works. I've also already landed upstream changes to RocketEditor[4] supporting multiple GNU Rocket clients, enabling having both SchismTracker and rototiller (via rkt) connected to RocketEditor simultaneously. The current Rocket "row" stays synchronized across the three of them when playing, moving the cursor in Schism moves the cursor in RocketEditor and vice-versa when editing. The main remaining piece here is to get audio support sorted out in rototiller, and some music playback modules, contributions welcome. --- [0] GNU Rocket: https://github.com/rocket/rocket [1] C/OpenGL RocketEditor: https://github.com/emoon/rocket [2] Demos: https://en.wikipedia.org/wiki/Demo_scene [3] Experimental SchismTracker GNU Rocket support: https://github.com/vcaputo/schismtracker/tree/gnurocket [4] RocketEditor, the first GNU Rocket editor supporting multiple clients: https://github.com/emoon/rocket/pull/165