CHGfx Class Reference

Arduino-style access to CHGfx: every method is a zero-cost inline forwarder to a gfx_* function. More...

#include <CHGfx.h>

Public Member Functions
void	begin (uint8_t spiDiv=GFX_DIV2, uint8_t colorMode=GFX_16BPP)
	Starts the panel.
Configuration
void	setSpiDiv (uint8_t d)
	Changes the SPI clock divider.
void	setColorMode (uint8_t m)
	Switches the colour output mode.
uint8_t	colorMode () const
	The current colour output mode.
uint32_t	spiHz () const
	The current SPI clock.
void	setPanelOffsets (uint8_t m, uint8_t cs, uint8_t rs)
	Sets the panel's MADCTL and window offsets.
void	setInverted (bool on)
	Turns colour inversion on or off.
void	setPanelFrameRate (uint8_t r, uint8_t f, uint8_t b)
	Sets the panel's own refresh rate (FRMCTR1).
Present
void	display ()
	Sends the whole framebuffer and waits for it.
void	stream (gfx_streamFn fn, void *user=nullptr)
	Draws one full-colour frame from a callback, bypassing the framebuffer.
void	displayAsync ()
	Starts sending the whole framebuffer by DMA and returns at once.
void	displayRect (int x, int y, int w, int h)
	Sends one rectangle of the framebuffer and waits for it.
void	displayRectAsync (int x, int y, int w, int h)
	Starts sending one rectangle of the framebuffer and returns at once.
bool	busy () const
	Whether an async flush is in flight.
void	wait ()
	Waits for the flush in flight to finish.
int	flushRow () const
	The first row the flush in flight may still read.
void	waitRow (int y)
	Waits until rows 0..y-1 are free to draw into.
Clip
void	setClip (int x, int y, int w, int h)
	Sets the clip rectangle.
void	resetClip ()
	Puts the clip rectangle back to the whole screen.
void	getClip (int *x, int *y, int *w, int *h) const
	Reads the clip rectangle.
Draw
void	clear (uint8_t c)
	Fills the clip rectangle with one colour.
void	drawPixel (int x, int y, uint8_t c)
	Sets one pixel.
uint8_t	getPixel (int x, int y) const
	Reads one pixel.
void	drawFastHLine (int x, int y, int w, uint8_t c)
	Draws a horizontal line.
void	drawFastVLine (int x, int y, int h, uint8_t c)
	Draws a vertical line.
void	fillRect (int x, int y, int w, int h, uint8_t c)
	Fills a rectangle.
void	drawRect (int x, int y, int w, int h, uint8_t c)
	Draws a rectangle's outline.
void	drawLine (int x0, int y0, int x1, int y1, uint8_t c)
	Draws a line, both ends included.
void	drawCircle (int cx, int cy, int r, uint8_t c)
	Draws a circle's outline.
void	fillCircle (int cx, int cy, int r, uint8_t c)
	Draws a filled circle.
void	drawSprite (const uint8_t *s, int x, int y, int w, int h, int transparent=-1)
	Copies a 4 bpp bitmap into the framebuffer.
void	drawRoundRect (int x, int y, int w, int h, int r, uint8_t c)
	Draws a rounded rectangle's outline.
void	fillRoundRect (int x, int y, int w, int h, int r, uint8_t c)
	Fills a rounded rectangle.
void	drawEllipse (int cx, int cy, int rx, int ry, uint8_t c)
	Draws an ellipse's outline.
void	fillEllipse (int cx, int cy, int rx, int ry, uint8_t c)
	Draws a filled ellipse.
void	dither (int x, int y, int w, int h, uint8_t c, uint8_t phase=0)
	Paints a 50% checkerboard of one colour over a rectangle.
void	remapRect (int x, int y, int w, int h, const uint8_t *remap)
	Recolours a rectangle in place through a 16-entry table.
void	drawSprite4 (const uint8_t *s, int x, int y, const uint8_t *remap=nullptr, int scale=256)
	Draws a span sprite.
void	drawSprite4Rot (const uint8_t *s, int ax, int ay, int px, int py, uint8_t angle, int scale=256, const uint8_t *remap=nullptr)
	Draws a span sprite rotated and scaled about a pivot.
