Configuration

Screen geometry, the panel's wiring, colour modes and SPI dividers: the build options and the constants they define. More...

Macros
#define	GFX_W   128
	Screen width in pixels (default 128).
#define	GFX_H   128
	Screen height in pixels (default 128).
#define	GFX_FB_STRIDE   (GFX_W / 2)
	Bytes per framebuffer row: two pixels a byte, 64 at 128 wide.
#define	GFX_FB_BYTES   (GFX_FB_STRIDE * GFX_H)
	Size of the framebuffer, gfx_fb, in bytes: 8192 at 128x128.
#define	GFX_CHUNK_ROWS   2
	Framebuffer rows converted per DMA chunk (default 2).
#define	GFX_CHUNK_BYTES   (GFX_W * GFX_CHUNK_ROWS * 2)
	Size of one DMA chunk buffer in bytes (worst case, 16 bpp).
#define	CHGFX_CS_PORT   GPIOA
	GPIO port of the panel's chip select (default GPIOA, the CHGame board's LCD_CS on PA4).
#define	CHGFX_CS_PIN   4
	Pin number of the panel's chip select on CHGFX_CS_PORT (default 4).
#define	CHGFX_DC_PORT   GPIOB
	GPIO port of the panel's data/command line (default GPIOB, LCD_DC on PB0).
#define	CHGFX_DC_PIN   0
	Pin number of the panel's data/command line on CHGFX_DC_PORT (default 0).
#define	CHGFX_RST_PORT   GPIOB
	GPIO port of the panel's reset line (default GPIOB, LCD_RST on PB12).
#define	CHGFX_RST_PIN   12
	Pin number of the panel's reset line on CHGFX_RST_PORT (default 12).
#define	CHGFX_SDCS_PORT   GPIOB
	GPIO port of the SD card's chip select, which shares SPI1 (default GPIOB, SD_CS on PB11).
#define	CHGFX_SDCS_PIN   11
	Pin number of the SD card's chip select on CHGFX_SDCS_PORT (default 11).

Enumerations
enum	: uint8_t {   GFX_16BPP = 0 ,   GFX_12BPP = 1 ,   GFX_18BPP = 2 }
	The panel's colour output modes, for gfx_begin() and gfx_setColorMode(). More...
enum	: uint8_t {   GFX_DIV2 = 2 ,   GFX_DIV4 = 4 ,   GFX_DIV8 = 8 ,   GFX_DIV16 = 16 }
	SPI baud dividers (HCLK / n) for gfx_begin() and gfx_setSpiDiv(). More...

Detailed Description

Screen geometry, the panel's wiring, colour modes and SPI dividers: the build options and the constants they define.

The macros here can be overridden with -D build flags. They are compiled into the library's own files, so they have to be build flags (--build-property build.extra_flags=-DGFX_CHUNK_ROWS=4 with arduino-cli), not #defines in the sketch. Two more switches are read only by the library's .cpp files:

• CHGFX_NO_SD_PARK: do not drive the shared SD card's chip select (CHGFX_SDCS_PORT / CHGFX_SDCS_PIN) high at gfx_begin(). Define it if nothing else shares SPI1.
• CHGFX_ISR_IN_SRAM: run the DMA interrupt handler from SRAM. An async flush costs 4-9% less CPU (0.1-0.25 ms a full frame), for about 330 bytes of SRAM.

Macro Definition Documentation

GFX_W

#define GFX_W   128

Screen width in pixels (default 128).

Override with a -D build flag. Must be a multiple of 8 (the row operations work in 32-bit words), and W*H/2 a multiple of 32. The framebuffer is W*H/2 bytes, so keep an eye on the 20 KB SRAM budget if you raise it (160x128 = 10 KB, still fits).

GFX_H

#define GFX_H   128

Screen height in pixels (default 128).

Override with a -D build flag.

GFX_FB_STRIDE

#define GFX_FB_STRIDE   (GFX_W / 2)

Bytes per framebuffer row: two pixels a byte, 64 at 128 wide.

GFX_FB_BYTES

#define GFX_FB_BYTES   (GFX_FB_STRIDE * GFX_H)

Size of the framebuffer, gfx_fb, in bytes: 8192 at 128x128.

GFX_CHUNK_ROWS

#define GFX_CHUNK_ROWS   2

Framebuffer rows converted per DMA chunk (default 2).

Two chunk buffers are allocated, so this directly costs GFX_W * GFX_CHUNK_ROWS * 4 bytes of SRAM. Override with -DGFX_CHUNK_ROWS=n; it does not buy much CPU back either (an async frame measured 2.49 / 2.33 / 2.29 ms of CPU at 2 / 4 / 8 rows, with CHGFX_ISR_IN_SRAM).

