Run-Time Display Rotation

The Moddable SDK now supports rotating the image shown on displays using features built into some display controllers. This allows the display to be rotated to 0, 90, 180, and 270 degrees at any time with no added overhead.

Build-time Rotation with Software

The Moddable SDK has always included support for drawing to displays at 0, 90, 180, and 270 degrees of rotation. The Poco graphics renderer implements rotation with no reduction in performance and no additional RAM use. It achieves this result independent of microcontroller and display controller by rotating the pixels at build-time. The only work done at run-time is relatively simple coordinate transformations. Because the pixels are rotated at build-time, the application is limited to the rotation selected at build-time. This approach works well for devices with a display in a fixed orientation.

Run-time Rotation with Hardware

The Moddable SDK has added support for using the hardware rotation feature built into some display controllers. By using hardware features, the rotation is zero overhead, like the original software-only approach. Unlike the software-only approach, rotation performed in hardware may be changed at run-time, making it possible to use several screen rotations in a single application.

For example, with run-time rotation a product with a built-in accelerometer is able to rotate the screen to match the orientation of the device, just like a phone. The M5Stack Fire platform support has been enhanced to support this feature. Further information is provided below.

The ILI9341 display driver is the first and only display driver in the Moddable SDK enhanced with support for run-time rotation. The ILI9341, and other compatible controllers based on the MIPI Display Serial Interface standard, are widely used.

Warning: Don’t mix build-time and run-time rotation. Because not all display controllers support run-time rotation, the original Moddable SDK support for zero-overhead rotation performed at build-time remains available. These two forms of rotation are incompatible. Only use one of them in your project.

Using Run-time Rotation with Commodetto

The API for display drivers based on the Commodetto PixelsOut class has been enhanced to support run-time rotation.

Detecting

Not all display controllers support hardware rotation. If a display driver implements rotation, it returns a numeric value for its rotation property. A display driver that does not support rotation returns undefined. On the ESP32 and ESP8266, the display driver instance is in the screen global:

if (undefined === screen.rotation)    
    trace("run-time rotation unavailable");
else    
    trace("run-time rotation available!");

Changing

Set the display driver’s rotation property to change to a supported value. The supported values vary by display driver. The ILI9341 supports 0, 90, 180, and 270.

screen.rotation = 90;

Note that changing the rotation may not update the display. The result depends on the display driver. In most situations, the application will need to redraw the display immediately.

The width and height properties of the display driver instance change based on the rotation. For example, on a Moddable Zero the width is 240 and height is 320 when rotation is 0, and their values are swapped when rotation is 90.

Using Run-time Rotation with Piu

The Piu user interface framework has been updated to support run-time rotation. Applications built with Piu should not access the rotation property of the display driver directly, and should instead use the Piu-provided APIs.

Detecting

If run-time rotation is supported, then the value of application.rotation is a number; otherwise, it is undefined.

if (undefined === application.rotation)
    trace("run-time rotation unavailable");
else
    trace("run-time rotation available!");

Changing

To change the run-time rotation in a Piu application, set the application’s rotation property.

application.rotation = 90;

When Piu changes the run-time rotation it also invalidates the entire display to force all content to be redrawn at the new rotation.

Adjusting Layout

If the display dimensions change as a result of a change in rotation, Piu performs layout on the content. This is the same as what happens in a Piu application such as xsbug running on a computer when its window is resized. During this process any Layout content objects will receive onFitHorizontally and onFitVertically events as necessary to adjust to the new display size. For an example, see the Piu cards example.

Run-time Rotation on M5Stack Fire

The M5Stack Fire is an ESP32-based development board with a built-in display and accelerometer. The Moddable SDK support for the M5Stack Fire has been updated to automatically change the rotation of the screen to match the physical orientation of the device.

Piu applications that do not want to use this feature can disable it in the config section of their manifest.

"config": {    "autorotate": false,},

The implementation of rotation is done in the M5Stack Fire setup code.

Conclusion

Run-time display rotation using the built-in hardware capabilities of display controllers opens exciting new possibilities for building user interfaces on low-cost hardware with microcontrollers. We have already seen one remarkably clever user of this capability in a customer project. We look forward to seeing how other developers use it.