path: root/README

Quickly jump sections of this text by searching forward/reverse for ---


---


 Overview:

      rototiller implements a corpus of software-rendered graphics
    rendering 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 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 <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:

        `./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.

      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 <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, 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