Double-buffered display driver for the 7-inch ESP32-P4 display board. More...

#include <stdbool.h>
#include <stdint.h>
#include "esp_err.h"
#include "gfx.h"

Data Structures
struct	display_config_t
	How display_init() sets the display up. More...

Macros
#define	DISPLAY_CONFIG_DEFAULT()
	Backlight on after the first frame.

Functions
esp_err_t	display_init (const display_config_t *cfg)
	Bring up the DSI PHY supply, the bus, the panel and the video stream, and the board's I2C bus and backlight if not already up.
esp_err_t	display_deinit (void)
	Stop the video stream and release the panel, the bus and the PHY supply.
gfx_canvas_t *	display_canvas (void)
	The canvas the application draws into. The returned pointer is stable for the lifetime of the driver; display_flip() re-points it at the new back buffer in place.
esp_err_t	display_flip (void)
	Present the back buffer and block until the buffer it replaces is no longer scanned out, at most 200ms.
esp_err_t	display_wait_vsync (uint32_t timeout_ms)
	Block until the next VSYNC (vertical sync) event.
int	display_width (void)
	The canvas's width: the UI's area.
int	display_height (void)
	The canvas's height: the UI's area.
int	display_back_index (void)
	Which frame buffer display_canvas() points at.
uint32_t	display_last_wait_us (void)
	How long the last display_flip() spent blocked.
uint32_t	display_frame_count (void)
	Frames presented since display_init().
float	display_fps (void)
	Rolling frames per second, measured over the last 500ms.
uint32_t	display_vsync_count (void)
	VSYNC events since display_init(): the panel's own refresh, whatever the flips do.
void	display_set_turned (bool turned)
	Screen rotation: 180°, or NORMAL, from the next display_flip() on. May be called from any task, also before display_init().
bool	display_turned (void)
	Whether the picture on the glass is turned by 180°: the flag the touch map turns by (gfx_turn_shown()).
bool	display_take_repaint (void)
	Whether the UI must repaint everything before it draws the next frame: the canvas changed between a logical buffer and a frame buffer. Clears it. Call it from the task that flips.
bool	display_take_turn_alert (void)
	Whether the alert that Screen rotation 180° fell back to NORMAL is due. Clears it. Call it from the task that flips.
uint32_t	display_last_turn_us (void)
	The time the last display_flip() spent copying turned blocks.
esp_err_t	display_backlight (bool on)
	Backlight at 100% or 0%.

Detailed Description

Double-buffered display driver for the 7-inch ESP32-P4 display board.

An EK79007 panel of 1024 x 600 pixels on a 2-lane MIPI DSI (Display Serial Interface) link, fed in video mode by the DPI (Display Pixel Interface) side of the ESP32-P4's DSI host.

Two full RGB565 (16-bit red, green, blue) frame buffers of 1,228,800 bytes each live in PSRAM (pseudo-static random-access memory), allocated by the DPI panel. The application draws into the one that is not being scanned out; display_flip() hands the finished buffer to the DPI panel, which takes the pointer without a copy and scans it from the next frame, waits for the frame-done event that frees the other buffer, and re-points the canvas at it.

gfx_canvas_t *c = display_canvas();
for (;;) {
    gfx_clear(c, GFX_BLACK);
    gfx_fill_circle(c, x, y, 40, GFX_RGB(0, 229, 255));
    display_flip();          // c re-points at the new back buffer
}

The canvas is BOARD_UI_H_RES x BOARD_UI_V_RES (1024 x 600), each buffer whole, with the buffer's 1024-pixel stride. A UI area smaller than the panel sits in the top-left corner; the rest of each buffer is black from allocation and nothing draws there.

Because the two buffers alternate, the back buffer after a flip holds the frame from two flips ago, not the one just shown. Redraw everything each frame, or keep a per-buffer record keyed on display_back_index().

Screen rotation 180° (display_set_turned()) turns the picture in the flush. The canvas then points at one of two logical buffers of the same size, 2,457,600 bytes of PSRAM in all, allocated at display_init(), and display_flip() copies what the frame drew into the frame buffer of the same index, turned, through the PPA (pixel-processing accelerator) before it hands that buffer over (gfx_turn.h). The touch map turns by the same flag, gfx_turn_shown(), once the turned frame is on the glass. A copy that takes longer than 50ms in a flip makes that frame go out unturned and the panel NORMAL until the next start.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ DISPLAY_CONFIG_DEFAULT

#define DISPLAY_CONFIG_DEFAULT ( )

Value:

(display_config_t) {                     \
    .backlight_on = true,                \
}

