Towards a general display interface

[u77345]

How do I add an SPI LCD to be used with 2DGraphics and potentially as ScreenDevice and CharDevice?
I started an implementation at https://github.com/u77345/circle/blob/master/addon/display/ili9341.cpp

[dlbogdan]

Coincidentally, I’m building a generic driver class + an implementation for an SSD1322 oled display to go with it. I am tailoring it to go with lvgl addon though. We should talk and add your LCD as well to the mix.

[u77345]

LVGL makes sense. I see samples/lvgl uses circle's CScreenDevice. Happy to collaborate.

[dlbogdan]

Only the Circle lib provided wrapper class CLVGL uses 2DGraphics, not lvgl itself. Initially I wanted to go the same route but there is a lot to modify in 2DGraphics class because it’s tailored with RGB 16/32bpp displays on DSI/HDMI in mind, with hardware framebuffer. My OLED for example is a 4bpp grayscale display. It’s a lot easier to build my own generic driver class for I2C/SPI and the OLED driver itself as well as others that come in my hand, and then in the same files create another wrapper class for LVGL. Also the project I’m working on will not have any pointing devices at all, as the inputs will be from rotary encoders and buttons. CLVGL wrapper class expects on having a mouse or a touchscreen, which is fine for a lot of cases but not all of them as you may see.

[u77345]

I have identical requirements - to fit ILI9341 into MiniDexed, on board with your approach.

[dlbogdan]

Great. As soon as I finish my classes and test a bit, I’ll share my generic driver class as well as the lvgl wrapper so you can test with your display. I’m aiming to make the lvgl wrapper it a seemless swap with CLVGL, compatible so existing apps such as minidexed should only initialize the display hardware by the use of its driver constructor and use it with no other modifications.

[dlbogdan]

https://youtube.com/shorts/eMTahYKymk0?feature=share

It works!
what’s left:

• clean up the hardcoding to make it truly generic
• optimize a bit (maybe DMA transfers, we’ll see)
• Another class for encoders and gpio buttons as inputs

what you should have ready in the meantime:
A putpixel function that uses an internal framebuffer
A flush function that writes the framebuffer to the screen
A init function that initializes the display.
optionally: a blitter function that converts and copies a lv_color_t * frambuffer (32bpp for ex) to your native framebuffer format.
if you use dma, you also need a function that gets called when the transfer finishes.

Regards.

[rsta2]

How do I add an SPI LCD to be used with 2DGraphics and potentially as ScreenDevice and CharDevice?

Unfortunately this is currently not supported. I think, this shouldn't be included directly in CScreenDevice and C2DGraphics. There should be separate classes for SPI LCD displays in addon/display for this purpose and it should be possible to extend this for other SPI displays in the future. For LVGL I think, there should also a specific class (e.g. CLGVL_SPI). I wouldn't mix SPI support with the frame buffer. Where it makes sense, a generic base class could be used. I'm open for suggestions.

[dlbogdan]

Hi Rene,
First of all, thank you immensely for your work. I can’t really be thankful enough for Circle.
Now, I have a personal project in my hands and am taking the opportunity to build two new generic driver classes for LVGL/Circle:
One, a wrapper class CGLVGL for the lvgl graphics, to interface with various spi/i2c screens of various depth and resolutions.
And a second one CILVGL for the lvgl input handling , customizable with rotary encoders and buttons attached to GPIOs on the raspberry pi.
Even though I lack time, as I have two small kids, I’m confident that I can have something production ready in about a week or two.

Best to you!

[rsta2]

Thank you! I'm looking forward to your contribution.

[dlbogdan]

Short update:
Got a lot of things working smoothly, some aren’t yet done, as I’ve had a terribly busy week at work. Had to remake the rotary encoder on my own implementation as the one included in circle/addon/sensor wouldn’t work at all, at least on raspberry pi zero.

Anyway, here’s a video. Two types of input devices: 4 buttons in corners (on GPIOs) and a rotary encoder.
The menu you’re seeing in the video is part of a bigger project, which I will make open source when done, as well as all the classes, drivers for displays and inputs that I needed to do.

https://youtu.be/a7K2PldYtTE

[rsta2]

Looks good! Take the time, you need. There's no hurry.

[u77345]

@dlbogdan Would you be open to collaborate on the driver?

[rsta2]

Towards a general display interface

I was dealing with the question, how different dot-matrix displays (e.g frame buffer, SPI LCDs) can be supported for different modes (e.g. Terminal, 2D graphics, LVGL GUI), and how Circle can support this in a flexible (i.e. use any display in any mode), efficient (i.e. performative), backwards compatible and possibly simple (i.e. easy to use) way. There is a preliminary version on the branch general-display-interface now. Feedback is very welcome and modifications are possible.

CDisplay

The dot-matrix display support is based on the new class CDisplay. It provides methods for color conversion between different color models and virtual methods, which form a general interface for displaying pixel information on a display (a single pixel or an area (rectangle) of pixels).

It defines a logical color type (TColor), which is RGB888, with some predefined colors. Colors of this type can be converted into different color models, used on the display hardware. These colors are represented by the type TRawColor. The following color models are supported at the moment:

• RGB565
• RGB565_BE (big endian, for the ST7789 display driver)
• ARGB8888
• I8 (index into palette)

The classes CBcmFrameBuffer and CST7789Display have been extended to be derived from CDisplay and to implement the general methods for displaying pixel information. Their previously implemented methods still exist.

CTerminalDevice

There is a new class CTerminalDevice, which provides the features of a scroll-able terminal display device, which was implemented in the class CScreenDevice before. As an advantage CTerminalDevice is independent from the class CBcmFrameBuffer and thus can be used on any display, which implements the CDisplay interface.

