Analog TV Tuning Effect with ESP_8_BIT_Composite
After addressing my backlog of issues with the ESP_8_BIT_Composite video output library, I felt that I have "eaten my vegetables" and earned some "have a dessert" fun time with my own library. On Twitter I saw that Emily Velasco had taken a programming bug and turned it into a feature, and I wanted to try taking that concept further.
When calling Adafruit GFX library's drawBitmap() command, we have to pass in a pointer to bytes that make up the bitmap. Since that is only a buffer of raw bytes, we also have to tell drawBitmap() how to interpret those bytes by sending in dimensions for width and height. If we accidentally pass in a wrong width value, the resulting output would be garbled. If I had seen that behavior, I would have thought "Oops, my bad, let me fix the bug" and moved on. But not Emily, instead she saw a fun effect to play with.
This is pretty amazing, using the wrong width value messes up the stride length used to copy image data, and it does vaguely resemble tuning an analog TV when it is just barely out of horizontal sync. Pushing the concept further, she added a vertical scrolling offset to emulate going out of vertical sync.
However, applying the tuning effect to animations required an arduous image conversion workload and complex playback code. I was quite surprised when I learned this, as I had wrongly assumed she used the animated GIF support I had added to my library. In hindsight I should have remembered drawBitmap() was only monochrome and thus incompatible.
Hence this project: combine my animated GIF support with Emily's analog TV tuning effect in order to avoid tedious image conversion and complex playback.
I started with my animated GIF example, which uses Larry Bank's AnimatedGIF library to decode directly into ESP_8_BIT_Composite back buffer. For this tuning effect, I needed to decode animation frames into an intermediate buffer, which I could then selectively copy into ESP_8_BIT_Composite back buffer with the appropriate horizontal & vertical offsets to simulate tuning effect. Since I am bypassing drawBitmap() to copy memory myself, I switched from the Adafruit GFX API to the lower-level raw byte buffer API exposed by my library.
For my library I allocated the frame buffer in 15 separate 4KB allocations, which was a tradeoff between "ability to fit in fragmented memory spaces" and "memory allocation overhead". Dividing up buffer memory was possible because rendering is done line by line and it didn't matter if one line was contiguous with the next in memory or not. However, this tuning effect will be copying data across line boundaries, so I had to allocate the intermediate buffer as one single block of memory.
My original example also asked the AnimatedGIF library to handle the wait time in between animation frames. However, since that delay could vary in an animation, and I have a user-interactive component. In order to remain responsive to knob movement faster than animation frame rate, I took over frame timing in a non-blocking fashion. Now every run of loop() reads the potentiometer knob position and update horizontal/vertical offsets without having to wait for the next frame of the animation, resulting in more immediate feedback to the user.
Animated GIF Tuner Effect with Cat and Galactic Squid is publicly available on GitHub.