Programming animations for Ledcat is simple! The interface has been designed to be generic, language agnostic, easy to understand and allow reuse of programs across projects/displays.
All you have to do is create a program that, for each pixel in your display, outputs three bytes for each sub-pixel in RGB order. Ledcat knows how to distinguish between frames because it knows how many byte a frame contains.
The simplest way of offering animation data to Ledcat is through it's STDIN:
perl -e 'print "\xff\x00\x00" x 30' | ledcat --geometry 30 <other arguments...>It is also possible to offer data to Ledcat by using one or more FIFO's.
--exit never is best used as well, since it tells Ledcat to retry reading
when you restart the animating program.
mkfifo /tmp/ledcat-01 /tmp/ledcat-02 /tmp/ledcat-03
ledcat --input /tmp/ledcat-01 /tmp/ledcat-02 /tmp/ledcat-03 --exit never <other arguments...>With this setup, Ledcat will prefer frames from the rightmost FIFO which can be read from.
Besides the --geometry option, it is also possible to set the display
geometry via the LEDCAT_GEOMETRY environment variable. This allows programs
to be reused between displays with differing geometry without having to specify
the geometry twice. Both options expect an integer for 1D geometry and two
integers separated by an x for 2D.
It is possible to modify which pixel goes where in the output. Accidentally mounted your display upside down? No problem. Head over to the transposition doc for more details.
By default, Ledcat will just read frames from it's input and output them immediately. To prevent hogging system resources with a busy loop, you should include a sleep in your animations to sync up with the desired frame rate.
This approach is recommended for animations which should visualize another data source in real time, like an audio signal.
If there are no real time requirements, it is recommended to leave out sleeps
in your program and set the desired frame rate with --framerate. Ledcat read
from it's input when needed and cause the animation program to block.
When you're using Ledcat like this (or with a network socket), it is a valid use case to terminate the animating program to start a new one. It is possible that a part of some frame that was produced by the previous animation is still stuck in Ledcat's input buffers.
But fear not! Ledcat will automatically clear these leftovers if you wait for a
while. If we would not, we would end up with shifted frames and colors in the
output. The timeout is based on the frame rate set with --framerate,
--clear-timeout or a default of 100ms. You should wait this amount before
writing new animations.