When building a target configuration all of the application files and target binaries must be copied to the target system. The following is a description of the files needed for the target system and their runtime requirements. Collectively these files are referred to as a Storyboard deployment bundle.
The deployment bundle must be accessible to the embedded target. The deployment bundle is exported from a Storyboard Designer model to a location on the host file system. For more information creating a deployment bundle, refer to the section Exporting to Storyboard Embedded Engine in this document.
A deployment bundle generally includes:
A Storyboard application file (required). These are usually files
with the extension .gapp.
A scripts directory (optional). These are usually Lua
script files that provide glue logic for the application
An images directory (optional). These are image
assets that are required by the application.
A fonts directory (optional). These are fonts that
are required by the application
Users may include additional directories as required by the application, but these are the standard contents of a deployment bundle
The directory structure below the root directory of the deployment bundle should not have its layout changed after being exported from Designer. All paths using within a Storyboard application for resources such as images, fonts and scripts are relative to the base directory containing the Storyboard application.
An engine execution environment is provided for each supported operating system, architecture and rendering system. The target system should be configured with the Engine (sbengine) and plugins required for the target application. All plugins are loaded via the SB_PLUGINS environment variable and all libraries are loaded via the LD_LIBRARY_PATH environment variable.
For example:
export SB_PLUGINS=/home/crank/linux-imx6yocto-armle-opengles_2.0-obj/plugins
export LD_LIBRARY_PATH=/home/crank/linux-imx6yocto-armle-opengles_2.0-obj/lib
On Windows systems, there is no LD_LIBRARY_PATH so the PATH environment
variable should be used instead. Similarly on MacOS, DYLD_LIBRARY_PATH should be
used instead of LD_LIBRARY_PATH
The Storyboard Engine executable (sbengine) is located in the bin folder of the Storyboard Engine directory structure. Now that the Storyboard Engine and Storyboard application (development bundle) are located on the embedded target and the Environmental Variables have been set, the Storyboard Engine can run a Storyboard application as follows:
sbengine thermostat.gapp
The Storyboard Engine is a self contained executable which loads plugins for added functionality. The Engine can be run as follows:
sbengine [-i] [-v] [-o] [storyboard application]
Table 3.1. Options
| OPTION | DESCRIPTION |
|---|---|
| -i | displays which version of sbengine and related libs are being used |
| -v | verbosity, more v’s means more verbose output. |
| -o | plugin or manager options |
Each plugin or manager defines its name and possible options.
As the verbosity level to storyboard is increased, you will see more information about the execution of the runtime engine.
Table 3.4. IO Manager Options
| OPTION | DESCRIPTION |
|---|---|
| -oio_mgr,queue_size=4096 | will limit the event queue size to a maximum of 4K. If the queue exceeds this size, events will be dropped and diagnostic messages will be logged regarding the dropped events. The default behaviour is to have an unlimited event queue size. |
Table 3.5. Model Manager Options
| OPTION | DESCRIPTION |
|---|---|
| -omodel_mgr,plugin_path=/temp | Sets the plugin path to the specified directory (/temp in this example). This setting overrides the SB_PLUGINS environment variable setting. |
| -omodel_mgr,fps=25 | Limits the frame rate for all animations to a maximum fps specified (25 in this example). |
| -omodel_mgr,mem_stats=1 | On platforms where process/task memory usage or heap allocator memory usage values are available, report them as performance log metrics. The value should be set to 1 to enable the statistics, future values are reserved. |
Table 3.6. Render Manager Options: Windows, win32, OpenGL ES 2.0, x86
| OPTION | DESCRIPTION |
|---|---|
| -orender_mgr,x=[xpos] | This will position the application at the defined x-position |
| -orender_mgr,y=[ypos] | This will position the application at the defined y-position |
Table 3.7. Render Manager Options: Linux, sdl, x86
| OPTION | DESCRIPTION |
|---|---|
| -orender_mgr,quality=[0|1|2] | Quality of image rotation. The default, 0 is fastest but lowest quality rendering. A setting of 2 is highest quality but slowest performing. |
Table 3.8. Render Manager Options: Linux, fbdev, x86, armle
| OPTION | DESCRIPTION |
|---|---|
| -orender_mgr,dblbuffer | Enable double buffering (fullscreen redraws) |
| -orender_mgr,fb=[device path] | The path to the framebuffer device to use (default=/dev/fb0) |
| -orender_mgr,fullscreen | Run in fullscreen mode |
| -orender_mgr,quality=[0|1|2] | Quality of image rotation. The default, 0 is fastest but lowest quality rendering. A setting of 2 is highest quality but slowest performing. |
Table 3.9. Render Manager Options: Linux, directfb, x86, armle
| OPTION | DESCRIPTION |
|---|---|
| -orender_mgr,dumpconfig | Dump the layer and graphics configuration information at startup |
| -orender_mgr,double | Enable double buffering (fullscreen redraws) |
| -orender_mgr,layer=[index] | Set the directfb layer index that content will render to (default=0) |
| -orender_mgr,quality=[0|1|2] | Quality of image rotation. The default, 0 is fastest but lowest quality rendering. A setting of 2 is highest quality but slowest performing. |
Table 3.10. Render Manager Options: Linux, Windows CE, Windows Compact 7, Mac OSX, Neutrino 6.5, OpenGL ES 2.0, armle (Beagleboard)
| OPTION | DESCRIPTION |
|---|---|
| -orender_mgr,quality=[0|1|2] | Set the rendering quality including shade model and texture filter, and image rotation quality. A value of 0=nearest/flat, 1=linear/flat, 2=nearest/smooth (default=linear/flat). For image rotation, lower numbers mean faster algorithms, but better quality |
| -orender_mgr,fullscreen | Run in fullscreen mode |
| -orender_mgr,multisample=[value] | This sets value indicates the degree of multisampling which affects the visual smoothness of edges. For example, 4 would be 4x multisampling while 0 would be no multisampling. The default value is 4. |
| -orender_mgr,vbo | use vertex buffer objects |
| -orender_mgr,scale=[aspect] | scale the application to the physical display size. If aspect is passed the application will retain the proper aspect ratio when scaled. |
| -orender_mgr,backbuffer | Render the scene using a damage rectangle. On some OpenGL ES implementations this will give better performance but will use more memory as it has to allocate a separate display buffer. |
| -orender_mgr,npot | Disable power-of-two texture allocations. By default the OpenGL ES API is queried to check for NPOT texture support. This option can be used to override this behaviour and force support. NPOT textures will use less memory for image data. |
| -orender_mgr,fontsize=[size] | Specify the size of the font texture sheet. Fonts are generated into sheets and the default size is 512x512. The number of glyphs put into the sheet is a function of the point size and the texture size. This option can be used to tune the number of available glyphs and the memory usage. |
| -orender_mgr,window_w=[w] | Scale the application content and window to the specified width. This option is only valid on desktop systems which use a window manager (MACOS and Windows). This option must be used along with 'window_h' |
| -orender_mgr,window_h=[h] | Scale the application content and window to the specified height. This option is only valid on desktop systems which use a window manager (MACOS and Windows). This option must be used along with 'window_w' |
| -orender_mgr,linejoin=[0|1] | Set line join style for path drawing, drawing joins can have a performance impact on frame rate. 0=none, 1=round (default=1) |
| -orender_mgr,clipmode=[stencil|scissor] | Set the clipping mode to use, may have performance impacts. Each implementation defaults to the best performance. |
| -orender_mgr,error_event | An error event is generated for OpenGL render errors. Image and font errors will identify the image and font related to the error. |
| -orender_mgr,display=[index] | Connect to the given display index, this option is only available for the QNX Screen OpenGL ES 2.0 render manager or the Linux i.MX6 OpenGL ES 2.0 render manager where the value is the selected framebuffer index. |
| -orender_mgr,fb=[x] | This option pertains specifically to iMX6 hardware platforms. Starting at 0, x defines the framebuffer number to render to. |
| -orender_mgr,x=[xpos] | When using the QNX Screen engine this will position the application at the defined x-position |
| -orender_mgr,y=[ypos] | When using the QNX Screen engine this will position the application at the defined y-position. |
| -orender_mgr,rotated=[90|180|270] | Rotate the application by the defined angle. |
| -orender_mgr,zorder=[z] | When using the QNX Screen engine this will position the application window at the defined Z index. |
Table 3.11. Render Manager Options: QNX Neutrino 6.5, Linux, Fujitsu Jade, armle
| OPTION | DESCRIPTION |
|---|---|
| -orender_mgr,mainlayer=[number] | The main layer to use for rendering, defaults to layer 0 |
| -orender_mgr,display=[number] | The display to connect to, defaults to display 0 |
| -orender_mgr,conf_file=[path] | A path to a LCD configuration file which includes the display settings |
Table 3.12. Render Manager Options: WinCE 6.0, Windows Compact 7, win32, armle
| OPTION | DESCRIPTION |
|---|---|
| -orender_mgr,quality=[0|1|2] | quality of image rotation. 0 is fastest but lowest quality. 2 highest and slowest |
| -orender_mgr,fullscreen | Removes the window border and fills the display outside of the application area |
| -orender_mgr,dumpcaps | Print the device capabilities and acceleration flags |
| -orender_mgr,nohwcursor | disables the HW cursor |
Table 3.13. Resource Manager Options
| OPTION | DESCRIPTION |
|---|---|
| -oresource_mgr,image=4 | will set the image cache limit to 4K for example (the texture memory on GPU based systems is related to the image cache limit as well) |
| -oresource_mgr,font=4 | will set the font cache limit to 4K for example |
| -oresource_mgr,error=0 | send or skip resource manager error events, default is 1 (send) |
Table 3.14. Screen Manager Options
| OPTION | DESCRIPTION |
|---|---|
| -oscreen_mgr,swcursor | enables the rendering of a software cursor |
| -oscreen_mgr,redraw_complete | generate a completed event for every screen update |
| -oscreen_mgr,dl=1 | disable the use of a particular hardware layer |
| -oscreen_mgr,fps | display the frames per second of the display update, requires level 4 verbosity (-vvvv) |
| -oscreen_mgr,overlay | Allow the application to be run as an overlay and show the content below. This only functions on particular render managers and if the application has a transparent background. |
The Storyboard product ships with a standard set of plugins which add functionality to the system. Plugins are loaded based on the SB_PLUGINS environment variable. This variable can be a directory where all plugins are loaded from or a “;” separated list of plugins.
Some plugins have options that can be passed via the command line to the plugin. To pass on option to a plugin use the -o option to sbengine in this format -o[PLUGIN_NAME],[PLUGIN OPTION]
Table 3.15. 3D model rendering: libgre-plugin-model3d.so
| OPTION | DESCRIPTION |
|---|---|
| -omodel3d,novbo | Disable the use of vertex buffer objects, by default Vertex buffer objects are used for rendering. |
Table 3.16. Capture/Playback: libgre-plugin-capture-playback.so
| OPTION | DESCRIPTION |
|---|---|
| -ocapture_playback,mode=[capture|playback] | Specifies the behaviour of the plugin for either playback or capture. If capture is specified then input events (gre.press, gre.release, gre.motion, gre.keypress etc) will be logged and stored in an ouptut file. If playback is specified then the contents of an input file are read and the input events are injected back into the application. |
| -ocapture_playback,file=filename | If "capture" is specified as the mode it indicates the contents of the file specified will be overwritten with the new event stream. If "playback" is specified then the contents of the file specified will be used as an event stream source. |
| -ocapture_playback,verbosity | Indicates that the plugin should log events that it is either capturing or playing back to the standard output |
| -ocapture_playback,loop=count | Playback option that indicates how many times the playback should iterate through its content. The default is to playback
the content once, otherwise if a count is specified the plugin will replay the full content count times. |
| -ocapture_playback,quit_playback | Playback option that indicates if a gre.quit event should be automatically generated after playback is complete.
The default is to not generate a quit event. |
Table 3.17. Gesture: libgre-plugin-gesture.so
| OPTION | DESCRIPTION |
|---|---|
| -ogesture,file=filename | filename is a text file containing custom gesture definitions. |
| -ogesture,mode=[single|multi] | single allows for single touch gestures. multi allows for both single and multi-touch gestures. By default both single and multi touch gestures are disabled |
| -ogesture,threshold=[level] | Specifying a level allows the user to configure the sensitivity level which determines if we translate a motion into a gesture event. By default the threshold is set to 100. |
| See below for more options |
Table 3.18. Linux Input Support: libgre-plugin-dev-input.so
| OPTION | DESCRIPTION |
|---|---|
| -odev-input,mouse=/dev/input/event0 |
The name of the mouse device, for example
|
| -odev-input,kbd=/dev/input/event1 | The name of the keyboard device, for example
/dev/input/event1 |
One of either the mouse or kbd
arguments must be passed to enable this plugin. There are no
default bindings so the full path to the desired input
device must be specified. |
Table 3.19. Lua Scripting: libgre-plugin-lua.so
| OPTION | DESCRIPTION |
|---|---|
| -olua,hold=[0|1] |
This option controls how Lua posts data manager change notifications. By
default all changes are held until the end of script execution (1) but if
0 is specified, change notifications and events are triggered as soon as
changes are made using |
| -olua,gc=[0|1] |
This option is used to minimize the runtime memory footprint of the Lua script
engine by invoking the Lua garbage collector after every Lua action. By default
this option is set to 0 indicating that garbage collection will occur at the
natural points specified by Lua's |
Table 3.20. Linux Multi-touch Protocol: libgre-plugin-mtdev.so
| OPTION | DESCRIPTION |
|---|---|
|
-omtdev,device=[path to touch device] |
Plugin for Linux Multitouch Protocol to be used with kernels supporting multitouch events. This plugin is only available for the imx6 runtime currently. |
|
-omtdev,rotation=[0|90|180|270] |
Clockwise rotation of the touch input coordinates. When X1,Y1 is in the top-left corner, rotation is 0. |
|
-omtdev,bounds=[X1:Y1:X2:Y2] |
Where X1,Y1 is the top-left corner and X2,Y2 is the bottom-right corner of the touch screen device. On some screens, X1 may be less than X2 and Y1 may be less than Y2. |
|
-omtdev,max_x=[max touch value in the x direction] | DEPRECATED in Storyboard 4.2 |
|
-omtdev,max_y=[max touch value in the y direction] | DEPRECATED in Storyboard 4.2 |
|
-omtdev,threshold=[integer] | This is the number of pixels a touch point has to move in order to generate a motion event, the default value is 1 |
|
-omtdev,points=[integer] | This is the number of multitouch fingers that is supported. Events will only be generated for this number of fingers in contact with the screen, the default is 5 |
Table 3.21. Linux Touchscreen Support: libgre-plugin-tslib.so
| OPTION | DESCRIPTION | ||||
|---|---|---|---|---|---|
| -otslib,pressure=1 | Set the pressure value with corresponds to a press, the default is any value greater than 0 is a press. | ||||
| -otslib,motion=5 | The number of consecutive motion events to compress, can be useful on a device which delivers a high rate of motion events, default is to not compress. | ||||
| -otslib,calibrate | Put tslib into raw mode which is used for calibration. | ||||
|
If you do not have the following
|
Table 3.22. Logger: libgre-plugin-logger.so
| OPTION | DESCRIPTION | ||||
|---|---|---|---|---|---|
| -ologger,output=[filename] |
This option specifies a path in the file system to direct the Storyboard standard output to. The directory path to the file must already exist.
A valid command would be: | ||||
|
-ologger,buffer=[bytes] |
This option will buffer all logging output to an allocated in-memory buffer and only flush the output when the buffer content is full. The number of bytes allocated for the buffer are provided by the option to the argument. If the buffer size is 0 or invalid, then 4K will be allocated for the buffer. | ||||
|
-ologger,event=[event_name] |
This option will enable the generation of a custom Storyboard event any time that an ERROR message is detected by the Storyboard Engine logging system. When the error is detected, an event "event_name" will be sent to the application and it will contain a payload of "1s0 msg" where the "msg" is the diagnostic string that would have been logged. | ||||
|
-ologger,slogger=[opcode] (QNX ONLY) |
This option specifies that sbengine should use the QNX system logging infrastructure. if no opcode is given, sbengine will provide an appropriate opcode. The opcode is a combination of a major and minor code. Create the opcode using the _SLOG_SETCODE(major, minor) macro that's defined in sys/slog.h. This option is only available for systems running QNX. | ||||
| -ologger,io=[level] | This option enables the logging of IO events in variable levels of verbosity. If no option is specified then the level will default to 1 and the event name and its size in bytes will be displayed. If 2 is specified then the format is displayed. If 3 is specified then the data payload will be dumped to the standard output in both hexadecimal and character formats. | ||||
| -ologger,data | This option enables the logging of data change events as they occur. The data key that has been changed is displayed to standard output. | ||||
| -ologger,perf | This option enables the logging of performance
data to the standard output (or file if perf_file is used). If a value of 0
is specified to the perf option then performance logging is enabled, but the capture of data is not
immediately started and can be toggled using the gra.perf_state action. If the value
is set to 1 or is not specified, then performance data will be immediately captured. For example
sbengine -ologger,perf=1 will enable performance logging with the immediate capture of
performance metrics. | ||||
| -ologger,perf_file=[filename] | This option specifies a path in the file system to direct the performance data output to. The directory path to the file must already exist and the contents of the file will be overwritten on each invocation of sbengine. | ||||
| -ologger,filter=[keyword] | This option enabled filtering of events based on the keyword provided.
Multiple keywords can be specified up to a maximum of 5. Each keyword can also be negated by the
'^' symbol. Therefor we could ignore all motion events by passing in the following command:
sbengine -ologger,filter=^motion Filtering applies to the 'io' and 'data' options. | ||||
| If performance logging is enabled then the output is a set of comma separated values (CSV) with the following fields: PERF, application time, type, operation, name, duration | |||||
| application time | This is the time that the performance event was finished relative to the start time of the application in milliseconds. | ||||
| type | This is the type of performance operation that was recorded as a broad classifier | ||||
| operation | This is a sub-classification of the type used for additional tracing granularity | ||||
| name | This is an identifier that can be used, along with the type and operation fields, to identify the context of the performance operation being performed | ||||
| duration | This is the duration of the operation in milliseconds |
Table 3.23. QNX input support: libgre-plugin-gfi-input.so
| OPTION | DESCRIPTION |
|---|---|
| -ogfi-input,mouse=/dev/devi/mouse0 | The name of the mouse device, for example /dev/devi/mouse0 |
| -ogfi-input,rotated=[90|270] | If specified, this indicates that the input co-ordinates should be rotated by 90 or 270 degrees |
By default the input system used the gfi interface based
on the devi drivers. The devi driver must be run with the
-P option. If you pass the
mouse option then the mouse/touchscreen is
used in raw mode. |
Table 3.24. Storyboard IO: libgre-plugin-greio.so
| OPTION | DESCRIPTION |
|---|---|
| -ogreio,channel=name | The value specifies the name that the applicaitons Storyboard IO channel will use. This
name can then be used by gre_io_open or iogen clients to send
events to the application. |
| -ogreio,queue | This flag indicates if the events on the Storyboard IO channel should be asynchronously queued into the application's message queue or if a new event should be added only after the last event has been processed. The default is to only have one event being processed by the application at a time. |
Capture mouse or touchscreen events and generate gesture events
gesture
libgre-plugin-gesture.so
file=filename
mode=[single|multi]
threshold=[level]
File is the filename of a text file containing custom gesture definitions.
Mode specifies if we are anticipating single or multi-touch events.
Threshold is the sensitivity level which determines if we translate a motion into a gesture event.
What the gesture plugin does is to translates input
gre.move events from a mouse or a touchscreen into a
gesture event. When a button is depressed, or your finger is dragged
across the touchscreen, the gesture plugin tracks it. When the button is
release or you take your finger off of the touchscreen, the plugin emits
the gesture.
The gesture plugin also handles input from multiple touch points when running on a multi-touch enabled device.
The conventional gestures below are only generated from the mouse or a single touch point. Using Multiple Touch points will generate other events described later in this document.
Gestures are made up of a series of numbers. The numbers represent the direction that the cursor was traveling as a grid arranged from 1 to 8:
Up
Up and to the Right
Right
Down and to the Right
Down
Down and to the Left
Left
Up and to the Left
By default the gesture plugin registers the Up, Right, Down, and Left gestures as 1, 3, 5, 7. The numbers 2, 4, 6, 8 aren't enabled by default, but you can define them in a custom gesture definition file. The gesture definition file is a text file that defines an event, followed by the gesture number.
For example, to define a z gesture, you could put the
following in the a gesture-definition.txt file:
gre.gesture.ze,363
This definition stats when the gesture plugin detects a right motion,
followed by a down and to the left motion, followed by another right
motion, it will emit a gre.gesture.ze event.
You can point the gesture plugin at the custom gesture definition file by running storyboard with the option "gesture,file=filename" , where filename would be the name of the file like, gesture-definition.txt, from the example above. Another option is to export the environment variable GESTURE_DEF_FILE which will set to the path to the custom definition file.
It should be noted that gestures are capped at a maximum of 30 motions and anything above this limit will cause a warning and be ignored.
Unlike the single touch gestures, which state which gesture you have just entered, the multi-touch gestures are events that fire whenever you have more than one finger on the touchscreen. The plugin tracks up to five contact points, if 6 or more are present they will simply be ignored by the plugin. The events the plugin listens to are gre.press, gre.release, and gre.motion to track the touchscreen info while only one finger is present and gre.mtpress, gre.mtrelease, and gre.mtmotion, to track the touchscreen info while multiple touches are present. Note when using a multi-touch enabled device single the press, release and motion events will be sent only while there is only one touch point present. As soon as there are multiple touch points present, all events will be mt events.
After listening to the events, if more than one touch point is present and one or more touch points move, the plugin will do an update where it compares the old touch locations to the updated touch locations and generates the related multi-touch gesture events. These events are all of the form gre.mtXaction, where X is the number of touch points present (between 2 and 5), and action is the name of the event, which will be one of, move, pinch or rotate.
All multi-touch gesture events have the same format of a gre pointer event, with a few extra data fields.
gre.mtXmove
This event has an x_move and y_move data field, which will be the difference in x and y of the midpoint of all present touch touches between the current and last event sent from the touchscreen.
gre.mtXpinch
This event has a value data field, which will be the scale factor of the average spacing from all current touch points compared to the spacing of all the old touch points. The scale factor is calculated by newspacing/oldspacing, so a value of 1.1 indicates a growth of 10% and a value of 0.9 indicates a shrink of 10%
gre.mtXrotate
This event has a value data field, which will be the difference in rotation between the average angle of all current touch points compared to the average angle of all the previous touch points. The value will be in degrees.