Storyboard Plugins on MCU Hardware

November 02, 2021 00:39

Introduction

The Storyboard Engine has been designed to provide features through a plugin interface. This means that features can be removed or added dynamically at compile time. In an MCU environment, the process that is used to add in the plugins involves telling the engine which plugins are loaded using a structure in a header file and by making sure that the correct libraries are compiled into the binary that is going to be deployed to the target hardware.

Adding a plugin

Adding a plugin to the header file

The header file that controls which plugins are going to be loaded by the Storyboard Engine is called static_plugins.h and it is responsible for providing the engine with a list of plugins to iterate through and initialize. Here is an example of the static_plugins.h header file:

* For more information email info@cranksoftware.com.

#include <gre/sdk/plugin.h>

* This is a list of the available plugins. Add the functions to the plugin list

* below to make the features available to your application

// gre plugins

extern int gre_plugin_animate(gr_plugin_state_t *);

extern int gre_plugin_script_lua(gr_plugin_state_t *);

extern int gre_plugin_greio(gr_plugin_state_t *);

extern int gre_plugin_logger(gr_plugin_state_t *);

extern int gre_plugin_timer(gr_plugin_state_t *);

// Render extension plugins

extern int gre_plugin_circle(gr_plugin_state_t *);

extern int gre_plugin_poly(gr_plugin_state_t *);

const gr_plugin_create_func_t sb_plugins[] = {

gre_plugin_animate,

gre_plugin_script_lua,

gre_plugin_greio,

gre_plugin_circle,

gre_plugin_logger,

gre_plugin_poly,

gre_plugin_timer,

NULL,

};

If the gradient plugin was to be added to the engine, then the following declaration would need to be added:

extern int gre_plugin_gradient (gr_plugin_state_t *);

and the following would need to be added to the sb_plugins array:

gre_plugin_gradient,

The resulting header file would look like this:

* For more information email info@cranksoftware.com.

#include <gre/sdk/plugin.h>

* This is a list of the available plugins. Add the functions to the plugin list

* below to make the features available to your application

// gre plugins

extern int gre_plugin_animate(gr_plugin_state_t *);

extern int gre_plugin_script_lua(gr_plugin_state_t *);

extern int gre_plugin_greio(gr_plugin_state_t *);

extern int gre_plugin_logger(gr_plugin_state_t *);

extern int gre_plugin_timer(gr_plugin_state_t *);

extern int gre_plugin_gradient(gr_plugin_state_t *);

// Render extension plugins

extern int gre_plugin_circle(gr_plugin_state_t *);

extern int gre_plugin_poly(gr_plugin_state_t *);

const gr_plugin_create_func_t sb_plugins[] = {

gre_plugin_animate,

gre_plugin_script_lua,

gre_plugin_greio,

gre_plugin_circle,

gre_plugin_logger,

gre_plugin_poly,

gre_plugin_timer,

gre_plugin_gradient,

NULL,

};

Adding in the plugin library

In order for the functionality to be included in the binary that is being deployed to the target, the plugin library needs to be added to the list of libraries that are referenced in the tooling that is being used to create the binary for the target.

To continue along with this example, if the gradient plugin was the functionality that was being added, here are the steps to follow.

The gradient functionality is included in the library libgre-plugin-gradient.a. Below are the steps to include this library based on which IDE might be used.

Adding the plugin library in IAR

To add the libgre-plugin-gradient library to an IAR project, click “Project->Options” and select the “Category: Linker with Library” entry from the list on the left hand side. Beside “Additional libraries” Click the ‘ellipsis’ button to display an “Edit Additional Libraries” dialog. Move to the end of the list and <Click to add> following libraries and add in the libgre-plugin-gradient.a. Typically this will need to include the path to the library, and if the setup that has been recommend from the integration guides has been followed this will be:

$PROJ_DIR$/../../../../../../<RUNTIME_NAME>/plugins/libgre-plugin-gradient.a

Where <RUNTIME_NAME> is the name of the runtime that is being used.

Adding the plugin library in MCUXpresso

To add the gradient plugin to the compiler libraries, right click on the project and select “Properties”. In the properties pane expand the “C/C++Build” tree item in the pane that is on the left hand side of the screen. From the expended tree item, select “Settings”. In the settings pane on the right hand side, expand the tree item “MCU Linker” and select ”Libraries”. Add gre-plugin-gradient to the pane labelled “Libraries (-l)”

Adding the plugin library in STM32CubeIDE

To add the gradient plugin to the compiler libraries, right click on the project and select “Properties”. In the properties pane expand the “C/C++Build” tree item in the pane that is on the left hand side of the screen. From the expended tree item, select “Settings”. In the settings pane on the right hand side, expand the tree item “MCU GCC Linker” and select ”Libraries”. Add gre-plugin-gradient to the pane labelled “Libraries (-l)”

Appendix A: Plugin List for Storyboard Engine

Library Name	libgre-plugin-animation.a
Declaration	extern int gre_plugin_animate(gr_plugin_state_t *);
Plugin Entry	gre_plugin_animate
Description	Enables the animation functionality in Storyboard
Additional Requirements	None

Library Name	libgre-plugin-capture-playback.a
Declaration	extern int gre_plugin_captureplayback(gr_plugin_state_t *);
Plugin Entry	gre_plugin_captureplayback
Description	Enables the playback functionality in the Storyboard engine. The capture functionality is disabled in the VFS configuration of the engine
Additional Requirements	A capture file to play back

