-*- mode: org; mode: visual-line; -*-

shado

The shado monome rendering library in Lua for the monome norns.

shado is a compositing and sprite library for the monome and arc devices on the monome norns. It is based on an earlier release written in Java as an OSC subsystem; this version is in Lua to run on norns natively.

To get a sense for what’s achievable in shado (as of ten years ago with first-generation monome kit), take a look at this video.

The file README.MANUAL will eventually be the manual for shado; for now, it contains an explanation of the shado architecture - quite possibly, along with the examples, just about enough to start writing shado “programs”.

Testing Setup

Install luarocks (the Lua package manager) and luaunit (the unit testing library). On norns:

sudo apt-get install luarocks
sudo luarocks install luaunit

Note: the command-line Lua on norns is currently version 5.1. (You might be able to upgrade it.) The Lua used for scripting is 5.3. The unit tests should work under 5.1, although that version is under-tested.

To set up the tests on macOS (with Homebrew):

brew install luarocks
luarocks install luaunit

We also use the library inspect for some debugging in the tests; install as above.

Unit Testing

From the directory containing shado (on the norns that would be /home/we/dust/code), test with:

lua shado/test-all.lua

Documentation

We’ve used LDoc, which can be cleanly installed with:

[sudo] luarocks install ldoc

From the main shado directory, a ldoc -v . reads from config.ld and generates docs in doc.

Comparison with Java shado

• All coordinates have origin or top-left at (1, 1) (Lua-style) rather than (0, 0) (every other language in the world-style).
• Rename: ViewPort is now called Mask, which is a bit snappier and more indicative of what it actually does.
• In the Java implementation, press() is a boolean method returning true for press handled, false otherwise. Since Lua is more dynamic, we can have press-handled as the default by omitting any return statement - i.e., a result of nil implies handled. In fact, false is the only return value to mark a press as not handled.