Storyboard Engine Plugin Options

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:

sbengine [[-oplugin_name,plugin_option[[,plugin_option2,...]]] your_app.gapp

Table 8. Plugin Options

PLUGIN OPTIONDESCRIPTION

Plugin Name: io_mgr (-oio_mgr,...)

queue_size=[size]

4096 will limit the event queue size to a maximum of 4K for example. If the queue exceeds this size, events will be dropped and diagnostic messages will be logged regarding the dropped events. The default behavior is to have an unlimited event queue size.

Plugin Name: model_mgr (-omodel_mgr,...)

fps=[integer]

Limits the frame rate for all animations to a maximum fps specified (25 for example).

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 reporting of the memory statistics at app initialization and at application termination. Future values are reserved.

If the metrics plugin is present and this option is present and loaded then this option will also generate a cost estimate of the curent application's in-memory structure cost which can be used within Storyboard Designer to estimate the RAM footprint of the application at design time.

plugin_path=[path]

Sets the plugin path to the specified directory (/temp for example). This setting overrides the SB_PLUGINS environment variable setting.

scroll_drag_px

The number of pixels that need to be moved before a scrollable container considers this a scroll operation (default 10).

scroll_bounce_ms

The number of milliseconds that the bounce operation on a scrollable container should animate once the bounce back is operation is started (default 200ms).

scroll_bounce_rate

The animation rate that should be used on a scrollable container for bounce back animations (default easein).

Plugin Name: render_mgr (-orender_mgr,...)

x=[xpos]

This will position the application at the defined x-position.

y=[ypos]

This will position the application at the defined y-position.

sysdpi

This will enable the window upscaling performed by Windows according to the system DPI setting.

PLATFORM: Windows, OpenGL, swrender, x86

dblbuffer

Enable double buffering (fullscreen redraws)

PLATFORM: Linux, x86, armle, swrender

display=[number]

The number of the framebuffer device to use (/dev/fb[number], default=/dev/fb0)

PLATFORM: Linux, x86, armle, swrender

fb=[x]

This option pertains specifically to iMX6 hardware platforms. Starting at 0, x defines the framebuffer number to render to.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, x86, armle, OpenGL, swrender

fullscreen

Run in fullscreen mode.

rotate=[90|180|270]

Rotate the application by the defined angle.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, x86, armle, OpenGL, swrender

rle_blit=[x]

Decode RLE compressed images directly to framebuffer surface memory in order to remove need for temporary decode buffer. Only available for 32 bits per pixel source images with No Scaling and No Rotation. This option pertains to swrender on RTExec platforms. Set x = 1 (default) to enable RLE blit; x = 0 is not enabled.

PLATFORM: armle, RTExec, Storyboard Lite, swrender

quality=[0|1|2]

Visual fidelity of image rotation rendering. A value of 0 emphasizes speed at the cost of visually fidelity. A value of 2 provides the highest visual fidelity, with a potential impact on performance. The default value is set to 1.

dumpconfig

Dump the layer and graphics configuration information at startup.

PLATFORM: Linux, x86, armle, swrender

double

Enable double buffering (fullscreen redraws)

PLATFORM: Linux, x86, armle, swrender

layer=[index]

Set the directfb layer index that content will render to (default=0)

PLATFORM: Linux, x86, armle, swrender

multisample=[value]

Indicates the degree of multisampling which affects the visual smoothness of edges. For example, a value of 4 would be 4x multisampling while 0 would be no multisampling. By default, this value is set dynamically based on the model content that is being interpreted in order to provide the best balance between high performance and high quality rendering. If your model contains 3D models, polygons or circles then multi-sampling is turned on to a level of 4, otherwise it is off. The command line option setting will override the default probing and ensure a fixed value.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

vbo

Enables the use of vertex buffer objects.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

scale=[aspect]

Scale the application to the physical display size. If aspect is passed the application will retain the proper aspect ratio when scaled.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

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.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

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 behavior and force support. NPOT textures will use less memory for image data.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

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.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

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. This option must be used along with 'window_h'

PLATFORM: Windows, Windows CE 2013, macOS, Linux, QNX, x86, armle, OpenGL

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. This option must be used along with 'window_w'

PLATFORM: Windows, Windows CE 2013, macOS, Linux, QNX, x86, armle, OpenGL

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)

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

clipmode=[stencil|scissor]

Set the clipping mode to use, may have performance impacts. Each implementation defaults to the best performance.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

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.

display=[index]

Connect to the given display index, this option is only available for the QNX Screen OpenGL render manager or the Linux i.MX6 OpenGL render manager where the value is the selected framebuffer index.

zorder=[z]

When using the QNX Screen engine this will position the application window at the defined Z index.

clearcolor=[color]

Specify the clear color to be used for the Window Surface. The color format is ARGB and specified in hexadecimal. The default clear color is 0x00000000. This option can be used for debugging purposes.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

image_block_size=[number]

This specifies the memory size of the shared blocks that are used within the image cache. These settings override the generic block_size setting that is used generically for the atlas and are bound by the -oresource_mgr,image setting.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