Backlight on after the first frame.

Function Documentation

◆ display_back_index()

int display_back_index ( void )

Which frame buffer display_canvas() points at.

The buffers alternate, so static content has to be drawn into both. A per-buffer validity flag keyed on this index keeps unchanging chrome out of the per-frame path, which on a panel fed from PSRAM decides whether the refresh rate is met.

Returns: 0 or 1.

◆ display_backlight()

esp_err_t display_backlight ( bool on )

Backlight at 100% or 0%.

Parameters

on	true for 100%, false for 0% (dark).

Returns: As board_backlight().

◆ display_canvas()

gfx_canvas_t * display_canvas ( void )

The canvas the application draws into. The returned pointer is stable for the lifetime of the driver; display_flip() re-points it at the new back buffer in place.

Returns: The canvas; before display_init() it has no pixels.

◆ display_deinit()

esp_err_t display_deinit ( void )

Stop the video stream and release the panel, the bus and the PHY supply.

Returns: ESP_OK, also when the display was not up.

◆ display_flip()

esp_err_t display_flip ( void )

Present the back buffer and block until the buffer it replaces is no longer scanned out, at most 200ms.

Returns: ESP_OK; ESP_ERR_TIMEOUT when no frame-done event came in 200ms; ESP_ERR_INVALID_STATE before display_init(); or the DPI panel's error for the hand-over.

◆ display_fps()

float display_fps ( void )

Rolling frames per second, measured over the last 500ms.

Returns: Frames per second; 0 before the first 500ms.

◆ display_frame_count()

uint32_t display_frame_count ( void )

Frames presented since display_init().

Returns: The count; it wraps at 2^32.

◆ display_height()

int display_height ( void )

The canvas's height: the UI's area.

Returns: BOARD_UI_V_RES, 600 pixels.

◆ display_init()

esp_err_t display_init ( const display_config_t * cfg )

Bring up the DSI PHY supply, the bus, the panel and the video stream, and the board's I2C bus and backlight if not already up.

Parameters

cfg	The set-up; NULL takes DISPLAY_CONFIG_DEFAULT().

Returns: ESP_OK, also when already up; otherwise the error of the step that failed, with everything before it released.

◆ display_last_turn_us()

uint32_t display_last_turn_us ( void )

The time the last display_flip() spent copying turned blocks.

Returns: Microseconds, 0 in NORMAL.

◆ display_last_wait_us()

uint32_t display_last_wait_us ( void )

How long the last display_flip() spent blocked.

Returns: Microseconds.

◆ display_set_turned()

void display_set_turned ( bool turned )

Screen rotation: 180°, or NORMAL, from the next display_flip() on. May be called from any task, also before display_init().

Parameters

turned true for 180°

◆ display_take_repaint()

bool display_take_repaint ( void )

Whether the UI must repaint everything before it draws the next frame: the canvas changed between a logical buffer and a frame buffer. Clears it. Call it from the task that flips.

Returns: true once per switch

◆ display_take_turn_alert()

bool display_take_turn_alert ( void )

Whether the alert that Screen rotation 180° fell back to NORMAL is due. Clears it. Call it from the task that flips.

Returns: true once per start at most

◆ display_turned()

bool display_turned ( void )

Whether the picture on the glass is turned by 180°: the flag the touch map turns by (gfx_turn_shown()).

Returns: true while turned

◆ display_vsync_count()

uint32_t display_vsync_count ( void )

VSYNC events since display_init(): the panel's own refresh, whatever the flips do.

Returns: The count; it wraps at 2^32.

◆ display_wait_vsync()

esp_err_t display_wait_vsync ( uint32_t timeout_ms )

Block until the next VSYNC (vertical sync) event.

Parameters

timeout_ms The longest wait in milliseconds; 0 waits forever.

Returns: ESP_OK, ESP_ERR_TIMEOUT, or ESP_ERR_INVALID_STATE before display_init().

◆ display_width()

int display_width ( void )

The canvas's width: the UI's area.

Returns: BOARD_UI_H_RES, 1024 pixels.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ DISPLAY_CONFIG_DEFAULT

Function Documentation

◆ display_back_index()

◆ display_backlight()

◆ display_canvas()

◆ display_deinit()

◆ display_flip()

◆ display_fps()

◆ display_frame_count()

◆ display_height()

◆ display_init()

◆ display_last_turn_us()

◆ display_last_wait_us()

◆ display_set_turned()

◆ display_take_repaint()

◆ display_take_turn_alert()

◆ display_turned()

◆ display_vsync_count()

◆ display_wait_vsync()

◆ display_width()