Storyboard 7.0 Migration Guide

The purpose of this document is to outline the Storyboard migration strategy for various platforms from previous versions to 7.0. While our latest version remains backwards compatible, this guide documents changes you should consider to get the most out of Storyboard.

Build configuration changes for MCU Platforms

Logging and tracing API

The logging and tracing API has changed, with the plugins broken out into discrete functional blocks. This requires additional configuration for the linker and sbengine_plugins.h. The logging plugin now requires the additional library “logging-util” to be added to the project list of libraries.  This library should be added after the plugin libraries.

To enable performance output, the following will need to be done:

Add the following declaration to the static_plugins.h header file:

   extern int gre_plugin_trace (gr_plugin_state_t *);

In the sb_plugins array structure, add the following entry before the NULL:

   gre_plugin_trace

Add the following library to the linker:

   gre-plugin-trace

If the “logging-util” library was not added to support the logging plugin, add the “logging-util” library to the project list of libraries.

To enable metrics output, the following will need to be done:

Add the following declaration to the static_plugins.h header file:

   extern int gre_plugin_metrics (gr_plugin_state_t *);

In the sb_plugins array structure, add the following entry before the NULL:

   gre_plugin_metrics

Add the following library to the linker:

   gre-plugin-metrics

If the “logging-util” library was not added to the project library list, add the “logging-util” library to the project list of libraries.

Image loading plugins

Storyboard now supports two different image loading plugins: One based on the Simple OpenGL Image Loader (SOIL) library used by Storyboard in the past, and a new image loading plugin based on the png library. An image loading plugin now needs to be loaded as part of the plugins that Storyboard Engine uses. On an MCU platform, this is done by adding the plugin to the static_plugins.h header file.

To use the older soil plugin:

Add the following declaration to the header file:

   extern int gre_plugin_sbimage_soil(gr_plugin_state_t *);

In the sb_plugins array structure, add the following entry before the NULL:

   gre_plugin_sbimage_soil

Add the following library to the linker:

   gre-plugin-sbimage-soil

To use the newer PNG plugin:

Add the following declaration to the header file:

   extern int gre_plugin_sbimage_png(gr_plugin_state_t *);

In the sb_plugins array structure, add the following entry before the NULL:

   gre_plugin_sbimage_png

Add the following library to the linker:

   gre-plugin-sbimage-png
   png
   sbz

Freetype font library

The version of the Freetype font library used by Storyboard has been updated. This change introduced a dependency on the PNG and Z libraries that are shipped with Storyboard, meaning that MCU projects using the Freetype font manager need to include the following additional libraries:

• png
• z 

The minimum requirements for the stack have increased when using the Freetype font manager. Therefore, when launching the Storyboard engine task on an MCU platform, set the stack size parameter to a minimum of 8096.

Lua execution changes

The parameters to Lua callback functions are lazily generated, meaning the content is populated as soon as one of the member variables of the callback argument (frequently called mapargs) is accessed within the callback. This trend of ‘load on access’ allows faster callback invocation for scenarios where the arguments are not being examined because the context of execution is known.

This may cause problems for clients that are saving the argument (aka mapargs) without accessing any of the member variables, as they will appear as nil values when they are accessed later as the context is no longer available.

To work around this, the old, non-optimized, behaviour can be accessed using:

   -olua,lazy_context=0

Alternatively, if the situation is very specific, simply accessing one of the member variables is enough to populate that value:

   function MyCallback(mapargs)
      local event = mapargs.context_event

Runtime naming changes

The 64-bit runtime names have been updated in Storyboard 7.0 which may result in runtime configuration errors, as x86 should be replaced with x86_64.  A common place where this may occur is in the configuration of the Lua module library paths package.path and package.cpath, where the convention of using OS + CPU is often used to separate different binary modules. For example, the macOS engine name is now “macos-x86_64” instead of “macos-x86” .

To avoid runtime configuration errors, ensure that all references to 64-bit runtimes are updated to the new naming convention.

Focus behaviour changes

Focus events on controls and table cells are no longer generated when an object is intersected with a press (gre.press) event, rather they occur when a touch (gre.touch) event is received. A touch is defined as a press or release on top of the same control or table cell. This behaviour allows more flexibility in the use of focus events in scrolling scenarios where target objects may be on the move and activation should not occur until the motion has stopped.

Historical projects that need to maintain the same behaviour can adjust the historical control focus selection to be based on a press (gre.press) event rather than the focus events.

Linux framebuffer (fbdev) changes

Color format

In previous versions of Storyboard Engine, the color format of the fbdev device wasn’t changed. If the color format of the device didn’t match the color format of the Storyboard application, the color format for drawing was adapted to match the color format of the device.

With Storyboard 7.0, an attempt is made to set the color format of the fbdev driver to match the color format of the Storyboard application. If this change is not accepted by fbdev, Storyboard automatically falls back to using the color format that the device uses, if possible.

Furthermore, a render manager option has been added (-orender_mgr,pixel_format=[format]) to permit users to specify a color format to use as an override for the color format associated with the Storyboard application. See Storyboard Engine Plugin Options for more details.

Drawing mode

In previous versions of Storyboard Engine, the default drawing mode when using fbdev was single-buffered mode. In Storyboard 7.0, the default drawing mode when using fbdev is double-buffered mode. The -orender_mgr,num_buffers=[n] plugin option can be used to override the default. See Storyboard Engine Plugin Options for more details.

Storyboard Engine command line option changes

See Storyboard Engine Plugin Options for the complete set of command line options.

   -olua,lazy_context=[0|1]

The default behavior for this option has changed as follows:

• The Lua callback context is created as it is accessed (1, default for 7.0)
• The context is created prior to every Lua action call (0, default prior to 7.0)

   -orender_mgr,pixel_format=[format]

New for 7.0: Override the application's pixel format. This option is specific to the Linux fbdev render manager.

   -oscreen_mgr,one_damage_area=[0|1]

This controls whether multiple screen damage areas are used (0, 7.0 default) or if they are unioned into a single damage area (1, pre-7.0 behaviour in some situations).

This is applicable for swrender render managers and OpenGL render managers when the backbuffer option is used.