void	scroll (int y, int h, int dx, int dy, int fill=-1)
	Moves a band of rows by (dx, dy) inside the band.
void	copyRow (int y, const uint8_t *src, int x0, int x1)
	Copies pixels [x0, x1) of a row buffer into a framebuffer row.
void	drawChar (int x, int y, char ch, uint8_t c)
	Draws one character.
void	drawChar (int x, int y, char ch, uint8_t c, uint8_t scale)
	Draws one character, scaled.
void	print (int x, int y, const char *s, uint8_t c)
	Draws a string.
void	print (int x, int y, const char *s, uint8_t c, uint8_t scale)
	Draws a string, scaled.
bool	printFx (int x, int y, const char *s, uint8_t scale, uint8_t fill, int outline=-1, int shadow=-1, const uint8_t *ramp=nullptr, const int8_t *dy=nullptr)
	Draws outlined, shadowed or gradient-filled text.
Fonts
setFont(nullptr) returns to the built-in 5x7. Note that a custom font takes y as the baseline - see Text.
void	setFont (const GFXfont *f=nullptr)
	Selects the font.
const GFXfont *	font () const
	The current font.
int	fontLineHeight () const
	Baseline-to-baseline line spacing.
int	fontBaseline () const
	The font's ascent above the baseline.
int	textWidth (const char *s) const
	Advance width of a string.
int	textWidth (const char *s, uint8_t scale) const
	Advance width of a string at a scale.
void	textBounds (const char *s, int x, int y, uint8_t scale, int *bx, int *by, int *bw, int *bh) const
	Bounding box of a string drawn at (x, y).
Direct to the panel
void	fillRectDirect (uint8_t x, uint8_t y, uint8_t w, uint8_t h, uint16_t rgb565)
	Fills a rectangle of the panel by DMA, bypassing the framebuffer (16 bpp only).

Palette
void	setPalette (const uint16_t *p, uint8_t n)
	Sets the first n palette entries.
void	setPaletteEntry (uint8_t i, uint16_t c)
	Sets one palette entry.
void	setFade (uint8_t amount, uint16_t rgb565=0)
	Fades every colour toward one colour.
uint8_t	fade () const
	The current fade amount.
uint8_t	nearest (uint16_t rgb565) const
	Nearest palette index for an RGB565 colour (slow: setup only).
static uint16_t	rgb (uint8_t r, uint8_t g, uint8_t b)
	Packs an 8-bit-per-channel colour into RGB565.

The raw framebuffer
uint8_t *	buffer () const
	The framebuffer, for primitives of your own.
static constexpr int	width ()
	Screen width.
static constexpr int	height ()
	Screen height.

Detailed Description

Arduino-style access to CHGfx: every method is a zero-cost inline forwarder to a gfx_* function.

There is exactly one panel, one SPI peripheral and one DMA channel, so the driver state is inherently global - the class exists for the familiar Gfx.clear(0) spelling, not to allow two instances. Use the one instance, Gfx. Use whichever style you prefer; they are the same code. Each method's full description is on the function it forwards to.

Gfx.begin(GFX_DIV2, GFX_12BPP);
Gfx.clear(0);
Gfx.print(4, 4, "Hello", 1);
Gfx.display();

Member Function Documentation

begin()

void CHGfx::begin ( uint8_t  spiDiv = GFX_DIV2, uint8_t  colorMode = GFX_16BPP  )

inline

Starts the panel.

Parameters

spiDiv	SPI clock divider (default GFX_DIV2, 24 MHz).
colorMode	GFX_16BPP (the default), GFX_12BPP or GFX_18BPP.

See also

gfx_begin()

setSpiDiv()

void CHGfx::setSpiDiv ( uint8_t  d )

inline

Changes the SPI clock divider.

Parameters

d	GFX_DIV2..GFX_DIV16.

See also

gfx_setSpiDiv()

setColorMode()

void CHGfx::setColorMode ( uint8_t  m )

inline

Switches the colour output mode.

Parameters

m	GFX_16BPP, GFX_12BPP or GFX_18BPP.