2 rows = 512 B per buffer, 1 KB total. Measured against the obvious 4 rows on real hardware: gfx_flush() went 11051 -> 11143 us, about 0.8%, which is the same order as run-to-run variation. That buys back a kilobyte, and on a part with 20 KB total a kilobyte is 5% of all the memory there is - the right way round for this chip. Raise it if you have RAM to spare and want the last percent.

GFX_CHUNK_BYTES

#define GFX_CHUNK_BYTES   (GFX_W * GFX_CHUNK_ROWS * 2)

Size of one DMA chunk buffer in bytes (worst case, 16 bpp).

There are two; together they are the 1 KB gfx_chunkScratch().

CHGFX_CS_PORT

#define CHGFX_CS_PORT   GPIOA

GPIO port of the panel's chip select (default GPIOA, the CHGame board's LCD_CS on PA4).

The three control pins (CS, DC, RST) can be moved with -D build flags; define the port and the pin together. SCK and MOSI are fixed: they are SPI1's pins on this package (PA5 and PA7), and SPI1 is the only peripheral with a DMA path to these lines.

CHGFX_CS_PIN

#define CHGFX_CS_PIN   4

Pin number of the panel's chip select on CHGFX_CS_PORT (default 4).

CHGFX_DC_PORT

#define CHGFX_DC_PORT   GPIOB

GPIO port of the panel's data/command line (default GPIOB, LCD_DC on PB0).

CHGFX_DC_PIN

#define CHGFX_DC_PIN   0

Pin number of the panel's data/command line on CHGFX_DC_PORT (default 0).

CHGFX_RST_PORT

#define CHGFX_RST_PORT   GPIOB

GPIO port of the panel's reset line (default GPIOB, LCD_RST on PB12).

CHGFX_RST_PIN

#define CHGFX_RST_PIN   12

Pin number of the panel's reset line on CHGFX_RST_PORT (default 12).

CHGFX_SDCS_PORT

#define CHGFX_SDCS_PORT   GPIOB

GPIO port of the SD card's chip select, which shares SPI1 (default GPIOB, SD_CS on PB11).

gfx_begin() drives it high so the card does not answer the traffic meant for the panel. Define CHGFX_NO_SD_PARK to skip that.

CHGFX_SDCS_PIN

#define CHGFX_SDCS_PIN   11

Pin number of the SD card's chip select on CHGFX_SDCS_PORT (default 11).

Enumeration Type Documentation

anonymous enum

anonymous enum : uint8_t

The panel's colour output modes, for gfx_begin() and gfx_setColorMode().

The framebuffer is always 4 bpp; this is what its palette colours are expanded to on the wire, so the frame rate is just the byte count. 12 bpp costs nothing visible behind a 16-colour palette and is a free 25%, so the CHGame games use it.

A note on 18 bpp. Each pixel is three bytes and each byte carries its 6-bit component in bits 7:2, bits 1:0 don't-care (ST7735S DS 9.8.4). 128*128*3 = 49152 B, so a frame costs 16.4 ms instead of 10.9 - you are buying one extra bit of red and one of blue for a third of your frame rate. Worth it for smooth gradients, pointless for sprite work. Unlike 12 bpp it does not pass through the RGBSET conversion table: the datasheet only defines 4k->262k and 65k->262k tables, so 18-bit data reaches the frame memory directly.

Enumerator
GFX_16BPP	ST7735 COLMOD 0x05, RGB565, 2 bytes/px -> 90 fps.
GFX_12BPP	ST7735 COLMOD 0x03, RGB444, 1.5 bytes/px -> 119 fps.
GFX_18BPP	ST7735 COLMOD 0x06, RGB666, 3 bytes/px -> 61 fps.

anonymous enum

anonymous enum : uint8_t

SPI baud dividers (HCLK / n) for gfx_begin() and gfx_setSpiDiv().

Note

The ST7735S datasheet specifies tSCYCW(min) = 66 ns, i.e. 15 MHz. 24 MHz is out of spec and only works on short flex. The Benchmark example's SPI sweep exists to find out whether YOUR panel tolerates it; GFX_DIV4 is comfortably in spec.

Enumerator
GFX_DIV2	HCLK/2 = 24 MHz: the fastest the chip can clock SPI, and the default.
GFX_DIV4	HCLK/4 = 12 MHz: within the ST7735S datasheet's limit.
GFX_DIV8	HCLK/8 = 6 MHz.
GFX_DIV16	HCLK/16 = 3 MHz.