hdw-tft.h File Reference

Detailed Description

Design Philosophy

TFT code is based on Espressif's LCD tjpgd example.

Each pixel in the frame-buffer is of type paletteColor_t. Even though the TFT supports 16 bit color, a 16 bit frame-buffer is too big to have in RAM alongside games and such. Instead, the 8 bit Web Safe palette is used, where each RGB channel has six options for a total of 216 colors. The paletteColor_t enum has values for all colors in the form of cRGB, where R, G, and B each range from 0 to 5. For example, c500 is full red. cTransparent is a special value for a transparent pixel.

Usage

You don't need to call initTFT() or deinitTFT(). The system does so at the appropriate time. You don't need to call drawDisplayTft() as it is called automatically after each main loop to draw the current frame-buffer to the TFT.

clearPxTft() is used to clear the current frame-buffer. This must be called before drawing a new frame, unless you want to draw over the prior one.

setPxTft() and getPxTft() are used to set and get individual pixels in the frame-buffer, respectively. These are not often used directly as there are helper functions to draw text, shapes, and sprites.

disableTFTBacklight() and enableTFTBacklight() may be called to disable and enable the backlight, respectively. This may be useful if the Swadge mode is trying to save power, or the TFT is not necessary. setTFTBacklightBrightness() is used to set the TFT's brightness. This is usually handled globally by a persistent setting. setTftBrightnessSetting() should be called instead if the brightness change should be persistent through reboots.

Example

Setting pixels:

// Clear the display
clearPxTft();
 
// Draw red, green, and blue vertical bars
for(uint16_t y = 0; y < TFT_HEIGHT; y++)
{
    for(uint16_t x = 0; x < TFT_WIDTH; x++)
    {
        if(x < TFT_WIDTH / 3)
        {
            setPxTft(x, y, c500);
        }
        else if (x < (2 * TFT_WIDTH) / 3)
        {
            setPxTft(x, y, c050);
        }
        else
        {
            setPxTft(x, y, c005);
        }
    }
}

Setting the backlight:

// Disable the backlight
disableTFTBacklight();
 
// Enable the backlight
enableTFTBacklight();
 
// Set the backlight to half brightness
setTFTBacklightBrightness(128);

Go to the source code of this file.

Macros
#define	MAX_TFT_BRIGHTNESS   7
	The maximum brightness setting of the TFT.
#define	SETUP_FOR_TURBO()
	Do nothing if this isn't an XTENSA platform.
#define	TURBO_SET_PIXEL(opxc, opy, colorVal)   setPxTft(opxc, opy, colorVal)
	Passthrough call to setPxTft() if this isn't an XTENSA platform.
#define	TURBO_SET_PIXEL_BOUNDS(opxc, opy, colorVal)   setPxTft(opxc, opy, colorVal)
	Passthrough call to setPxTft() if this isn't an XTENSA platform.

Typedefs
typedef void(*	fnBackgroundDrawCallback_t) (int16_t x, int16_t y, int16_t w, int16_t h, int16_t up, int16_t upNum)
	This is a typedef for a function pointer passed to drawDisplayTft() which will be called to draw a background image while the SPI transfer is occurring. This will be called multiple times to draw multiple areas for the current frame.

Functions
void	initTFT (spi_host_device_t spiHost, gpio_num_t sclk, gpio_num_t mosi, gpio_num_t dc, gpio_num_t cs, gpio_num_t rst, gpio_num_t backlight, bool isPwmBacklight, ledc_channel_t ledcChannel, ledc_timer_t ledcTimer, uint8_t brightness)
	Initialize a TFT display and return it through a pointer arg.
void	deinitTFT (void)
	Deinitialize the TFT display.
esp_err_t	setTFTBacklightBrightness (uint8_t intensity)
	Set TFT Backlight brightness. setTftBrightnessSetting() should be called instead if the new volume should be persistent through a reboot.
void	disableTFTBacklight (void)
	Disable the backlight (for power down)
void	enableTFTBacklight (void)
	Enable the backlight.
void	setPxTft (int16_t x, int16_t y, paletteColor_t px)
	Set a single pixel in the display, with bounds check.
paletteColor_t	getPxTft (int16_t x, int16_t y)
	Get a single pixel in the display.
paletteColor_t *	getPxTftFramebuffer (void)
	Return the pixel framebuffer, which is (TFT_WIDTH * TFT_HEIGHT) pixels in row order, starting from the top left. This can be used t directly modify individual pixels without calling setPxTft()
void	clearPxTft (void)
	Clear all pixels in the display to black.
void	drawDisplayTft (fnBackgroundDrawCallback_t cb)
	Send the current framebuffer to the TFT display over the SPI bus.