See also

gfx_setColorMode()

colorMode()

uint8_t CHGfx::colorMode ( ) const

inline

The current colour output mode.

Returns

GFX_16BPP, GFX_12BPP or GFX_18BPP.

See also

gfx_colorMode()

spiHz()

uint32_t CHGfx::spiHz ( ) const

inline

The current SPI clock.

Returns

Hz.

See also

gfx_spiHz()

setPanelOffsets()

void CHGfx::setPanelOffsets ( uint8_t  m, uint8_t  cs, uint8_t  rs  )

inline

Sets the panel's MADCTL and window offsets.

Parameters

m	MADCTL value.
cs	First visible column.
rs	First visible row.

See also

gfx_setPanelOffsets()

setInverted()

void CHGfx::setInverted ( bool  on )

inline

Turns colour inversion on or off.

Parameters

on	true to invert.

See also

gfx_setInverted()

setPanelFrameRate()

void CHGfx::setPanelFrameRate ( uint8_t  r, uint8_t  f, uint8_t  b  )

inline

Sets the panel's own refresh rate (FRMCTR1).

Parameters

r	RTNA.
f	Front porch.
b	Back porch.

See also

gfx_setPanelFrameRate()

setPalette()

void CHGfx::setPalette ( const uint16_t *  p, uint8_t  n  )

inline

Sets the first n palette entries.

Parameters

p	RGB565 colours.
n	How many, at most 16.

See also

gfx_setPalette()

setPaletteEntry()

void CHGfx::setPaletteEntry ( uint8_t  i, uint16_t  c  )

inline

Sets one palette entry.

Parameters

i	Palette index, 0..15.
c	RGB565 colour.

See also

gfx_setPaletteEntry()

setFade()

void CHGfx::setFade ( uint8_t  amount, uint16_t  rgb565 = 0  )

inline

Fades every colour toward one colour.

Parameters

amount	0 = none, 255 = solid rgb565.
rgb565	The colour faded toward (default black).

See also

gfx_setFade()

fade()

uint8_t CHGfx::fade ( ) const

inline

The current fade amount.

Returns

0..255.

See also

gfx_fade()

nearest()

uint8_t CHGfx::nearest ( uint16_t  rgb565 ) const

inline

Nearest palette index for an RGB565 colour (slow: setup only).

Parameters

rgb565

The colour.

Returns

Palette index, 0..15.

See also

gfx_nearest()

rgb()

static uint16_t CHGfx::rgb ( uint8_t  r, uint8_t  g, uint8_t  b  )

inlinestatic

Packs an 8-bit-per-channel colour into RGB565.

Parameters

r	Red, 0..255.
g	Green, 0..255.
b	Blue, 0..255.

Returns

RGB565.

See also

gfx_rgb()

display()

void CHGfx::display ( )

inline

Sends the whole framebuffer and waits for it.

See also

gfx_flush()

stream()

void CHGfx::stream ( gfx_streamFn  fn, void *  user = nullptr  )

inline

Draws one full-colour frame from a callback, bypassing the framebuffer.

Parameters

fn	Fills each chunk of rows.
user	Passed to fn (default nullptr).

See also

gfx_stream()

displayAsync()

void CHGfx::displayAsync ( )

inline

Starts sending the whole framebuffer by DMA and returns at once.

See also

gfx_flushAsync()

displayRect()

void CHGfx::displayRect ( int  x, int  y, int  w, int  h  )

inline

Sends one rectangle of the framebuffer and waits for it.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.

See also

gfx_flushRect()

displayRectAsync()

void CHGfx::displayRectAsync ( int  x, int  y, int  w, int  h  )

inline

Starts sending one rectangle of the framebuffer and returns at once.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.

See also

gfx_flushRectAsync()

busy()

bool CHGfx::busy ( ) const

inline

Whether an async flush is in flight.

Returns

true while sending.

See also

gfx_busy()

wait()

void CHGfx::wait ( )

inline

Waits for the flush in flight to finish.

See also

gfx_wait()

flushRow()

int CHGfx::flushRow ( ) const

inline

The first row the flush in flight may still read.

Returns

