summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README357
1 files changed, 296 insertions, 61 deletions
diff --git a/README b/README
index ae4b2f7..fce07fc 100644
--- a/README
+++ b/README
@@ -1,82 +1,317 @@
+Quickly jump sections of this document by searching forward/reverse for ^-
-rototiller implements a corpus of software-rendered graphics modules,
-integrated into a single program.
-It can be used as a static library (libtil.a) embedded in other programs,
-or it can be used standalone to display stuff realtime via libdrm and/or
-SDL2.
+---
+
+
+ Overview:
+
+ rototiller implements a corpus of software-rendered graphics
+ rendering modules, integrated into a single program.
-If you wish to see some eye candy, just build it in the conventional
-autotools project fashion:
+ 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.
-`./bootstrap; mkdir build; cd build; ../configure; make`
+ If you wish to see some eye candy, just build it in the conventional
+ autotools project fashion:
-If successful, run build/src/rototiller with no arguments for an
-interactive dialog to choose what to see. You can just smash enter a bunch
-for defaults and it will probably work. You can also just pass --defaults
-to achieve the same thing non-interactively.
+ `./bootstrap; mkdir build; cd build; ../configure; make`
-If you wish to hack on rototiller check out HACKING.txt in this tree.
+ If successful, run build/src/rototiller with no arguments for an
+ interactive dialog to choose what to see. You can just smash <enter> a
+ bunch for defaults and it will probably work. You can also just pass
+ "--defaults" on the command-line to achieve the same thing:
-See https://rototiller.pengaru.com for more information.
+ `./build/src/rototiller --defaults`
-Everything below is out of date vestigial stuff from simpler times.
+ If you wish to hack on rototiller modules see HACKING.txt.
--------------------------------------------------------------------------------
+ See https://rototiller.pengaru.com for more information, including
+ videos, and screenshots.
+
+ Everything below pertains to the CLI `rototiller` program, but much
+ will probably overlap with anything utilizing libtil.a.
-rototiller is, rendered entirely in software:
- drizzle: a 2D raindrops visualization
- flui2d: a 2D fluid dynamics simulation
- julia: a morphing Julia set (fractal)
- meta2d: a 2D metaballs effect
- montage: a montage of modules meta-module
- pixbounce: a 2D bouncing pixmap demonstration
- plasma: an oldskool "plasma" effect
- plato: a basic 3D Platonic solids display
- ray: a multi-threaded ray tracer
- roto: a simple fixed-point tiled texture rotation
- rtv: a "Rototiller TV" slideshow meta-module
- snow: a "TV snow" / white noise effect
- sparkler: a fireworks-like particle system with spatial interactions
- spiro: a Spirograph simulator
- stars: a starfield simulator
- submit: a 2D cellular automata game sim
- swab: a colorful perlin-noise visualization
- swarm: "Boids"-inspired particle swarm in 3D
---
-This is a quick little graphics hack I put together to experiment with libdrm
-and this "dumb buffer" thingy David Airlie added to the kernel back in 2011.
-If you're like me and miss the pre-KMS days of functional SVGAlib on linux
-where we could write purely software-rendered graphics toys like demos that
-were still beautiful and synchronized to vertical retrace without any tearing
-or flickering, there is cause to rejoice.
+ 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
+ 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 <enter> 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 <enter> 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, <enter> 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 <enter> 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 GUI[1] tracker-style interface.
+
+ 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. 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 a
+ Editor-native format the Editor can load and edit.
+
+ 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.
-Using libdrm and these two ioctls:
-DRM_IOCTL_MODE_CREATE_DUMB
-DRM_IOCTL_MODE_MAP_DUMB
+ 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.
-We can then mmap into our address space a 32bpp buffer that can be drawn to
-while off-screen, and submitted to the gpu for displaying in a page-flipping
-fashion, synchronized to the vertical retrace. It's revisiting the 90s, it's
-VESA 2.0 linear frame buffers but actually supporting all our crazy native
-resolutions and abundant memory for 32bpp with page flipping.
+ The main remaining piece here is to get audio support sorted out in
+ rototiller, and some music playback modules, contributions welcome.
-In my testing so far, this seems to work without even requiring root.
-Before you try to run these things, realize this is direct libdrm graphics,
-it's going to compete with your X/wayland server. Switch to a plain virtual
-console to run the program. You don't need to quit X, just switch away from the
-X vt so it's not visible.
+ ---
-To quit it's as simple as Ctrl-C, rototiller will otherwise run forever.
-Do not try switching back to X while rototiller is drawing, Ctrl-C it first, or
-X will get angry and exit when it tries to do drm things and can't.
+[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
-Your display may be left in an inconsistent state after exiting rototiller.
-Don't panic! Just switch virtual consoles or go back to X, graphics will be
-restored. This seems like a bug in drm to me. It's genuine SVGAlib dejavu,
-corrupt displays and all. BUCKETS OF NOSTALGIA
© All Rights Reserved