Software/net.loadbang.shado/README.MANUAL {code:none} S H A D O M A N U A L This file will eventually be a manual; for now, it's a working overview of the shado architecture and components, with some fragments of Python code which show how it works. Read in conjunction with the Python examples and the javadocs, it should be enough information to start writing shado-based applications. - THE RENDERING MODEL ------------------- shado is a compositing and sprite library for the monome, written in Java. It is designed to be driven from a lightweight scripting language such as Python, and it uses a Java OSC library to talk to the monome via the MonomeSerial program. (The Java OSC library is not yet used for input, for hysterical reasons; this will change in due course.) An application which uses shado will build structures of "frames", "blocks" and "view ports". These objects know how to present themselves to a rendering object, which generates the OSC messages for MonomeSerial. The renderer is smart enough to send incremental updates for a display, to minimise network traffic and load. The shado library doesn't have things called sprites per se, but any structure of blocks, frames and view ports can be manipulated and altered dynamically, in Python (say). If components are moved around relative to one another, or if their layering order or visibility are changed, the result is sprite-like animation. - BLOCKS ------ A block is a two-dimensional matrix of data values representing monome lights, or pixels. Each block pixel value (a type we refer to as a "lamp") can have the obvious value ON or OFF; a lamp can also have the value THRU (which means "transparent": show whatever is beneath) or FLIP (invert whatever is beneath). It is possible to render a block directly to a monome - the block is considered to be sitting on a black base, so ON and FLIP cause the lamp to light, and OFF and THRU turn it off. Here's a simple 4 x 4 square of lights (see the example code for all the details of the required import statements): outputter = OSCOutputter('localhost', 8080, 8, '/m64') renderer = Renderer(8, 8, outputter) block = Block(4, 4).fill(LampState.ON) renderer.render(block) Block(...).fill(...) sets all pixels in the block. Alternatively, single pixels can be set (via setLamp()). Block also has a constructor which takes an ASCII string representing pixel values (useful for quickly initialising those digital clock demos): block = Block('111 101 101 101 111') '0' means OFF, '1' means ON, '.' means THRU and '/' means FLIP. Each token is a row; the tokens are separated by white space. - FRAMES ------ A frame is a stack of blocks, where items at the "top" obscure, or modify, items lower down. In fact, more generally, a frame is a stack of "renderables", which may be blocks, view ports (described later), or other frames. This recursive structure allows a complex animation (say) to be constructed in a frame, and then for this frame to be moved around inside an enclosing frame. (This is how the "UFO" animation sequence works.) Unlike blocks and view ports, frames do not have dimensions; a frame's "size" can be considered to be defined by the extents of any blocks or view ports it, or its sub-frames, contain. The renderer does not care about the size of frames (or of blocks or view ports, for that matter): it knows the size of the monome it's addressing, and scans an area corresponding to the monome's width and height, asking renderables to deliver their data. (So, an obvious way to hide a block is to move it beyond the monome's coordinates; there are better ways, outlined below.) A frame renders its pixel values from the bottom to the top of its list; higher items modify what is below. Lamp values of OFF and ON obscure underlying pixels; THRU passes pixels through unchanged, FLIP inverts them. The resulting pixel values in a frame still have these four lamp values, which are then interpreted by any parent frame as part of its stack of renderables, and so on to the actual frame which is rendered. The renderer asks this outermost frame or block to "fold" lamp values to ON or OFF (i.e., render them against black) prior to transmitting them. The frame constructor has no arguments, so: f = Frame() renderer.render(f) is an easy way to clear a monome (an empty frame renders to black). Renderables are added using add(): block = Block(.....) Frame.add(block, 2, 3) This adds a renderable to the *top* of a frame, in this case offset horizontally by two pixels and vertically by three. Frame.add() returns the frame itself, allowing cascading: Frame.add(b1).add(b2) A renderable can only be added to any frame once - this is because the renderable value is used in subsequent operations like show(), hide() and top(). It is possible to get replicated tiling effects by creating multiple unique sub-frames (or view ports) over a single block, and adding these to the main frame. (There's a simple demo in "Animate.py" which does this.) A frame allows a few operation on its stack of renderables: frame.top(item): bring a renderable to the top frame.bottom(item): send a renderable to the bottom frame.hide(item): hide a renderable (make it transparent) frame.show(item): show a renderable frame.remove(item): remove a renderable from a frame And finally, some sprite action: frame.moveBy(item, dx, dy): move a renderable by this distance frame.moveTo(item, x, y): move a renderable to this location relative to the frame's origin Since the renderables might themselves be frames, all sorts of nested movement and animation is possible. In addition, hide() and show() (or, depending on style, bottom() and top()) can be used for animation: if you want to invert an entire monome, use a frame with a large Block(...).fill(LampState.FLIP) at the top; hide() and show() calls on it will invert everything. If you want to switch between a number of different patterns, create them all in advance, making sure they are all the same size and are opaque (ON or OFF values only, no THRU or FLIP) and them call frame.top() on them in sequence. (See Counter.py for an example.) - VIEW PORTS ---------- ViewPorts provide a simple way to crop blocks or (more likely) frames, useful if animated sub-frames are being tiled into a larger system. When a view port is built around a renderable (a block or frame), the result is a port onto that renderable; anything outside the port is rendered as LampState.THRU (transparent). There is no change to the coordinate system of the contents of the port. ViewPorts are also renderables, and so may be incorporated into frames, cropped in other ports, and so on. After: p = ViewPort(renderable, x, y, width, height) the renderable "p" will be the same as `renderable' for pixels whose column is between x and x+width-1, and whose row is between y and y+height-1. Outside those coordinates, the pixels of "p" will be LampState.THRU. ViewPort objects also expose properties "x", "y", "width" and "height", so that the cropping dimensions can be changed dynamically: p.x = 3 p.height = p.height - 1 - BUTTON INPUT ------------ The machinery for dealing with button presses works with the same structures as those used to drive the LEDs. Once a structure of blocks, frames and view ports has been built to generate output, button presses can be routed into those same blocks, frames and view ports. The assumption is that an application which draws some kind of animated widget with a bit of scripting code will also want to capture button presses locally in that same portion of code, with sensible local coordinates, regardless of what else might be going on in the system at the time. Here's how it works: the Block and ViewPort classes both implement an interface called IPressable in the Java world. This means they contain a method as follows: public boolean press(int x, int y, int how); The Block and ViewPort classes provide a method which does nothing; in order to respond to button presses, a Block or ViewPort must be sub-classed and this method overridden. This can obviously be done in Java, but it can also be done in Python. When a button is pressed, shado searches a tree of renderables in order, until it finds one which handles the press; once the press is handled, the search stops. If the renderable returns true from the call to press(), then it is considered to have handled the event. A Block or ViewPort can only handle a button press which falls within its coordinates; if the button press is outside the renderable's dimensions then the renderable never sees it. (This, by the way, is why Frames cannot directly intercept button presses (they are not IPressables): a Frame does not have an obvious coordinate range.) If a Block measuring (width * height) is within range of a press, it will be passed X and Y coordinates within (0, 0) and (width-1, height-1). If a ViewPort receives a press, the coordinate (0, 0) coincides with the top-left corner of the port, rather than (0, 0) in the port's coordinate system. A button press can be routed into any renderable: Block, Frame or ViewPort. (Even though a Frame cannot handle presses directly, it will pass them on to its children.) There's a class called PressManager which does this (and which also tracks on and off presses, as we describe later): f = Frame() ... manager = PressManager(f) ... manager.press(x, y, how) (A PressManager can be built over a completely different structure to the one being displayed - but in most cases you probably don't want to do that.) If the PressManager is constructed around a Block, the routing is simple: Block.press() gets called with the same coordinates that are passed in to PressManager.press() - these are presumably coming directly from the monome. Sending a press to a ViewPort is slightly more complicated. The ViewPort might accept the event (by returning true from its press() method) in which case the event is considered finished. If the ViewPort returns false, the event is routed into the ViewPort's *content* - another renderable - with the original coordinates - and the result is whatever the content renderable returns. When a press is routed to a Frame, the Frame starts calling into its stack of children in order, from top to bottom, mapping the coordinates so that each child sees (0, 0) as top-left. As soon as a child returns true, the event is over. If any child returns false, the Frame tries the next, and so on. If all children return false (or if the Frame is empty), the result is false. Note that the handling of button presses by objects bears no relation to their visibility (but only to their coordinate range). An object which has been hidden (by Frame.hide()) will still be sent press() events. A Block which is completely transparent (all cell values are LampState.THRU) will also receive press() events. There are situations where this is useful: to capture the raw coordinates of a monome's buttons regardless of the objects in a frame, just add a monome-sized transparent layer to the top and use this to deal with the press() events. Finally: a note about button presses and releases. If a button press is routed to an object deep within a visual heirarchy, then that structure can change dramatically before the button is released. For example, suppose that a Block receives a button press, and its press() method actually moves the Block within its enclosing Frame. The button release could have coordinates different to those of the press; or the release might be completely out of range of the new location of the Block. We have implemented some machinery which guarantees a fundamental property of button handling: if a renderable receives - and handles - a button press at coordinates (x, y), then it will always receive the corresponding release at the same coordinates. It does not matter if the renderable has been moved out of range of the button - or even if the renderable has been completely removed from the object heirarchy - the PressManager keeps hold of it, purely so that the press(x, y, 0) can be sent to the original recipient of press(x, y, 1). A side-effect of this is that, if an object chooses to ignore a press (by returning false from a press(x, y, 1) call) then it will never get the release call - that call will always go to the actual object which dealt with the press (if any). Another side-effect is that an object might receive multiple button-on presses at the same coordinates. If a press(0, 0, 1) event to a Block causes it to move, another button on the monome might now map to the Block's top-left, and might send a second press(0, 0, 1). In other words, it's quite possible for button-on events to be duplicated in the same location - and the release events will also be duplicated. This makes perfect sense to the PressManager so it had better make sense to your Python scripts. {code} 2008-07-20 16:37:35.0 2008-06-27 21:34:12.0