font_block_size=[number]

This specifies the memory size of the shared blocks that are used within the font glpyh cache. These settings override the generic block_size setting that is used generically for the atlas and are bound by the -oresource_mgr,font setting.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

block_size=[-1|0|>0]

Specify how block size should be determined for growing the image atlas. For -1, a degenerate block size will be used, forcing block size to that of a single image. For 0, the block size is rounded up to the nearest power of two for an image's dimensions. For any value greater than zero, block allocations will be rounded up to the size specified. (default=1024)

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

surface_cache=[-1(default)|0|>0]

Specify the surface cache control. For -1, the surface cache will grow unbounded (default). For 0, the surface cache will be disabled. For any value greater than zero, it will be used as the upper limit on the number of surfaces in the surface cache.

PLATFORM: Windows CE 2013, macOS, Linux, QNX, armle, OpenGL

mainlayer=[number]

The main layer to use for rendering, defaults to layer 0

PLATFORM: Linux, QNX, armle

dumpcaps

Print the device capabilities and acceleration flags.

PLATFORM: Windows CE 2013, armle

nohwcursor

Disables the HW cursor.

PLATFORM: Windows CE 2013, armle

Plugin Name: resource_mgr (-oresource_mgr,...)

error=[0|1]

When a resource error is encountered a diagnostic message is generated. This option controls if an event for the error is sent (1, default) or not sent (0). This option is currently only enabled for OpenGL render managers.

font=[number]

Similar to the image resource option, this value controls the number of bytes of memory allocated for the font glyph cache. After the cache is full, the behaviour of the allocations is controlled via the font_oom option. A value of 0 (default setting) indicates that the font glyph cache should be limited by the size of available system memory. Otherwise a positive value indicates the size of the cache in bytes and can be symbolically specified using K, M qualifiers such as 4K to indicate an font glpyh cache of 4096 bytes or 1M to indicate 1048576 bytes of memory.

image=[number]

This will set the maximium number of bytes in the image cache. After the cache is full, the behaviour for allocations is controlled via the image_oom option. A value of 0 (default setting) indicates that the image cache should be limited by the size of available system memory. A value of -1 indicates no image cache and only one image at a time will be loaded and that image not cached. Otherwise a positive value indicates the size of the cache in bytes and can be symbolically specified using K, M qualifiers such as 4K to indicate an image cache of 4096 bytes or 1M to indicate 1048576 bytes of memory.

image_oom=[fail|lru]

This sets the behaviour when the maximum value of the image cache is reached. If this is set to the value fail then when an allocation can't be fulfilled the request will fail. If this is set to the value lru then when an allocation can't be fulfilled the request will attempt to remove other entries from the cache until it can either fit the request or it fails. The default behaviour is lru.

Plugin Name: screen_mgr (-oscreen_mgr,...)

dl=[1]

Disable the use of a particular hardware layer.

fps

Display the frames per second of the display updates in the Storyboard Engine console output and also set the grd_fps variable with the calculated value.

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.

redraw_complete

Generate a completed event for every screen update.

swcursor

Enables the rendering of a software cursor.

Plugin Name: capture_playback (-ocapture_playback,...) / Shared Library: libgre-plugin-capture-playback

capture_events=[eventname]

Capture option to define a custom list of events to capture. Multiple events can be specified by using the ":" character as a delimiter.

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.

loop=[count]

A 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.

mode=[capture|playback]

Specifies the behavior 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.

no_defaults

Capture option to specify that there are no default events set to be captured. By default we capture the following events:

1 gre.press

2 gre.release

3 gre.keyup

4 gre.keydown

5 gre.keyup

6 gre.keyrepeat

7 gre.motion

8 gre.mtevent

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.

verbosity

Indicates that the plugin should log events that it is either capturing or playing back to the standard output.

Plugin Name: ccallback (-occallback,...)

path

Point the ccallback plugin to a dynamic library (dll/so). Only applies to dynamically linked engines. On statically linked engines, this is not required.

Plugin Name: dev-input (-odev-input,...) / Shared Library: libgre-plugin-dev-input

kbd=[device]

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.

mouse=[device]

The name of the mouse device, for example /dev/input/event0

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.

Plugin Name: gesture (-ogesture,...) / Shared Library: libgre-plugin-gesture

file=[filename]

filename is a text file containing custom gesture definitions. When the gesture plugin is in 'auto' mode, the gesture plugin will determine if the application uses any of the custom gesture events and enable single touch events.

mode=[disabled|single|multi]

By default, sbengine will search your application for use of any gesture events and gestures will be enbled as required. This behaviour can be overridden with any of the following mode options:

disabled will not generate any gesture events.

single allows for generation of single touch gesture events.

multi allows for generation of both single and multi-touch gesture events.

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.

Plugin Name: gfi-input (-ogfi-input,...) / Shared Library: libgre-plugin-gfi-input

mouse=[device]

The name of the mouse device, for example /dev/devi/mouse0

PLATFORM: QNX

rotate=[90|270]

If specified, this indicates that the input co-ordinates should be rotated by 90 or 270 degrees.

