2021-05-12 03:26:07 +00:00
/*
2021-12-21 09:38:56 +00:00
* SPDX - FileCopyrightText : 2021 - 2022 Espressif Systems ( Shanghai ) CO LTD
2021-05-12 03:26:07 +00:00
*
* SPDX - License - Identifier : Apache - 2.0
*/
# pragma once
# include <stdbool.h>
# include "esp_err.h"
# include "esp_lcd_types.h"
# include "soc/soc_caps.h"
2021-08-20 03:48:33 +00:00
# include "hal/lcd_types.h"
2021-05-12 03:26:07 +00:00
# ifdef __cplusplus
extern " C " {
# endif
# if SOC_LCD_RGB_SUPPORTED
/**
* @ brief LCD RGB timing structure
2021-11-30 02:54:35 +00:00
* @ verbatim
2021-09-27 03:32:29 +00:00
* Total Width
* < - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - >
2021-11-30 02:54:35 +00:00
* HSYNC width HBP Active Width HFP
2021-09-27 03:32:29 +00:00
* < - - - > < - - > < - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - > < - - - >
* ____ ____ | _______________________________________ | ____ |
* | ___ | | | |
* | | |
* __ | | | |
* / | \ / | \ | | | |
* | VSYNC | | | | |
* | Width \ | / | __ | | |
* | / | \ | | | |
* | VBP | | | | |
* | \ | / _____ | _________ | _______________________________________ | |
* | / | \ | | / / / / / / / / / / / / / / / / / / / | |
* | | | | / / / / / / / / / / / / / / / / / / / / | |
* Total | | | | / / / / / / / / / / / / / / / / / / / / | |
2021-11-30 02:54:35 +00:00
* Height | | | | / / / / / / / / / / / / / / / / / / / / | |
2021-09-27 03:32:29 +00:00
* | Active | | | / / / / / / / / / / / / / / / / / / / / | |
* | Heigh | | | / / / / / / Active Display Area / / / / | |
* | | | | / / / / / / / / / / / / / / / / / / / / | |
* | | | | / / / / / / / / / / / / / / / / / / / / | |
* | | | | / / / / / / / / / / / / / / / / / / / / | |
* | | | | / / / / / / / / / / / / / / / / / / / / | |
* | | | | / / / / / / / / / / / / / / / / / / / / | |
* | \ | / _____ | _________ | _______________________________________ | |
* | / | \ | |
* | VFP | | |
* \ | / \ | / _____ | ______________________________________________________ |
2021-11-30 02:54:35 +00:00
* @ endverbatim
2021-05-12 03:26:07 +00:00
*/
typedef struct {
unsigned int pclk_hz ; /*!< Frequency of pixel clock */
unsigned int h_res ; /*!< Horizontal resolution, i.e. the number of pixels in a line */
unsigned int v_res ; /*!< Vertical resolution, i.e. the number of lines in the frame */
unsigned int hsync_pulse_width ; /*!< Horizontal sync width, unit: PCLK period */
unsigned int hsync_back_porch ; /*!< Horizontal back porch, number of PCLK between hsync and start of line active data */
unsigned int hsync_front_porch ; /*!< Horizontal front porch, number of PCLK between the end of active data and the next hsync */
unsigned int vsync_pulse_width ; /*!< Vertical sync width, unit: number of lines */
unsigned int vsync_back_porch ; /*!< Vertical back porch, number of invalid lines between vsync and start of frame */
2022-03-03 07:39:24 +00:00
unsigned int vsync_front_porch ; /*!< Vertical front porch, number of invalid lines between the end of frame and the next vsync */
2021-05-12 03:26:07 +00:00
struct {
unsigned int hsync_idle_low : 1 ; /*!< The hsync signal is low in IDLE state */
unsigned int vsync_idle_low : 1 ; /*!< The vsync signal is low in IDLE state */
unsigned int de_idle_high : 1 ; /*!< The de signal is high in IDLE state */
2022-03-03 07:34:32 +00:00
unsigned int pclk_active_neg : 1 ; /*!< Whether the display data is clocked out on the falling edge of PCLK */
2021-11-30 02:54:35 +00:00
unsigned int pclk_idle_high : 1 ; /*!< The PCLK stays at high level in IDLE phase */
2022-05-11 07:52:09 +00:00
} flags ; /*!< LCD RGB timing flags */
2021-05-12 03:26:07 +00:00
} esp_lcd_rgb_timing_t ;
2021-09-27 03:32:29 +00:00
/**
* @ brief Type of RGB LCD panel event data
*/
typedef struct {
} esp_lcd_rgb_panel_event_data_t ;
/**
2022-07-06 08:34:14 +00:00
* @ brief RGB LCD VSYNC event callback prototype
2021-09-27 03:32:29 +00:00
*
2022-06-01 03:00:00 +00:00
* @ param [ in ] panel LCD panel handle , returned from ` esp_lcd_new_rgb_panel ( ) `
2021-09-27 03:32:29 +00:00
* @ param [ in ] edata Panel event data , fed by driver
2022-07-06 08:34:14 +00:00
* @ param [ in ] user_ctx User data , passed from ` esp_lcd_rgb_panel_register_event_callbacks ( ) `
2021-09-27 03:32:29 +00:00
* @ return Whether a high priority task has been waken up by this function
*/
2022-07-06 08:34:14 +00:00
typedef bool ( * esp_lcd_rgb_panel_vsync_cb_t ) ( esp_lcd_panel_handle_t panel , const esp_lcd_rgb_panel_event_data_t * edata , void * user_ctx ) ;
2021-09-27 03:32:29 +00:00
2022-06-28 03:56:22 +00:00
/**
2022-07-06 08:34:14 +00:00
* @ brief Prototype for function to re - fill a bounce buffer , rather than copying from the frame buffer
2022-06-28 03:56:22 +00:00
*
2022-07-06 08:34:14 +00:00
* @ param [ in ] bounce_buf Bounce buffer to write data into
* @ param [ in ] pos_px How many pixels already were sent to the display in this frame , in other words ,
* at what pixel the routine should start putting data into bounce_buf
* @ param [ in ] len_bytes Length , in bytes , of the bounce buffer . Routine should fill this length fully .
* @ param [ in ] user_ctx Opaque pointer that was passed from ` esp_lcd_rgb_panel_register_event_callbacks ( ) `
* @ return Whether a high priority task has been waken up by this function
2022-06-28 03:56:22 +00:00
*/
2022-07-06 08:34:14 +00:00
typedef bool ( * esp_lcd_rgb_panel_bounce_buf_fill_cb_t ) ( esp_lcd_panel_handle_t panel , void * bounce_buf , int pos_px , int len_bytes , void * user_ctx ) ;
2022-06-28 03:56:22 +00:00
/**
2022-07-06 08:34:14 +00:00
* @ brief Group of supported RGB LCD panel callbacks
* @ note The callbacks are all running under ISR environment
* @ note When CONFIG_LCD_RGB_ISR_IRAM_SAFE is enabled , the callback itself and functions called by it should be placed in IRAM .
2022-06-28 03:56:22 +00:00
*/
2022-07-06 08:34:14 +00:00
typedef struct {
esp_lcd_rgb_panel_vsync_cb_t on_vsync ; /*!< VSYNC event callback */
esp_lcd_rgb_panel_bounce_buf_fill_cb_t on_bounce_empty ; /*!< Bounce buffer empty callback. */
} esp_lcd_rgb_panel_event_callbacks_t ;
2022-06-28 03:56:22 +00:00
2021-05-12 03:26:07 +00:00
/**
* @ brief LCD RGB panel configuration structure
*/
typedef struct {
2021-08-20 03:48:33 +00:00
lcd_clock_source_t clk_src ; /*!< Clock source for the RGB LCD peripheral */
2021-05-12 03:26:07 +00:00
esp_lcd_rgb_timing_t timings ; /*!< RGB timing parameters */
size_t data_width ; /*!< Number of data lines */
2021-12-28 02:36:03 +00:00
size_t sram_trans_align ; /*!< Alignment for framebuffer that allocated in SRAM */
size_t psram_trans_align ; /*!< Alignment for framebuffer that allocated in PSRAM */
2022-07-06 08:59:37 +00:00
size_t bits_per_pixel ; /*!< Color depth, in bpp, specially, if set to zero, it will default to `data_width`.
When using a Serial RGB interface , this value could be different from ` data_width ` */
2021-05-12 03:26:07 +00:00
int hsync_gpio_num ; /*!< GPIO used for HSYNC signal */
int vsync_gpio_num ; /*!< GPIO used for VSYNC signal */
int de_gpio_num ; /*!< GPIO used for DE signal, set to -1 if it's not used */
int pclk_gpio_num ; /*!< GPIO used for PCLK signal */
int data_gpio_nums [ SOC_LCD_RGB_DATA_WIDTH ] ; /*!< GPIOs used for data lines */
int disp_gpio_num ; /*!< GPIO used for display control signal, set to -1 if it's not used */
2022-06-28 03:56:22 +00:00
int bounce_buffer_size_px ; /*!< If not-zero, the driver uses a bounce buffer in internal memory to DMA from. Value is in pixels. */
2021-05-12 03:26:07 +00:00
struct {
unsigned int disp_active_low : 1 ; /*!< If this flag is enabled, a low level of display control signal can turn the screen on; vice versa */
2021-07-23 03:04:35 +00:00
unsigned int fb_in_psram : 1 ; /*!< If this flag is enabled, the frame buffer will be allocated from PSRAM preferentially */
2022-06-28 03:56:22 +00:00
unsigned int bb_do_cache_invalidate : 1 ; /*!< If this flag is enabled, in bounceback mode we'll do a cache invalidate on the read data, freeing the cache. Can be dangerous if data is written from other core. */
2022-07-06 08:54:30 +00:00
uint32_t refresh_on_demand : 1 ; /*!< If this flag is enabled, the host only refresh the frame buffer when `esp_lcd_panel_draw_bitmap` is called.
2022-05-11 07:52:09 +00:00
} flags ; /*!< LCD RGB panel configuration flags */
2021-05-12 03:26:07 +00:00
} esp_lcd_rgb_panel_config_t ;
/**
* @ brief Create RGB LCD panel
*
* @ param rgb_panel_config RGB panel configuration
* @ param ret_panel Returned LCD panel handle
* @ return
* - ESP_ERR_INVALID_ARG if parameter is invalid
* - ESP_ERR_NO_MEM if out of memory
* - ESP_ERR_NOT_FOUND if no free RGB panel is available
* - ESP_OK on success
*/
esp_err_t esp_lcd_new_rgb_panel ( const esp_lcd_rgb_panel_config_t * rgb_panel_config , esp_lcd_panel_handle_t * ret_panel ) ;
2022-07-06 08:34:14 +00:00
/**
* @ brief Register LCD RGB panel event callbacks
*
* @ param [ in ] panel LCD panel handle , returned from ` esp_lcd_new_rgb_panel ( ) `
* @ param [ in ] callbacks Group of callback functions
* @ param [ in ] user_ctx User data , which will be passed to the callback functions directly
* @ return
* - ESP_OK : Set event callbacks successfully
* - ESP_ERR_INVALID_ARG : Set event callbacks failed because of invalid argument
* - ESP_FAIL : Set event callbacks failed because of other error
*/
esp_err_t esp_lcd_rgb_panel_register_event_callbacks ( esp_lcd_panel_handle_t panel , const esp_lcd_rgb_panel_event_callbacks_t * callbacks , void * user_ctx ) ;
2022-06-01 03:00:00 +00:00
/**
* @ brief Set frequency of PCLK for RGB LCD panel
*
* @ note The PCLK frequency is set in the ` esp_lcd_rgb_timing_t ` and gets configured during LCD panel initialization .
* Usually you don ' t need to call this function to set the PCLK again , but in some cases , you may need to change the PCLK frequency .
* e . g . to slow down the PCLK frequency to reduce power consumption or to reduce the memory throughput .
* @ note This function doesn ' t cause the hardware to update the PCLK immediately but to record the new frequency and set a flag internally .
* Next time when start a new transaction , the driver will update the PCLK automatically .
*
* @ param panel LCD panel handle , returned from ` esp_lcd_new_rgb_panel ( ) `
* @ param freq_hz Frequency of pixel clock , in Hz
2022-07-06 08:43:08 +00:00
/**
* @ brief Get the address of the frame buffer ( s ) that allocated by the driver
*
* @ param [ in ] panel LCD panel handle , returned from ` esp_lcd_new_rgb_panel ( ) `
* @ param [ in ] fb_num Number of frame buffer ( s ) to get . This value must be the same as the number of the following parameters .
* @ param [ out ] fb0 Returned address of the frame buffer 0
* @ param [ out ] . . . List of other frame buffer addresses
* @ return
* - ESP_ERR_INVALID_ARG : Get frame buffer address failed because of invalid argument
* - ESP_OK : Get frame buffer address successfully
*/
esp_err_t esp_lcd_rgb_panel_get_frame_buffer ( esp_lcd_panel_handle_t panel , uint32_t fb_num , void * * fb0 , . . . ) ;
2022-07-06 08:48:22 +00:00
/**
* @ brief Manually trigger once transmission of the frame buffer to the LCD panel
*
* @ note This function should only be called when the RGB panel is working under the ` refresh_on_demand ` mode .
*
* @ param [ in ] panel LCD panel handle , returned from ` esp_lcd_new_rgb_panel ( ) `
2022-06-01 03:00:00 +00:00
* @ return
2022-07-06 08:48:22 +00:00
* - ESP_ERR_INVALID_ARG : Start a refresh failed because of invalid argument
* - ESP_ERR_INVALID_STATE : Start a refresh failed because the LCD panel is not created with the ` refresh_on_demand ` flag enabled .
* - ESP_OK : Start a refresh successfully
2022-06-01 03:00:00 +00:00
*/
2022-07-06 08:48:22 +00:00
esp_err_t esp_lcd_rgb_panel_refresh ( esp_lcd_panel_handle_t panel ) ;
2022-06-01 03:00:00 +00:00
2021-05-12 03:26:07 +00:00
# endif // SOC_LCD_RGB_SUPPORTED
# ifdef __cplusplus
}
# endif