Arduino_GFX Library

The Canvas Mono class is designed for monochrome display chips (such as the SSD1306 or SH1106) that require an in-memory buffer of the graphics data to be transferred in bulk to the display hardware.

To use Canvas Mono correctly, you must initialize it so that its internal memory buffer matches the physical characteristics of the display chip. This includes:

1. Dimensions: The width and height of the display memory.
2. Byte Orientation: Whether a byte is oriented horizontally or vertically in the display memory.

Note on Rotation: When you change the orientation (rotation) of the canvas (e.g., to 90 or 270 degrees), the width and height of the logical display will swap, but the underlying memory organization remains unchanged. The class handles the positioning of graphics elements like lines or characters within the memory buffer based on this orientation.

If your hardware is not a supported development device, you can customize the default configurations in the library header files:

• DataBus: The default is Arduino SPI. To use a different bus, modify Arduino_GFX_databus.h.
• Display: The default is an ILI9341 LCD. To use a different display driver, modify Arduino_GFX_display.h.

For a comprehensive test of the library's capabilities, use the built-in example:

1. Open the Arduino IDE.
2. Navigate to File -> Examples -> GFX Library for Arduino -> PDQgraphicstest.
3. The example consists of multiple tabs: PDQgraphicstest is the main program, while other tabs contain necessary header files like Arduino_GFX_databus.h.

If you are using a pre-configured development board (like LilyGo T-Deck), you can quickly set up the library by editing Arduino_GFX_dev_device.h. Locate the list of defines and uncomment the one corresponding to your hardware.

// In Arduino_GFX_dev_device.h
// #define JC3248W535
#define LILYGO_T_DECK
// #define LILYGO_T_DISPLAY

To use Arduino_GFX, you must first instantiate an Arduino_DataBus object (e.g., Arduino_HWSPI) and then pass that bus to an Arduino_GFX display driver instance (e.g., Arduino_ILI9341). This separation allows you to decouple the communication protocol from the specific display controller.

#include <Arduino_GFX_Library.h>

// 1. Initialize the DataBus (e.g., Hardware SPI with DC and CS pins)
Arduino_DataBus *bus = new Arduino_HWSPI(16 /* DC */, 5 /* CS */);

// 2. Initialize the Display driver using the bus and RST pin
Arduino_GFX *gfx = new Arduino_ILI9341(bus, 17 /* RST */);

The driver supports custom initialization sequences via the init_operations parameter in the constructor. This is particularly useful when switching between different communication modes (like SPI vs Parallel) or specific hardware configurations like the T-Display S3 AMOLED Plus.

Two predefined sequences are available in the header:

1. rm67162_init_operations: Standard initialization.
2. rm67162_spi_init_operations: Specific sequence for T-Display S3 AMOLED Plus using SPI mode, which includes specific page register setups and a 16-bit pixel format (0x75).

// Using the SPI-specific sequence for T-Display S3
Arduino_RM67162 display(&bus, RST_PIN, 1, true, rm67162_spi_init_operations, sizeof(rm67162_spi_init_operations));

Once the Arduino_GFX object is initialized, use standard graphics methods to control the display. Common methods include begin() to initialize the hardware, fillScreen() to clear the display, and text methods like setCursor(), setTextColor(), and println().

// Initialize the display
gfx->begin();

// Clear screen with black
gfx->fillScreen(RGB565_BLACK);

// Draw text
gfx->setCursor(10, 10);
gfx->setTextColor(RGB565_RED);
gfx->println("Hello World!");

The library provides several Canvas classes for managing framebuffers with different memory footprints:

• Arduino_Canvas: 16-bit pixel (standard).
• Arduino_Canvas_3bit: Uses 1/4 of the memory space of a 16-bit pixel.
• Arduino_Canvas_Indexed: Uses half the memory space of a 16-bit pixel.
• Arduino_Canvas_Mono: Uses 1/16 of the memory space of a 16-bit pixel.

After instantiation, call begin() to initialize the bus. You can optionally specify the bus speed and the data mode.

Parameters:

• speed: The bus speed (defaults to GFX_NOT_DEFINED).
• dataMode: The data mode (defaults to GFX_NOT_DEFINED).

// Initialize with default settings
bus.begin();

// Or initialize with specific speed
bus.begin(40000000); 

The Arduino_SH1106 class provides several specialized methods for rendering bitmap data to the screen:

• drawBitmap(x, y, bitmap, w, h, color, bg): Draws a standard bitmap with a specified foreground color and background bg.
• drawIndexedBitmap(x, y, bitmap, color_index, w, h, x_skip): Draws a bitmap using a color index map.
• draw3bitRGBBitmap(x, y, bitmap, w, h): Draws a 3-bit RGB bitmap.
• draw16bitRGBBitmap(x, y, bitmap, w, h): Draws a 16-bit RGB bitmap.
• draw24bitRGBBitmap(x, y, bitmap, w, h): Draws a 24-bit RGB bitmap.

display.drawBitmap(0, 0, myBitmap, 128, 64, 1, 0);

To use an SSD1306 display, instantiate the Arduino_SSD1306 class. The constructor requires an Arduino_DataBus pointer (such as an I2C or SPI bus implementation) and accepts optional parameters for the reset pin, width, and height.

Constructor Signature: Arduino_SSD1306(Arduino_DataBus *bus, int8_t rst = GFX_NOT_DEFINED, int16_t w = 128, int16_t h = 64)

Initialization: Call begin(int32_t speed) to initialize the hardware. The speed parameter allows you to specify the communication speed (e.g., I2C clock frequency), or use GFX_NOT_DEFINED to use the default.

// Example initialization
Arduino_SSD1306 display(&bus, RST_PIN, 128, 64);
if (!display.begin(400000)) {
  // Handle error
}