PLATFORM: QNX

 

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.

Plugin Name: greio (-ogreio,...) / Shared Library: libgre-plugin-greio

channel=[name]

The value specifies the name that the applications Storyboard IO channel will use. This name can then be used by gre_io_open or iogen clients to send events to the application.

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.

Plugin Name: logger (-ologger,...) / Shared Library: libgre-plugin-logger

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.

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.

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.

filter=[keyword]

This option enables filtering of events based on the keyword provided. Multiple keywords can be specified. Filtered events are delimited by a ':'. sbengine -ologger,io,filter=gre.press:gre.release Each keyword can also be negated by the '^' symbol. Therefore we could ignore all motion events by passing in the following command: -ologger,io,filter=^gre.motion Filtering applies to the 'io' and 'data' options. If neither 'io' or 'data' options are specified, then this option does nothing.

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.

metrics_event_prefix=[prefix]

This option specifies the prefix to use in the metrics event names. This defaults to metrics.

metrics_output=[0 | 1 | 2 | 3]

This option tells the metrics portion of the logger plugin where to out the metrics data. 0 just updates the data, and this is the defualt, 1 is used to output the data to the log, 2 outputs the data to the performance log, if the perf option is also specified, and 3 will output the data to both the log and the performance log if the perf option is specified.

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.

+ At the beginning of the file name will append to the log file, otherwise the file will be overridden on each invocation of sbengine.

%D in the filename will be replaced by a date stamp with YYYY-MM-DD format.

%T in the filename will be replaced by a 24h time stamp with HHMMSS format.

Both %D and %T may be used on the same filename.

A valid command would be: -ologger,output=/logs/log-%D-%T.txt, provided the /logs/ directory existed prior to runtime.

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 -ologger,perf=1 will enable performance logging with the immediate capture of performance metrics.

perf_buffer=[bytes]

This option will buffer all performance 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.

perf_event_prefix=[prefix]

This option specifies the prefix to use in the perf event name. This defaults to perf.

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.

perf_filter=[keyword]

This option enables filtering of perf types based on the keyword provided. The sb_Event type cannot be filtered out. This is because Storyboard engine is event based, and everything that happens is tied back to the event that kicked things off. Multiple keywords can be specified. Filtered types are delimited by a ':'. -ologger,perf,perf_filter=sb_RenderExtension Each keyword can also be negated by the '^' symbol. Therefor we could ignore all render extension types by passing in the following command: -ologger,perf,perf_filter=^sb_RenderExtension Filtering applies to the perf option.

poll_metrics_interval=[ms]

This option sets up a timer to fire at the interval specified by ms. When the timer fires the system metrics for memory, CPU and FPS will be updated. See metrics output to control where the metrics output will go.

retailmsg

The logger will output using RETAILMSG instead of sending output to stdio.

PLATFORM: Windows CE 2013

 

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.

slogger=[opcode]

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.

Plugin Name: lua (-olua,...) / Shared Library: libgre-plugin-lua

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 collectgarbage option. If the value is set to 1, then garbage collection is run after every Storyboard Lua action invocation, reducing the active runtime memory footprint with a slight cost to execution performance.

hold=[0|1|2]

This option controls how Lua posts data manager change notifications. By default all changes are held until the end of script execution (1), except whenever a local event is sent through the gre.set_event call. In this case the data manager will be released to process the notifications, the send_event call will be issued, and then the data manager will again be held from making data change notifications. If 0 is specified, change notifications and events are triggered as soon as changes are made using gre.set_data calls. If 2 is specified then the data manager is held from emitting change notifications until the end of script execution even if a gre.send_event call is made.

Plugin Name: model3d (-omodel3d,...) / Shared Library: libgre-plugin-model3d

novbo

Disable the use of vertex buffer objects, by default Vertex buffer objects are used for rendering.

Plugin Name: mtdev (-omtdev,...) / Shared Library: libgre-plugin-mtdev

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.

calibrate

Puts mtdev into raw mode to be used in conjunction with the mtcalib application (See Crank Public SVN) to acquire the bounds parameters for screen calibration. Use the -omtdev,bounds option to pass the parameters to sbengine.

device=[path to touch device]

Plugin for Linux Multi-Touch Protocol to be used with kernels supporting multi-touch events. This plugin is only available for the imx6 runtime currently.

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.

rotate=[0|90|180|270]

Clockwise rotation of the touch input coordinates. This option is not often required. By default, mtdev plugin input will be rotated depending on the render manager configuration. The input transformation will be calculated by combining the specified rotation value and the render manager rotation.

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.

Plugin Name: tslib (-otslib,...) / Shared Library: libgre-plugin-tslib

calibrate

Put tslib into raw mode which is used for calibration. If you do not have the following tslib variables setup the plugin will not load or function properly.

TSLIB_CONSOLEDEVICE

TSLIB_TSDEVICE

TSLIB_CALIBFILE

TSLIB_CONFFILE

motion=[integer]

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.

pressure=[integer]

Set the pressure value which corresponds to a press. The default is any value greater than 0 is a press.