A row, or GFX_H when idle.

See also

gfx_flushRow()

waitRow()

void CHGfx::waitRow ( int  y )

inline

Waits until rows 0..y-1 are free to draw into.

Parameters

y	One past the last row needed.

See also

gfx_waitRow()

setClip()

void CHGfx::setClip ( int  x, int  y, int  w, int  h  )

inline

Sets the clip rectangle.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.

See also

gfx_setClip()

resetClip()

void CHGfx::resetClip ( )

inline

Puts the clip rectangle back to the whole screen.

See also

gfx_resetClip()

getClip()

void CHGfx::getClip ( int *  x, int *  y, int *  w, int *  h  ) const

inline

Reads the clip rectangle.

Parameters

[out]	x	Left edge (may be nullptr).
[out]	y	Top edge (may be nullptr).
[out]	w	Width (may be nullptr).
[out]	h	Height (may be nullptr).

See also

gfx_getClip()

clear()

void CHGfx::clear ( uint8_t  c )

inline

Fills the clip rectangle with one colour.

Parameters

c	Palette index.

See also

gfx_clear()

drawPixel()

void CHGfx::drawPixel ( int  x, int  y, uint8_t  c  )

inline

Sets one pixel.

Parameters

x	Column.
y	Row.
c	Palette index.

See also

gfx_pixel()

getPixel()

uint8_t CHGfx::getPixel ( int  x, int  y  ) const

inline

Reads one pixel.

Parameters

x	Column.
y	Row.

Returns

Palette index, or 0 off the screen.

See also

gfx_getPixel()

drawFastHLine()

void CHGfx::drawFastHLine ( int  x, int  y, int  w, uint8_t  c  )

inline

Draws a horizontal line.

Parameters

x	Left end.
y	Row.
w	Length.
c	Palette index.

See also

gfx_hline()

drawFastVLine()

void CHGfx::drawFastVLine ( int  x, int  y, int  h, uint8_t  c  )

inline

Draws a vertical line.

Parameters

x	Column.
y	Top end.
h	Length.
c	Palette index.

See also

gfx_vline()

fillRect()

void CHGfx::fillRect ( int  x, int  y, int  w, int  h, uint8_t  c  )

inline

Fills a rectangle.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.
c	Palette index.

See also

gfx_fillRect()

drawRect()

void CHGfx::drawRect ( int  x, int  y, int  w, int  h, uint8_t  c  )

inline

Draws a rectangle's outline.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.
c	Palette index.

See also

gfx_rect()

drawLine()

void CHGfx::drawLine ( int  x0, int  y0, int  x1, int  y1, uint8_t  c  )

inline

Draws a line, both ends included.

Parameters

x0	Start column.
y0	Start row.
x1	End column.
y1	End row.
c	Palette index.

See also

gfx_line()

drawCircle()

void CHGfx::drawCircle ( int  cx, int  cy, int  r, uint8_t  c  )

inline

Draws a circle's outline.

Parameters

cx	Centre column.
cy	Centre row.
r	Radius.
c	Palette index.

See also

gfx_circle()

fillCircle()

void CHGfx::fillCircle ( int  cx, int  cy, int  r, uint8_t  c  )

inline

Draws a filled circle.

Parameters

cx	Centre column.
cy	Centre row.
r	Radius.
c	Palette index.

See also

gfx_fillCircle()

drawSprite()

void CHGfx::drawSprite ( const uint8_t *  s, int  x, int  y, int  w, int  h, int  transparent = -1  )

inline

Copies a 4 bpp bitmap into the framebuffer.

Parameters

s	The bitmap, packed like the framebuffer.
x	Left edge.
y	Top edge.
w	Width in pixels.
h	Height in pixels.
transparent	Colour index skipped, or -1 (the default) for opaque.

See also

gfx_blit()

drawRoundRect()

void CHGfx::drawRoundRect ( int  x, int  y, int  w, int  h, int  r, uint8_t  c  )

inline

Draws a rounded rectangle's outline.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.
r	Corner radius.
c	Palette index.

See also

gfx_roundRect()

fillRoundRect()