Macro Definition Documentation

MAX_TFT_BRIGHTNESS

#define MAX_TFT_BRIGHTNESS   7

The maximum brightness setting of the TFT.

SETUP_FOR_TURBO

#define SETUP_FOR_TURBO

(

)

Do nothing if this isn't an XTENSA platform.

TURBO_SET_PIXEL

#define TURBO_SET_PIXEL	(		opxc,
			opy,
			colorVal )   setPxTft(opxc, opy, colorVal)

Passthrough call to setPxTft() if this isn't an XTENSA platform.

TURBO_SET_PIXEL_BOUNDS

#define TURBO_SET_PIXEL_BOUNDS	(		opxc,
			opy,
			colorVal )   setPxTft(opxc, opy, colorVal)

Passthrough call to setPxTft() if this isn't an XTENSA platform.

Typedef Documentation

fnBackgroundDrawCallback_t

typedef void(* fnBackgroundDrawCallback_t) (int16_t x, int16_t y, int16_t w, int16_t h, int16_t up, int16_t upNum)

This is a typedef for a function pointer passed to drawDisplayTft() which will be called to draw a background image while the SPI transfer is occurring. This will be called multiple times to draw multiple areas for the current frame.

Parameters

x	The X coordinate to start filling in
y	The Y coordinate to start filling in
w	The width of the background area to draw
h	The height of the background area to draw
up	The number of times this function has been called for the current frame (an incrementing number)
upNum	The total number of times this will be called for the current frame

Function Documentation

initTFT()

void initTFT	(	spi_host_device_t	spiHost,
		gpio_num_t	sclk,
		gpio_num_t	mosi,
		gpio_num_t	dc,
		gpio_num_t	cs,
		gpio_num_t	rst,
		gpio_num_t	backlight,
		bool	isPwmBacklight,
		ledc_channel_t	ledcChannel,
		ledc_timer_t	ledcTimer,
		uint8_t	brightness )

Initialize a TFT display and return it through a pointer arg.

Parameters

spiHost	The SPI host to use for this display
sclk	The GPIO for the SCLK pin
mosi	The GPIO for the MOSI pin
dc	The GPIO for the TFT SPI data or command selector pin
cs	The GPIO for the chip select pin
rst	The GPIO for the RESET pin
backlight	The GPIO used to PWM control the backlight
isPwmBacklight	true to set up the backlight as PWM, false to have it be on/off
ledcChannel	The LEDC channel to use for the PWM backlight
ledcTimer	The LEDC timer to use for the PWM backlight
brightness	The initial backlight brightness

deinitTFT()

void deinitTFT

(

void

)

Deinitialize the TFT display.

setTFTBacklightBrightness()

esp_err_t setTFTBacklightBrightness

(

uint8_t

intensity

)

Set TFT Backlight brightness. setTftBrightnessSetting() should be called instead if the new volume should be persistent through a reboot.

Parameters

intensity

The brightness, 0 to MAX_TFT_BRIGHTNESS

Returns

value is 0 if OK nonzero if error.

disableTFTBacklight()

void disableTFTBacklight

(

void

)

Disable the backlight (for power down)

enableTFTBacklight()

void enableTFTBacklight

(

void

)

Enable the backlight.

setPxTft()

void setPxTft	(	int16_t	x,
		int16_t	y,
		paletteColor_t	px )

Set a single pixel in the display, with bounds check.

Parameters

x	The x coordinate of the pixel to set
y	The y coordinate of the pixel to set
px	The color of the pixel to set

getPxTft()

paletteColor_t getPxTft	(	int16_t	x,
		int16_t	y )

Get a single pixel in the display.

Parameters

x	The x coordinate of the pixel to get
y	The y coordinate of the pixel to get

Returns

paletteColor_t The color of the given pixel, or black if out of bounds

getPxTftFramebuffer()

paletteColor_t * getPxTftFramebuffer

(

void

)

Return the pixel framebuffer, which is (TFT_WIDTH * TFT_HEIGHT) pixels in row order, starting from the top left. This can be used t directly modify individual pixels without calling setPxTft()

Returns

The pixel framebuffer

clearPxTft()

void clearPxTft

(

void

)

Clear all pixels in the display to black.

drawDisplayTft()

void drawDisplayTft

(

fnBackgroundDrawCallback_t

fnBackgroundDrawCallback

)

Send the current framebuffer to the TFT display over the SPI bus.

This function can be called as quickly as possible

Because the SPI driver handles transactions in the background, we can calculate the next line while the previous one is being sent.

Parameters

fnBackgroundDrawCallback

A function pointer to draw backgrounds while the transmission is occurring