Screen Driver Callback Functions¶

Screen driver callback functions are the only interface for the upper-layer driver framework to operate the screen driver. Inside the interface, the register read and write functions are frequently used to operate the LCD.

The screen driver callback functions mainly include the following functions (for non-mandatory functions, they can be left blank or set to NULL):

Callback Function	Description
LCD_Init	Mandatory, screen driver initialization function (including reset, initialization procedures, etc.)
LCD_ReadID	Mandatory, screen presence detection function
LCD_DisplayOn	Mandatory, turn on the screen
LCD_DisplayOff	Mandatory, turn off the screen
LCD_SetRegion	Mandatory, set the area where the screen accepts data (2A, 2B area)
LCD_WritePixel	Optional, write a single pixel to the screen
LCD_WriteMultiplePixels	Mandatory, write multiple pixels to the screen
LCD_ReadPixel	Optional, read a pixel’s data from the screen, return the RGB value of the pixel
LCD_SetColorMode	Optional, switch the color format output to the screen
LCD_SetBrightness	Optional, set the screen brightness
LCD_IdleModeOn	Optional, enter standby display mode (low power mode)
LCD_IdleModeOff	Optional, exit standby display mode (low power mode)
LCD_Rotate	Optional, rotate the screen by a certain angle
LCD_TimeoutDbg	Optional, screen self-check after batch data transfer timeout
LCD_TimeoutReset	Optional, screen reset after batch data transfer timeout
LCD_ESDCheck	Optional, periodic ESD check for the screen

LCD Controller Register Read and Write Interfaces¶

These interfaces automatically communicate with the screen based on the interface type, frequency, and other settings configured by HAL_LCDC_Init:

Note

Both register and data transmission are little-endian. For example, when writing a register to an SPI screen:

uint8_t param[4] = {0xAA, 0xBB, 0xCC, 0xDD};

HAL_LCDC_WriteU32Reg(hlcdc, 0x78563412, &param, 4);

The bytes transmitted over the interface are in the order 0x12, 0x34, 0x56, 0x78, 0xAA, 0xBB, 0xCC, 0xDD.

(lcd-cb-func-LCD-Init)=
## LCD_Init
The first function called by the screen driver, for initialization.
This mainly includes:
1. Call `HAL_LCDC_Init` to initialize the LCD controller, setting the interface type, frequency, data format, etc.
2. Reset the screen using the `BSP_LCD_Reset` interface, with delays using `LCD_DRIVER_DELAY_MS`.
3. Send the initialization commands from the manufacturer's provided screen initialization command table to the screen using the [register write interface](lcdc-reg-read-write-func).

The following is a screenshot of a screen driver:
```{figure} assets/LCD_Init_func.png
    :scale: 30 %

LCD_ReadID¶

Screen presence detection function. The value returned by this function is compared with the LCD_ID provided during screen driver registration. If they match, the screen driver framework considers the screen driver to be usable. Otherwise, it will not call this screen driver.

This is the LCD_ID provided during screen driver registration:

LCD_DRIVER_EXPORT2(nv3051f1, LCD_ID, &lcdc_int_cfg, &LCD_drv,2);  

Note

This function can directly return the registered ID, which is suitable for the following scenarios:

Only one screen, no need to support multiple screen drivers
The screen does not support reading the ID

LCD_DisplayOn¶

This function generally sends the Display on command to the screen driver. The command format should refer to the screen driver IC’s datasheet.

LCD_DisplayOff¶

This function generally sends the Display off command to the screen driver. The command format should refer to the screen driver IC’s datasheet.

LCD_SetRegion¶

This function sets the output area of the LCD controller and the reception area of the screen driver.

Set the output area of the LCD controller using HAL_LCDC_SetROIArea.
Send the screen driver’s reception window command, usually the 2A, 2B registers.

In most cases, these two areas can be set to the same area based on the parameters passed to SetRegion. For DPI, DSI video, and other ramless screens, the area can be set once during initialization and does not need to be reset.

Relationship between the output area of the LCD controller, the reception area of the screen driver, and the Framebuffer area

LCD_WritePixel¶

Write a single pixel’s data to the screen.

LCD_WriteMultiplePixels¶

This function sets the address and region of the Framebuffer, and then triggers the screen refresh.

Set the address and coordinate region of the Framebuffer using HAL_LCDC_LayerSetData.
Send the register address for batch write data and then send the RGB data to the screen using HAL_LCDC_SendLayerData2Reg_IT. For interfaces like DPI and DSI video, which do not have register addresses, call HAL_LCDC_SendLayerData_IT to start sending RGB data.

LCD controller output area, screen driver reception area, Framebuffer location, and their relative relationships

LCD_ReadPixel¶

TODO.

LCD_SetColorMode¶

TODO.

LCD_SetBrightness¶

Set the backlight of the screen. There are generally two methods:

Directly modify the screen’s register to change the transparency of the LCD. This is typically used for AMOLED screens, and it works like this:

    uint8_t bright = (uint8_t)((int)255 * br / 100); // Convert percentage to a value between 0 and 255
    LCD_WriteReg(hlcdc, 0x51, &bright, 1); // Set the backlight register, usually 0x51

Modify the brightness of the backlight device “lcdlight”. This method is generally used for TFT screens, while AMOLED screens do not require it. It works like this:

    rt_device_t device = rt_device_find("lcdlight"); // Find the backlight device
    if (device)
    {
        rt_err_t err = rt_device_open(device, RT_DEVICE_OFLAG_RDWR); // Open the device
        uint8_t val = br;
        rt_device_write(device, 0, &val, 1); // Set the backlight value
        rt_device_close(device); // Close the device (does not turn off the backlight)
    }

LCD_IdleModeOn¶

TODO.

LCD_IdleModeOff¶

TODO.

LCD_Rotate¶

TODO.

LCD_TimeoutDbg¶

TODO.

LCD_TimeoutReset¶

TODO.

LCD_ESDCheck¶

TODO.