Library Name	libgre-plugin-canvas.a
Declaration	extern int gre_plugin_canvas(gr_plugin_state_t *);
Plugin Entry	gre_plugin_canvas
Description	Enables dynamic drawing through the use of the Canvas Lua API
Additional Requirements	Lua plugin

Library Name	libgre-plugin-ccallback.a
Declaration	extern int gre_plugin_c_callback(gr_plugin_state_t *);
Plugin Entry	gre_plugin_c_callback
Description	Enables the C callback actions in runtime
Additional Requirements	None

Library Name	libgre-plugin-circle.a
Declaration	extern int gre_plugin_circle(gr_plugin_state_t *);
Plugin Entry	gre_plugin_circle
Description	Enables the circle render extension functionality in the runtime
Additional Requirements	None

Library Name	libgre-plugin-gradient.a
Declaration	extern int gre_plugin_gradient(gr_plugin_state_t *);
Plugin Entry	gre_plugin_gradient
Description	Enables the gradient render extension functionality in the runtime
Additional Requirements	None

Library Name	libgre-plugin-greio.a
Declaration	extern int gre_plugin_greio(gr_plugin_state_t *);
Plugin Entry	gre_plugin_greio
Description	Enables the use of the Storyboard IO connection API
Additional Requirements	None

Library Name	libgre-plugin-gesture.a
Declaration	extern int gre_plugin_gesture(gr_plugin_state_t *);
Plugin Entry	gre_plugin_gesture
Description	Enables the use of gestures to invoke actions. There are predefined gestures as well as the ability to use custom gestures
Additional Requirements	None

Library Name	libgre-plugin-logger.a
Declaration	extern int gre_plugin_logger(gr_plugin_state_t *);
Plugin Entry	gre_plugin_logger
Description	Enables additional logging features for the runtime, such as the ability to buffer logging messages in a predefined memory buffer.
Additional Requirements	logging-util library that is provided in the runtime

Library Name	libgre-plugin-lua.a
Declaration	extern int gre_plugin_lua(gr_plugin_state_t *);
Plugin Entry	gre_plugin_lua
Description	Enables the use of Lua scripting with the engine.
Additional Requirements	None

Library Name	libgre-plugin-luagredom.a
Declaration	extern int gre_plugin_luagredom(gr_plugin_state_t *);
Plugin Entry	gre_plugin_luagredom
Description	Enables the use of the Storyboard Lua DOM API in Lua scripts
Additional Requirements	Lua plugin

Library Name	libgre-plugin-metrics.a
Declaration	extern int gre_plugin_metrics(gr_plugin_state_t *);
Plugin Entry	gre_plugin_metrics
Description	Enables the reporting of the CPU usage, memory usage, FPS and model memory usage for the running Storyboard application
Additional Requirements	The logging-util library shipped with the runtime

Library Name	libgre-plugin-poly.a
Declaration	extern int gre_plugin_poly(gr_plugin_state_t *);
Plugin Entry	gre_plugin_poly
Description	Enables the use of the polygon render extension
Additional Requirements	None

Library Name	libgre-plugin-rtext.a
Declaration	extern int gre_plugin_rtext(gr_plugin_state_t *);
Plugin Entry	gre_plugin_rtext
Description	Enables the use of the rich text render extension
Additional Requirements	None

Library Name	libgre-plugin-screen-drag.a
Declaration	extern int gre_plugin_screen_drag(gr_plugin_state_t *);
Plugin Entry	gre_plugin_screen_drag
Description	Enables the use of the screen drag functionality
Additional Requirements	The corresponding screen transition plugins that the screen drag is to invoke, for example the screen-path screen transition plugin

Library Name	libgre-plugin-screen-dump.a
Declaration	extern int gre_plugin_screen_dump(gr_plugin_state_t *);
Plugin Entry	gre_plugin_screen_dump
Description	Allows for the application to dump the current contents of the screen to an image. Note that on an MCU platform the output will be printed in a Base64 format that will need to be decoded.
Additional Requirements	The png and sbz libraries that are shipped with the runtime

Library Name	libgre-plugin-screen-fade.a
Declaration	extern int gre_plugin_screen_fade(gr_plugin_state_t *);
Plugin Entry	gre_plugin_screen_fade
Description	Enables the screen fade screen transition
Additional Requirements	None

Library Name	libgre-plugin-screen-path.a
Declaration	extern int gre_plugin_screen_path(gr_plugin_state_t *);
Plugin Entry	gre_plugin_screen_path
Description	Enables the screen path screen transition
Additional Requirements	None

Library Name	libgre-plugin-sbimage-png.a
Declaration	extern int gre_plugin_sbimage_png(gr_plugin_state_t *);
Plugin Entry	gre_plugin_sbimage_png
Description	Enables the use of the PNG image loader to load PNG’s
Additional Requirements	The png and sbz libraries that are shipped with the runtime

Library Name	libgre-plugin-sbimage-soil.a
Declaration	extern int gre_plugin_sbimage_soil(gr_plugin_state_t *);
Plugin Entry	gre_plugin_sbimage_soil
Description	Enables the use of the soil image loader to load images
Additional Requirements	The soil library that is shipped with the runtime

Library Name	libgre-plugin-timer.a
Declaration	extern int gre_plugin_timer(gr_plugin_state_t *);
Plugin Entry	gre_plugin_timer
Description	Enables the use of the timer action in the Storyboard Engine
Additional Requirements	None

Library Name	libgre-plugin-trace.a
Declaration	extern int gre_plugin_trace(gr_plugin_state_t *);
Plugin Entry	gre_plugin_trace
Description	Enables the use of the performance tracing functionality in the engine
Additional Requirements	The logging-util library that is shipped with the runtime.