I wanted to display circle shaped images on the screen - like this:
It looks ok, if the dark M5ez theme was used, but it looks ugly when the theme was switched to default.
I wanted to have a good looking solution, so I investigated the various image formats supported by the M5Stack LCD API
According to the documentation, M5Stack Arduino API supports the following image formats:
From these file formats only PNG supports transparency.
The XBMP file format is a binary format. It means that the images are displayed in two colors - one background and one foreground.
The PNG file type support is not documented on the API, but it is available on the code level.
The images can come from these two places:
Memory means Flash memory. It means that the image data was transformed into an array and stored in a C header file, which will be included into the main program.
// Image data in FLASH memory
File is the original image file. It is usually stored on an SD card.
In M5Stack the following storage type restrictions applies:
The following file formats can come from FLASH memory:
In case of BMP the color code is expressed by a total of 16 bits: red 5 bits, green 6 bits and blue 5 bits from the top. It means only 16 bpp (bit per pixel) BMP files are supported.
The following online converter tools are recommended:
The following file formats can come from an SD card:
Please note that only 24 bpp (bit per pixel) - True Color - BMP files are supported!
At the time of writing M5ez only supports the JPEG file format. I thought that it would be great that the other file formats become available as well. I implemented the required changes in my GitHub fork. Of course I will contribute these back to M5ez in a pull request.
I also created an example called M5images, which displays an image menu with all the available M5Stack file formats and storage types.
Just go back to the original problem, where I wanted to display a circle shaped image with transparent background.
Of course I can put the original PNG file onto an SD card and display it in the menu. There are two problems with this approach:
- Application distribution
Once you build your application in Arduino, you just put all files into a single directory. These files then can be compiled and uploaded by Arduino IDE onto your microcontroller development board like the M5Stack M5Core device.
If something has to be installed onto the SD card prior to these steps, it just introduces complications and further error conditions for the end users.
The obvious solution is to store those images, which are essential part of your application in the Flash memory. The downside of this solution is the limited capacity of the Flash memory compared to the SD card.
Once it is done and the application is started, speed will be a problem. The PNG files are loaded quite slowly from SD card. M5Stack renders these images with a considerable delay. You can spot the scrolling load on the UI. It means no go for frequently used places - like menus - in the application.
XBMP was ruled out at the first place, because its binary nature. Two color images just look ugly.
There are two options left:
Both of them are non transparent image types, so this problem has to be solved later.
- Cut down rounded edges
- Distort the image
- Change some colors
After the image conversion the end result is not looking as good as the original PNG file.
I solved the transparency issue with two images for the two themes:
- Default - #EFEFEF (RGB888) = 0xEF7D (RGB565) as the background color
- Dark - #000000 (black) as the backgound color
The images in the M5images example comes from IconArchive free image collection.