For compatibility the class CScreenDevice still exists, and uses the classes CTerminalDevice and CBcmFrameBuffer for its implementation.

The sample/08-usbkeyboard can be run on a ST7789-based SPI display now too.

C2DGGraphics

The class C2DGGraphics has a new constructor, which gets called with a pointer to a CDisplay-derived object (e.g. CST7789Display) and thus can be used to create 2D graphics on an LCD display for example. The existing double-buffered and Vsync-honoring support for CBcmFrameBuffer displays still exists.

C2DGGraphics now generally uses logical colors (CDisplay::TColor, alias T2DColor). This allows to implement applications, which are independent from the real display hardware, where they should running on.

The sample/41-screenanimations can be run on a ST7789-based SPI display now too.

CLVGL

The class CLVGL has a new constructor, which gets called with a pointer to a CDisplay-derived object (e.g. CST7789Display) and thus can be used to show a LVGL GUI on any display, which supports the CDisplay interface.

The class CLVGL now generally uses a LVGL mouse cursor, which was necessary, because only CBcmFrameBuffer-based displays are working with the firmware provided mouse cursor.

The addon/LVGL/sample can be run on a ST7789-based SPI display now too.

CWindowDisplay

The class CWindowDisplay is a CDisplay instance in a CDisplay and allows to use multiple (non-overlapping) windows on a display. In this window a CTerminalDevice, C2DGraphics or CLVGL instance can be displayed.

Currently the CLVGL instance has to be in the top left window of the underlying display, because of the support for input devices (mouse, touchscreen). Only the Raspberry Pi official 7" touchscreen (v1) has been tested so far.

The sample/43-multiwindow demonstrates this class in a multi-core application.

CCharGenerator

The class CCharGenerator has been extended to provide select-able fonts with the option to use a doubled width and/or height of the font. Four new fonts with 8, 10, 12 and 14 pixels height have been added. Only the actually used fonts will be included in the kernel image.

The constructors or text drawing methods of the classes CTerminalDevice, C2DGGraphics, CScreenDevice, CST7789Display and CST7789Device allow to specify the font and font options now.

Options

The following (system) options control the display support:

• DEPTH (8, 16 or 32 bits depth for CScreenDevice and C2DGGraphics in frame buffer mode)
• DEFAULT_FONT (default system font for frame buffer based displays)
• SCREEN_DMA_BURST_LENGTH (DMA burst length for screen (i.e. frame buffer) updates or non-DMA mode (NO_SCREEN_DMA_BURST_LENGTH)
• SCREEN_HEADLESS (still supported for using CScreenDevice without an attached display)

The class CST7789Display has a new parameter bSwapColorBytes, which enables the big endian mode for colors (default), which can be disabled now.

Compatibility

There are only a few API breaking changes. Most display classes can be used as before.

The class C2DGGraphics uses different (logical) colors now. This must be adapted. Also sprite images must be converted to raw colors now, if specified in logical colors. There is a new class C2DImage for this purpose.

The constructors of the classes CScreenDevice and CST7789Device have been modified slightly to be able to specify the used font.

The "virtual buffer" mode of CScreenDevice has been removed, because it was not that easy to implement now, and I did not know anybody, who was using it.

The constructor of the class CLVGL does not get a pointer to the interrupt system any more.

Future work

It should be easier now to implement new drivers for other currently unsupported displays to be able to use them with existing applications. If somebody wants to work in this direction, this would be highly appreciated.

[rsta2]

ILI9341-based SPI displays are supported now too in sample/08-usbkeyboard, sample/41-screenanimations and addon/lvgl/sample on the branch general-display-interface. ST7789-based displays were already supported. Thanks to @u77345, who's driver (see the first comment) helped very much to get the ILI9341 support working.

[rsta2]

There is a driver for SSD1306-based I2C displays now on the general-display-interface branch in addon/display/ssd1306display.*, which supports the CDisplay interface. Thus it can be used with sample/08-usbkeyboard, sample/41-screenanimations and addon/lvgl/sample. Furthermore a driver for XPT2046-based touchscreens has been implemented.

[rsta2]

With the latest change on the branch general-display-interface an USB mouse or touchscreen can be used in any window of a multi-window application now, independent from the position of the window on the display. Only one window on a display can use the mouse or touchscreen. Furthermore an optional lazy update mode for CTerminalDevice and CScreenDevice has been implemented.

This was probably the last modification for the new general support for dot-matrix displays. I will merge the feature to the develop branch on Dec 9, if there are no wishes for changes until then.

API breaking changes

There are some API breaking changes, which come with the new display support:

• The class CScreenDevice has a changed constructor for supporting font selection. The support for virtual-only screen buffers and the parameter bVirtual have been removed.

• The class C2DGraphcis does not work with TScreenColor colors any more, but uses T2DColor logical colors (RGB888), which are the same for all displays. This was necessary to support 2D graphics on SPI- and I2C- displays. Because colors have to be converted now, the performance may be slightly smaller. There is a new class C2DImage for the color management of 2D sprites.

• The constructor of the class CLVGL does not get a pointer to the CInterruptSystem object any more.

• The constructor of the class CST7789Device has a changed parameter list for supporting font selection.

• The method CMouseDevice::Setup() now gets a pointer to the used CDisplay instance, instead of the screen width and height.

• The class CTouchScreenDevice has a new Setup() method, which must be called before any other method. SetCalibration() does not receive the screen width and height any more.

• For the class CDMAChannel the completion routine has to be set before each asynchronous transfer now. Previously it was enough to set it once.

Despite the last listed modification, all changes will lead to compiler errors on build, so they can be sorted out relatively quick.

[rsta2]

The feature branch general-display-interface has been merged to develop and removed afterwards.