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