void CHGfx::fillRoundRect ( int  x, int  y, int  w, int  h, int  r, uint8_t  c  )

inline

Fills a rounded rectangle.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.
r	Corner radius.
c	Palette index.

See also

gfx_fillRoundRect()

drawEllipse()

void CHGfx::drawEllipse ( int  cx, int  cy, int  rx, int  ry, uint8_t  c  )

inline

Draws an ellipse's outline.

Parameters

cx	Centre column.
cy	Centre row.
rx	Horizontal radius.
ry	Vertical radius.
c	Palette index.

See also

gfx_ellipse()

fillEllipse()

void CHGfx::fillEllipse ( int  cx, int  cy, int  rx, int  ry, uint8_t  c  )

inline

Draws a filled ellipse.

Parameters

cx	Centre column.
cy	Centre row.
rx	Horizontal radius.
ry	Vertical radius.
c	Palette index.

See also

gfx_fillEllipse()

dither()

void CHGfx::dither ( int  x, int  y, int  w, int  h, uint8_t  c, uint8_t  phase = 0  )

inline

Paints a 50% checkerboard of one colour over a rectangle.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.
c	Palette index.
phase	0 (the default) paints where x + y is even, 1 where odd.

See also

gfx_dither()

remapRect()

void CHGfx::remapRect ( int  x, int  y, int  w, int  h, const uint8_t *  remap  )

inline

Recolours a rectangle in place through a 16-entry table.

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.
remap	16 palette indices.

See also

gfx_remapRect()

drawSprite4()

void CHGfx::drawSprite4 ( const uint8_t *  s, int  x, int  y, const uint8_t *  remap = nullptr, int  scale = 256  )

inline

Draws a span sprite.

Parameters

s	The sprite data.
x	Left edge.
y	Top edge.
remap	16 palette indices, or nullptr (the default).
scale	Q8 scale, 256 = 1:1 (the default).

See also

gfx_sprite4()

drawSprite4Rot()

void CHGfx::drawSprite4Rot ( const uint8_t *  s, int  ax, int  ay, int  px, int  py, uint8_t  angle, int  scale = 256, const uint8_t *  remap = nullptr  )

inline

Draws a span sprite rotated and scaled about a pivot.

Parameters

s	The sprite data (at most 1 KB decoded).
ax	Pivot column in the sprite.
ay	Pivot row in the sprite.
px	Screen column of the pivot.
py	Screen row of the pivot.
angle	256 = a full turn, clockwise.
scale	Q8 scale, 256 = 1:1 (the default).
remap	16 palette indices, or nullptr (the default).

See also

gfx_sprite4Rot()

scroll()

void CHGfx::scroll ( int  y, int  h, int  dx, int  dy, int  fill = -1  )

inline

Moves a band of rows by (dx, dy) inside the band.

Parameters

y	First row.
h	Rows.
dx	Pixels right (negative: left).
dy	Rows down (negative: up).
fill	Palette index for uncovered pixels, or -1 (the default) to keep them.

See also

gfx_scroll()

copyRow()

void CHGfx::copyRow ( int  y, const uint8_t *  src, int  x0, int  x1  )

inline

Copies pixels [x0, x1) of a row buffer into a framebuffer row.

Parameters

y	Framebuffer row.
src	GFX_FB_STRIDE bytes, packed like the framebuffer.
x0	First pixel.
x1	One past the last pixel.

See also

gfx_copyRow()

drawChar() [1/2]

void CHGfx::drawChar ( int  x, int  y, char  ch, uint8_t  c  )

inline

Draws one character.

Parameters

x	Left edge.
y	Top (built-in font) or baseline (GFXfont).
ch	The character.
c	Palette index.

See also

gfx_char()

drawChar() [2/2]

void CHGfx::drawChar ( int  x, int  y, char  ch, uint8_t  c, uint8_t  scale  )

inline

Draws one character, scaled.

Parameters

x	Left edge.
y	Top (built-in font) or baseline (GFXfont).
ch	The character.
c	Palette index.
scale	Integer scale.

See also

gfx_charScaled()

print() [1/2]

void CHGfx::print ( int  x, int  y, const char *  s, uint8_t  c  )

inline

