1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*******************************************************************************************************************//** 8 * @ingroup RENESAS_GRAPHICS_INTERFACES 9 * @defgroup DISPLAY_API Display Interface 10 * @brief Interface for LCD panel displays. 11 * 12 * @section DISPLAY_API_SUMMARY Summary 13 * The display interface provides standard display functionality: 14 * - Signal timing configuration for LCD panels with RGB interface. 15 * - Dot clock source selection (internal or external) and frequency divider. 16 * - Blending of multiple graphics layers on the background screen. 17 * - Color correction (brightness/configuration/gamma correction). 18 * - Interrupts and callback function. 19 * 20 * 21 * @{ 22 **********************************************************************************************************************/ 23 24 #ifndef R_DISPLAY_API_H 25 #define R_DISPLAY_API_H 26 27 /*********************************************************************************************************************** 28 * Includes 29 **********************************************************************************************************************/ 30 31 /* Includes board and MCU related header files. */ 32 #include "bsp_api.h" 33 34 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 35 FSP_HEADER 36 37 /********************************************************************************************************************** 38 * Macro definitions 39 **********************************************************************************************************************/ 40 41 #define DISPLAY_GAMMA_CURVE_ELEMENT_NUM (16) 42 43 /********************************************************************************************************************** 44 * Typedef definitions 45 **********************************************************************************************************************/ 46 47 /** Display frame number */ 48 typedef enum e_display_frame_layer 49 { 50 DISPLAY_FRAME_LAYER_1 = 0, ///< Frame layer 1 51 DISPLAY_FRAME_LAYER_2 = 1 ///< Frame layer 2 52 } display_frame_layer_t; 53 54 /** Display interface operation state */ 55 typedef enum e_display_state 56 { 57 DISPLAY_STATE_CLOSED = 0, ///< Display closed 58 DISPLAY_STATE_OPENED = 1, ///< Display opened 59 DISPLAY_STATE_DISPLAYING = 2 ///< Displaying 60 } display_state_t; 61 62 /** Display event codes */ 63 typedef enum e_display_event 64 { 65 DISPLAY_EVENT_GR1_UNDERFLOW = 1, ///< Graphics frame1 underflow occurs 66 DISPLAY_EVENT_GR2_UNDERFLOW = 2, ///< Graphics frame2 underflow occurs 67 DISPLAY_EVENT_LINE_DETECTION = 3, ///< Designated line is processed 68 DISPLAY_EVENT_FRAME_END = 4, ///< Frame end is processed 69 } display_event_t; 70 71 #ifndef BSP_OVERRIDE_DISPLAY_IN_FORMAT_T 72 73 /** Input format setting */ 74 typedef enum e_display_in_format 75 { 76 DISPLAY_IN_FORMAT_32BITS_ARGB8888 = 0, ///< ARGB8888, 32 bits 77 DISPLAY_IN_FORMAT_32BITS_RGB888 = 1, ///< RGB888, 32 bits 78 DISPLAY_IN_FORMAT_16BITS_RGB565 = 2, ///< RGB565, 16 bits 79 DISPLAY_IN_FORMAT_16BITS_ARGB1555 = 3, ///< ARGB1555, 16 bits 80 DISPLAY_IN_FORMAT_16BITS_ARGB4444 = 4, ///< ARGB4444, 16 bits 81 DISPLAY_IN_FORMAT_CLUT8 = 5, ///< CLUT8 82 DISPLAY_IN_FORMAT_CLUT4 = 6, ///< CLUT4 83 DISPLAY_IN_FORMAT_CLUT1 = 7, ///< CLUT1 84 } display_in_format_t; 85 86 #endif 87 88 /** Output format setting */ 89 typedef enum e_display_out_format 90 { 91 DISPLAY_OUT_FORMAT_24BITS_RGB888 = 0, ///< RGB888, 24 bits 92 DISPLAY_OUT_FORMAT_18BITS_RGB666 = 1, ///< RGB666, 18 bits 93 DISPLAY_OUT_FORMAT_16BITS_RGB565 = 2, ///< RGB565, 16 bits 94 DISPLAY_OUT_FORMAT_8BITS_SERIAL = 3, ///< SERIAL, 8 bits 95 } display_out_format_t; 96 97 /** Data endian select */ 98 typedef enum e_display_endian 99 { 100 DISPLAY_ENDIAN_LITTLE, ///< Little-endian 101 DISPLAY_ENDIAN_BIG, ///< Big-endian 102 } display_endian_t; 103 104 /** RGB color order select */ 105 typedef enum e_display_color_order 106 { 107 DISPLAY_COLOR_ORDER_RGB, ///< Color order RGB 108 DISPLAY_COLOR_ORDER_BGR ///< Color order BGR 109 } display_color_order_t; 110 111 /** Polarity of a signal select */ 112 typedef enum e_display_signal_polarity 113 { 114 DISPLAY_SIGNAL_POLARITY_LOACTIVE, ///< Low active signal 115 DISPLAY_SIGNAL_POLARITY_HIACTIVE, ///< High active signal 116 } display_signal_polarity_t; 117 118 /** Signal synchronization edge select */ 119 typedef enum e_display_sync_edge 120 { 121 DISPLAY_SIGNAL_SYNC_EDGE_RISING, ///< Signal is synchronized to rising edge 122 DISPLAY_SIGNAL_SYNC_EDGE_FALLING, ///< Signal is synchronized to falling edge 123 } display_sync_edge_t; 124 125 /** Fading control */ 126 typedef enum e_display_fade_control 127 { 128 DISPLAY_FADE_CONTROL_NONE, ///< Applying no fading control 129 DISPLAY_FADE_CONTROL_FADEIN, ///< Applying fade-in control 130 DISPLAY_FADE_CONTROL_FADEOUT, ///< Applying fade-out control 131 } display_fade_control_t; 132 133 /** Fading status */ 134 typedef enum e_display_fade_status 135 { 136 DISPLAY_FADE_STATUS_NOT_UNDERWAY, ///< Fade-in/fade-out is not in progress 137 DISPLAY_FADE_STATUS_FADING_UNDERWAY, ///< Fade-in or fade-out is in progress 138 DISPLAY_FADE_STATUS_PENDING ///< Fade-in/fade-out is configured but not yet started 139 } display_fade_status_t; 140 141 /** Color Keying enable or disable */ 142 typedef enum e_display_color_keying 143 { 144 DISPLAY_COLOR_KEYING_DISABLE = 0, ///< Color keying disable 145 DISPLAY_COLOR_KEYING_ENABLE = 1 ///< Color keying enable 146 } display_color_keying_t; 147 148 #ifndef BSP_OVERRIDE_DISPLAY_DATA_SWAP_T 149 150 /** Data swap settings */ 151 typedef enum e_display_data_swap 152 { 153 DISPLAY_DATA_SWAP_8BIT = 1, 154 DISPLAY_DATA_SWAP_16BIT = 2, 155 DISPLAY_DATA_SWAP_32BIT = 4, 156 DISPLAY_DATA_SWAP_64BIT = 8, 157 } display_data_swap_t; 158 159 #endif 160 161 /** Display signal timing setting */ 162 typedef struct st_display_timing 163 { 164 uint16_t total_cyc; ///< Total cycles in one line or total lines in one frame 165 uint16_t display_cyc; ///< Active video cycles or lines 166 uint16_t back_porch; ///< Back porch cycles or lines 167 uint16_t sync_width; ///< Sync signal asserting width 168 display_signal_polarity_t sync_polarity; ///< Sync signal polarity 169 } display_timing_t; 170 171 /** RGB Color setting */ 172 typedef struct st_display_color 173 { 174 union 175 { 176 uint32_t argb; ///< Entire color 177 struct 178 { 179 uint8_t b; ///< blue 180 uint8_t g; ///< green 181 uint8_t r; ///< red 182 uint8_t a; ///< alpha 183 } byte; 184 }; 185 } display_color_t; 186 187 /** Contrast (gain) correction setting */ 188 typedef struct st_display_coordinate 189 { 190 int16_t x; ///< Coordinate X, this allows to set signed value. 191 int16_t y; ///< Coordinate Y, this allows to set signed value. 192 } display_coordinate_t; 193 194 /** Brightness (DC) correction setting */ 195 typedef struct st_display_brightness 196 { 197 bool enable; ///< Brightness Correction On/Off 198 uint16_t r; ///< Brightness (DC) adjustment for R channel 199 uint16_t g; ///< Brightness (DC) adjustment for G channel 200 uint16_t b; ///< Brightness (DC) adjustment for B channel 201 } display_brightness_t; 202 203 /** Contrast (gain) correction setting */ 204 typedef struct st_display_contrast 205 { 206 bool enable; ///< Contrast Correction On/Off 207 uint8_t r; ///< Contrast (gain) adjustment for R channel 208 uint8_t g; ///< Contrast (gain) adjustment for G channel 209 uint8_t b; ///< Contrast (gain) adjustment for B channel 210 } display_contrast_t; 211 212 /** Color correction setting */ 213 typedef struct st_display_correction 214 { 215 display_brightness_t brightness; ///< Brightness 216 display_contrast_t contrast; ///< Contrast 217 } display_correction_t; 218 219 /** Gamma correction setting for each color */ 220 typedef struct st_gamma_correction 221 { 222 bool enable; ///< Gamma Correction On/Off 223 uint16_t * gain; ///< Gain adjustment 224 uint16_t * threshold; ///< Start threshold 225 } gamma_correction_t; 226 227 /** Gamma correction setting */ 228 typedef struct st_display_gamma_correction 229 { 230 gamma_correction_t r; ///< Gamma correction for R channel 231 gamma_correction_t g; ///< Gamma correction for G channel 232 gamma_correction_t b; ///< Gamma correction for B channel 233 } display_gamma_correction_t; 234 235 /** CLUT setting */ 236 typedef struct st_display_clut 237 { 238 uint32_t color_num; ///< The number of colors in CLUT 239 const uint32_t * p_clut; ///< Address of the area storing the CLUT data (in ARGB8888 format) 240 } display_clut_t; 241 242 /** Color Keying setting */ 243 typedef struct st_display_colorkeying_cfg 244 { 245 display_color_t src_color; ///< Source color 246 display_color_t dst_color; ///< Destination color 247 display_color_keying_t enable_ckey; ///< Select enable or disable 248 } display_colorkeying_cfg_t; 249 250 /** Color Keying layer setting */ 251 typedef struct st_display_colorkeying_layer 252 { 253 display_colorkeying_cfg_t layer[2]; 254 } display_colorkeying_layer_t; 255 256 #ifndef BSP_OVERRIDE_DISPLAY_INPUT_CFG_T 257 258 /** Graphics plane input configuration structure */ 259 typedef struct st_display_input_cfg 260 { 261 uint32_t * p_base; ///< Base address to the frame buffer 262 uint16_t hsize; ///< Horizontal pixel size in a line 263 uint16_t vsize; ///< Vertical pixel size in a frame 264 uint32_t hstride; ///< Memory stride (bytes) in a line 265 display_in_format_t format; ///< Input format setting 266 bool line_descending_enable; ///< Line descending enable 267 bool lines_repeat_enable; ///< Line repeat enable 268 uint16_t lines_repeat_times; ///< Expected number of line repeating 269 } display_input_cfg_t; 270 271 #endif 272 273 /** Display output configuration structure */ 274 typedef struct st_display_output_cfg 275 { 276 display_timing_t htiming; ///< Horizontal display cycle setting 277 display_timing_t vtiming; ///< Vertical display cycle setting 278 display_out_format_t format; ///< Output format setting 279 display_endian_t endian; ///< Bit order of output data 280 display_color_order_t color_order; ///< Color order in pixel 281 display_signal_polarity_t data_enable_polarity; ///< Data Enable signal polarity 282 display_sync_edge_t sync_edge; ///< Signal sync edge selection 283 display_color_t bg_color; ///< Background color 284 display_brightness_t brightness; ///< Brightness setting 285 display_contrast_t contrast; ///< Contrast setting 286 display_gamma_correction_t * p_gamma_correction; ///< Pointer to gamma correction setting 287 bool dithering_on; ///< Dithering on/off 288 } display_output_cfg_t; 289 290 /** Graphics layer blend setup parameter structure */ 291 typedef struct st_display_layer 292 { 293 display_coordinate_t coordinate; ///< Blending location (starting point of image) 294 display_color_t bg_color; ///< Color outside region 295 display_fade_control_t fade_control; ///< Layer fade-in/out control on/off 296 uint8_t fade_speed; ///< Layer fade-in/out frame rate 297 } display_layer_t; 298 299 /** Display callback parameter definition */ 300 typedef struct st_display_callback_args 301 { 302 display_event_t event; ///< Event code 303 void const * p_context; ///< Context provided to user during callback 304 } display_callback_args_t; 305 306 /** Display main configuration structure */ 307 typedef struct st_display_cfg 308 { 309 /** Generic configuration for display devices */ 310 display_input_cfg_t input[2]; ///< Graphics input frame setting 311 display_output_cfg_t output; ///< Graphics output frame setting 312 display_layer_t layer[2]; ///< Graphics layer blend setting 313 uint8_t line_detect_ipl; ///< Line detect interrupt priority 314 uint8_t underflow_1_ipl; ///< Underflow 1 interrupt priority 315 uint8_t underflow_2_ipl; ///< Underflow 2 interrupt priority 316 IRQn_Type line_detect_irq; ///< Line detect interrupt vector 317 IRQn_Type underflow_1_irq; ///< Underflow 1 interrupt vector 318 IRQn_Type underflow_2_irq; ///< Underflow 2 interrupt vector 319 320 /** Configuration for display event processing */ 321 void (* p_callback)(display_callback_args_t * p_args); ///< Pointer to callback function 322 void const * p_context; ///< User defined context passed into callback function 323 324 /** Pointer to display peripheral specific configuration */ 325 void const * p_extend; ///< Display hardware dependent configuration 326 } display_cfg_t; 327 328 /** Display main configuration structure */ 329 typedef struct st_display_runtime_cfg 330 { 331 /** Generic configuration for display devices */ 332 display_input_cfg_t input; ///< Graphics input frame setting 333 display_layer_t layer; ///< Graphics layer alpha blending setting 334 } display_runtime_cfg_t; 335 336 /** Display CLUT configuration structure */ 337 typedef struct st_display_clut_cfg 338 { 339 uint32_t * p_base; ///< Pointer to CLUT source data 340 uint16_t start; ///< Beginning of CLUT entry to be updated 341 uint16_t size; ///< Size of CLUT entry to be updated 342 } display_clut_cfg_t; 343 344 /** Display control block. Allocate an instance specific control block to pass into the display API calls. 345 */ 346 347 /** Display control block */ 348 typedef void display_ctrl_t; 349 350 /** Display Status */ 351 typedef struct st_display_status 352 { 353 display_state_t state; ///< Status of display module 354 display_fade_status_t fade_status[DISPLAY_FRAME_LAYER_2 + 1]; ///< Status of fade-in/fade-out status 355 } display_status_t; 356 357 /** Shared Interface definition for display peripheral */ 358 typedef struct st_display_api 359 { 360 /** Open display device. 361 * @param[in,out] p_ctrl Pointer to display interface control block. Must be declared by user. Value set 362 * here. 363 * @param[in] p_cfg Pointer to display configuration structure. All elements of this structure must be 364 * set by user. 365 */ 366 fsp_err_t (* open)(display_ctrl_t * const p_ctrl, display_cfg_t const * const p_cfg); 367 368 /** Close display device. 369 * @param[in] p_ctrl Pointer to display interface control block. 370 */ 371 fsp_err_t (* close)(display_ctrl_t * const p_ctrl); 372 373 /** Display start. 374 * @param[in] p_ctrl Pointer to display interface control block. 375 */ 376 fsp_err_t (* start)(display_ctrl_t * const p_ctrl); 377 378 /** Display stop. 379 * @param[in] p_ctrl Pointer to display interface control block. 380 */ 381 fsp_err_t (* stop)(display_ctrl_t * const p_ctrl); 382 383 /** Change layer parameters at runtime. 384 * @param[in] p_ctrl Pointer to display interface control block. 385 * @param[in] p_cfg Pointer to run-time layer configuration structure. 386 * @param[in] frame Number of graphic frames. 387 */ 388 fsp_err_t (* layerChange)(display_ctrl_t const * const p_ctrl, display_runtime_cfg_t const * const p_cfg, 389 display_frame_layer_t frame); 390 391 /** Change layer framebuffer pointer. 392 * @param[in] p_ctrl Pointer to display interface control block. 393 * @param[in] framebuffer Pointer to desired framebuffer. 394 * @param[in] frame Number of graphic frames. 395 */ 396 fsp_err_t (* bufferChange)(display_ctrl_t const * const p_ctrl, uint8_t * const framebuffer, 397 display_frame_layer_t frame); 398 399 /** Color correction. 400 * @param[in] p_ctrl Pointer to display interface control block. 401 * @param[in] param Pointer to color correction configuration structure. 402 */ 403 fsp_err_t (* correction)(display_ctrl_t const * const p_ctrl, display_correction_t const * const p_param); 404 405 /** Set CLUT for display device. 406 * @param[in] p_ctrl Pointer to display interface control block. 407 * @param[in] p_clut_cfg Pointer to CLUT configuration structure. 408 * @param[in] layer Layer number corresponding to the CLUT. 409 */ 410 fsp_err_t (* clut)(display_ctrl_t const * const p_ctrl, display_clut_cfg_t const * const p_clut_cfg, 411 display_frame_layer_t layer); 412 413 /** Set CLUT element for display device. 414 * @param[in] p_ctrl Pointer to display interface control block. 415 * @param[in] layer Layer number corresponding to the CLUT. 416 * @param[in] index CLUT element index. 417 * @param[in] color Desired CLUT index color. 418 */ 419 fsp_err_t (* clutEdit)(display_ctrl_t const * const p_ctrl, display_frame_layer_t layer, uint8_t index, 420 uint32_t color); 421 422 /** Configure color keying. 423 * @param[in] p_ctrl Pointer to display interface control block. 424 * @param[in] key_cfg Pointer to color keying configuration. 425 * @param[in] layer Layer to apply color keying. 426 */ 427 fsp_err_t (* colorKeySet)(display_ctrl_t const * const p_ctrl, display_colorkeying_layer_t key_cfg, 428 display_frame_layer_t layer); 429 430 /** Get status for display device. 431 * @param[in] p_ctrl Pointer to display interface control block. 432 * @param[in] status Pointer to display interface status structure. 433 */ 434 fsp_err_t (* statusGet)(display_ctrl_t const * const p_ctrl, display_status_t * const p_status); 435 } display_api_t; 436 437 /** This structure encompasses everything that is needed to use an instance of this interface. */ 438 typedef struct st_display_instance 439 { 440 display_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 441 display_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 442 display_api_t const * p_api; ///< Pointer to the API structure for this instance 443 } display_instance_t; 444 445 /********************************************************************************************************************** 446 * Public Functions 447 **********************************************************************************************************************/ 448 449 /* @} (end defgroup DISPLAY_API) */ 450 451 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 452 FSP_FOOTER 453 #endif 454
