ArduboyG Tutorial
This tutorial assumes you have mastered the art of rendering black and white graphics to the Arduboy using the `drawOverwrite()` and `drawPlusMask()` functions that are contained in the `Sprites` library. If you haven't got this far I recommend you master those before moving on.
History of Greyscale on the Arduboy
The production Arduboy comes with an SSD1306 screen - a monochrome screen of 128x64 pixels. Many developers have attempted to produce a grey effect by alternating images with different dithering patterns to produce a grey colour. This can be seen on earlier games, such as 'Ard-Drivin, and can be quite effective if the frame rate is fast enough.
Following the lead of what developers on the Thumby site were doing, @brow1067 developed a library for the Arduboy that uses a very high frame rate (above 150 fps) and the persistence properties of the screen to simulate both 3-shades and 4-shades of grey. The library comes with methods to render the images from PROGMEM or directly from the FX chip in multiple modes, including images with transparent backgrounds. The methods that use the FX chip are extremely useful due to the larger size of the graphics.
The following tutorial will focus on @brow1067's library and introduce advanced concepts as it progresses. This thread on the Arduboy forum describes the library in detail and is a great reference when attempting to solve problems you may face when using the library.
Getting Started
The library itself can be downloaded from @brow1067's GitHub repository here. However, I have built a stripped down sample that this tutorial references which can be downloaded here. I have focused on using only one mode - four shades of grey - but even the stripped down demo has a lot of moving parts!
Before jumping into the code, it is important to understand how the grey scale library works and to compare this to the standard Arduboy2 library.
A typical Arduboy2 program might look like this:
000 #include <Arduboy2.h>
010
020 Arduboy2 arduboy;
030 uint8_t y = 0;
040
050 void setuo() {
060 arduboy.begin();
070 arduboy.setFrameRate(60);
080 }
090
100 void loop() {
110
120 if (!(arduboy.nextFrame())) return;
130
140 arduboy.clear();
150
160 // Handle movements ..
170
180 if (arduboy.pressed(UP_BUTTON) && y > 0) {
190 y--;
200 }
210
220 if (arduboy.pressed(DOWN_BUTTON) && y < 56) {
230 y++;
240 }
250
260 // Render image at y position ..
270
280 Sprites::drawOverwrite(64, y, img, 0);
290
300 arduboy.display();
310
320 }
Let's pull that sketch apart.
At line 000 we import the standard Arduboy2 library and create an instance of it at line 020. Within the setup() function, we initalise the library and set any other parameters - such as setting the frame rate to 60 FPS, at line 070. This should all be familiar code so far.
In the loop() function, we enforce the frame rate using the standard Arduboy2 approach (line 120). If it is time to render the next frame, the screen buffer is clear at line 140 before updating the game logic, such as handling any user input, before rendering images and other graphics into the screen buffer (line 260). Finally we push the screen buffer to the actual screen at line 280 and clear the buffer ready for the next iteration.
The cycle of applying game logic, updating player positions then rendering the screen is a typical pattern for Arduboy2 games.
Compare that to the same ArduboyG library sketch (simplified):
000 #include "src/ArduboyG.h"
010 #include "src/SpritesU.hpp"
020
030 extern ArduboyGBase_Config<ABG_Mode::L4_Triplane> arduboy;
040 decltype(arduboy) arduboy;
050 uint8_t y;
060
070 void setup() {
080 arduboy.boot();
090 arduboy.startGray();
100 }
110
120 void update() {
130
140 if (arduboy.pressed(UP_BUTTON) && y > 0) {
150 y--;
160 }
170
180 if (arduboy.pressed(DOWN_BUTTON) && y < 56) {
190 y++;
200 }
210
220 }
230
240 void loop() {
250
260 FX::enableOLED();
270 a.waitForNextPlane(BLACK);
280 FX::disableOLED();
290
300 if (arduboy.needsUpdate()) update();
310
320 uint16_t currentPlane = a.currentPlane();
330
340 SpritesU::drawOverwriteFX(0, y, img, currentPlane);
350
360 }
The two sketches look similar.
As with the original sketch, the lines 000 - 040 import the required libraries and declare an instance of the main library. You will notice that the declaration includes the ABG_Mode::L4_Triplane constant indicating that we are using 4 shades of grey (white, light grey, dark grey and black). There are other modes but these are beyond the scope of this tutorial.
The setup() loop initialises and starts the library. Note that there is no code to set the frame rate as all ArduboyG games run at a high 156 FPS!
Jumping to the loop() function, you will notice the code starts varying from the original Arduboy2 version. It is important to understand that the grey scale images are painted in ‘layers’ or 'planes' building up the colors as it goes. When using the L4_Triplane (4 colour) mode, each image contains 3 planes - white, light grey and dark grey - and these are painted in that order and the planes build on each other.
If a single pixel is only rendered in one plane, it comes out as dark grey. If it is rendered in two planes, it is light grey. Finally, if it is rendered in all three planes then, of course, it is white.
At line 320, you the code uint16_t currentPlane = a.currentPlane(); which returns the current plane being drawn. When the code renders the image, using the SpritesU::drawOverwriteFX() command, it passes the coordinates, the image name and the current plane being drawn.
The loop() function must be executed three times to render a single image!
As images must be rendered over multiple iterations of the loop() function, it is important that they are not moved mid-rendering. The ArduboyG library provides a simple test to ensure that your game state logic is called only every 3rd iteration of the loop() function - as can be seen at line 300. Thus the logic to move the image is broken out into a function to be called every 3rd iteration rather than left inline as per the original Arduboy2 version of the code.