Draws a string.

Parameters

x	Left edge.
y	Top (built-in font) or baseline (GFXfont).
s	Null-terminated string.
c	Palette index.

See also

gfx_text()

print() [2/2]

void CHGfx::print ( int  x, int  y, const char *  s, uint8_t  c, uint8_t  scale  )

inline

Draws a string, scaled.

Parameters

x	Left edge.
y	Top (built-in font) or baseline (GFXfont).
s	Null-terminated string.
c	Palette index.
scale	Integer scale.

See also

gfx_textScaled()

printFx()

bool CHGfx::printFx ( int  x, int  y, const char *  s, uint8_t  scale, uint8_t  fill, int  outline = -1, int  shadow = -1, const uint8_t *  ramp = nullptr, const int8_t *  dy = nullptr  )

inline

Draws outlined, shadowed or gradient-filled text.

Parameters

x	Left edge.
y	Top (built-in font) or baseline (GFXfont).
s	Null-terminated string.
scale	Integer scale.
fill	Palette index of the letters.
outline	Palette index of the outline, or -1 (the default).
shadow	Palette index of the shadow, or -1 (the default).
ramp	A fill colour per pixel row, or nullptr (the default).
dy	A vertical offset per character, or nullptr (the default).

Returns

false if the text is too big for the 1 KB mask.

See also

gfx_textFx()

setFont()

void CHGfx::setFont ( const GFXfont *  f = nullptr )

inline

Selects the font.

Parameters

f	A GFXfont, or nullptr (the default) for the built-in 5x7.

See also

gfx_setFont()

font()

const GFXfont * CHGfx::font ( ) const

inline

The current font.

Returns

The GFXfont, or nullptr for the built-in one.

See also

gfx_font()

fontLineHeight()

int CHGfx::fontLineHeight ( ) const

inline

Baseline-to-baseline line spacing.

Returns

Pixels at scale 1.

See also

gfx_fontLineHeight()

fontBaseline()

int CHGfx::fontBaseline ( ) const

inline

The font's ascent above the baseline.

Returns

Pixels at scale 1; 0 for the built-in font.

See also

gfx_fontBaseline()

textWidth() [1/2]

int CHGfx::textWidth ( const char *  s ) const

inline

Advance width of a string.

Parameters

s	Null-terminated string.

Returns

Pixels (the widest line).

See also

gfx_textWidth()

textWidth() [2/2]

int CHGfx::textWidth ( const char *  s, uint8_t  scale  ) const

inline

Advance width of a string at a scale.

Parameters

s	Null-terminated string.
scale	Integer scale.

Returns

Pixels (the widest line).

See also

gfx_textWidthScaled()

textBounds()

void CHGfx::textBounds ( const char *  s, int  x, int  y, uint8_t  scale, int *  bx, int *  by, int *  bw, int *  bh  ) const

inline

Bounding box of a string drawn at (x, y).

Parameters

	s	Null-terminated string.
	x	Where it would be drawn.
	y	Where it would be drawn.
	scale	Integer scale.
[out]	bx	Left edge (may be nullptr).
[out]	by	Top edge (may be nullptr).
[out]	bw	Width (may be nullptr).
[out]	bh	Height (may be nullptr).

See also

gfx_textBounds()

fillRectDirect()

void CHGfx::fillRectDirect ( uint8_t  x, uint8_t  y, uint8_t  w, uint8_t  h, uint16_t  rgb565  )

inline

Fills a rectangle of the panel by DMA, bypassing the framebuffer (16 bpp only).

Parameters

x	Left edge.
y	Top edge.
w	Width.
h	Height.
rgb565	The colour.

See also

gfx_directFillRect()

buffer()

uint8_t * CHGfx::buffer ( ) const

inline

The framebuffer, for primitives of your own.

Returns

gfx_fb.

width()

static constexpr int CHGfx::width ( )

inlinestaticconstexpr

Screen width.

Returns

GFX_W.

height()

static constexpr int CHGfx::height ( )

inlinestaticconstexpr

Screen height.

Returns

GFX_H.

---

The documentation for this class was generated from the following file:

• CHGfx/src/CHGfx.h