Storyboard Engine Environment
Prev Chapter 3. Storyboard Engine Next

Storyboard Engine Environment

The following pieces are required when putting the Engine on an embedded target:

Storyboard Engine

In order to deploy the engine to an embedded target we must first decide which plugins are needed.  The Engine is a self contained executable which loads plugins for added functionality.  The Engine can be run as follows:

sbengine [-i] [-v] [-o]  [deployment bundle]

Options:

-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 can have specific options.  The option string is defined as follows:

-o plugin_name,option[,option]…]

Each plugin or manager defines its name and possible options.

Engine Manager Options

Action Manager
Name:

action_mgr

Options:

None

Data Manager
Name:

data_mgr

Options:

None

Model Manager
Name:

model_mgr

Options:
plugin_path

The filesystem path to the plugins, overrides the SB_PLUGINS environment variable.

For example sbengine -omodel_mgr,plugin_path=/temp will set the plugin search path to the directory /temp

fps

This is the maximum framerate to run animations at. The default value is 60 fps

For example sbengine -omodel_mgr,fps=25 will cap all animation framerates at 25 fps.

Render Manager
Name:

render_mgr

Options:

The options for the Render Manager vary depending on the particular configuration used. The options for each configuration are described in the System Specific Requirements section of this document.

Resource Manager
Name:

resource_mgr

Options:
image=[size]

The size of the image memory pool in kilobytes

font=[size]

The size of the font memory pool in kilobytes

For example sbengine -oresource_mgr,image=4096 will set the image cache limit to 4K. By default there is no limit on a particular resource.

Screen Manager
Name:

screen_mgr

Options:
swcursor

Enables the rendering of a software cursor

redraw_complete

Generate a completed event for every screen update

dl=[layer_index]

Disable the use of a particular hardware layer

fps

Display the frames per second of the display update, requires level 4 verbosity

IO Manager
Name:

io_mgr

Options:
queue_size=[size]

The size of the event queue in bytes

For example sbengine -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.

Plugins

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 the plugin. To pass on option to a plugin use the -o option to sbengine in this format -o[PLUGIN_NAME],[PLUGIN OPTION]

Animation

Provides animation support.

Name:

animate

Plugin:

libgre-plugin-animation.so

Options:

None

Capture/Playback

Provide the facility to capture an input event stream composed of stanard gre.press/release/move events to a file and then provide the ability to re-play that event stream back into the application providing a playback functionality. The capture file is portable among systems with the same endian byte format.

Name:

capture-playback

Plugin:

libgre-plugin-capture-playback.so

Options:

filename

This specifies the file to be used for either capture or playback depending on the mode.

mode=[capture|playback]

This specifies the mode of operation for the plugin. If "capture" is specified it indicates the contents of the file option will be overwritten with the new event stream. If "playback" is specified then the contents of the file option will be used as an event stream source.

verbosity

A number indicating if the event stream capture or playback should be echoed to the standard log.

Audio

Provides platform audio support.

Name:

audio

Plugin:

libgre-plugin-audio.so

Options:

None

This provides a contributed action gra.audio that allows the user to play a single asynchronous audio WAV formatted file.

Event Redirection

Redirect events to another Storyboard IO channel. All events that are received are copied and tranferred directly to another channel without interpretation.

Name:

redirect

Plugin:

libgre-plugin-redirect.so

Options:

None

Gesture

Capture mouse or touchscreen events and generate gesture events

Name:

gesture

Plugin:

libgre-plugin-gesture.so

Options:

file=filename

This is the filename of a text file containing custom gesture definitions.

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 travelling as a grid arranged from 1 to 8:

1

Up

2

Up and to the Right

3

Right

4

Down and to the Right

5

Down

6

Down and to the Left

7

Left

8

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.

Multi-Touch Gestures

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

Storyboard IO

Implement the Storyboard IO API and external application communication

Name:

greio

Plugin:

libgre-plugin-greio.so

Options:
channel=[name]

The name given to the application's Storyboard IO channel.

For example sbengine -ogreio,channel=my_greio_channel would result in a Storybord IO channel named my_greio_channel to be used for this application. This channel name can then be used by clients that want to connect and send events to the application.

Logger

Log system messages for debugging.  

Name:

logger

Plugin:

libgre-plugin-logger.so

Options:
io

This option enables the logging of IO events to the output.

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.

perf_file=[filename]

This option specifies a path in the filesystem 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.

data

This option enables the logging of data change events to the output.

If IO logging is enabled then events and their data payload will be displayed as they are received.  The data payload is dumped to the standard output in both hexadecimal and character formats.

If data logging is enabled, then data changes in the data manager will be displayed as they occur.  The data key that has been changed is displayed to standard output.

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

duration

This is the duration of the operation in milliseconds

The logger is disabled by default and can be enabled by passing -ologger[,io][,data][,perf] to the sbengine application.

Lua

The Lua script plugin

Name:

lua

Plugin:

libgre-plugin-lua.so

Options:

None

Screen Dump

Dump the contents of the current screen display buffer. The contents are dumped using the gra.screendump action and can be written to either a BMP or a TGA formatted file.

Name:

screen-dump

Plugin:

libgre-plugin-screen-dump.so

Options:

None

Screen Path Transition

Transition from one screen to another in a path based method: Right, left, up or down

Name:

screen-path

Plugin:

libgre-plugin-screen-path.so

Options:

None

Screen Scale Transition

Transition from one screen to another by scaling the new screen to fill the display

Name:

screen-scale

Plugin:

libgre-plugin-screen-scale.so

Options:

None

Screen 3D Transition

Transition from one screen to another using a 3D transformation

Name:

screen-3d

Plugin:

libgre-plugin-screen-3d.so

Options:

None

Soft Input/Virtual Keyboard

Provide a virtual keyboard interface for WinCE clients using the Soft Input Protocol (SIP).

Name:

softinput

Plugin:

libgre-plugin-softinput.so

Options:

None

System

Execute a system command.

Name:

system

Plugin:

libgre-plugin-system.so

Options:

None

Timer

Allow external timer events to be used by the application.  Adds support for the gra.time. action.

Name:

timer

Plugin:

libgre-plugin-timer.so

Options:

None

Linux touchscreen support

Add support for touchscreens using the Linux tslib framework. This plugin available on Linux platforms only.

Name:

tslib

Plugin:

libgre-plugin-tslib.so

Options:
pressure=[value]

Set the pressure value with corresponds to a press, the default is any value greater than 0 is a press.

motion=[value]

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.

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

Linux input support

Add support for Linux input devices such as mouse and keyboards based on the Linux input system.

Name:

dev-input

Plugin:

libgre-plugin-dev-input.so

Options:
mouse=[mouse_device]

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

kbd=[keyboard_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.

QNX input support

Add support for QNX input devices such as mouse and keyboards based on the QNX input system.

Name:

gfi-input

Plugin:

libgre-plugin-gfi-input.so

Options:
mouse=[mouse_device]

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

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.

Polygon

Provides support for the polygon render extension.

Name:

poly

Plugin:

libgre-plugin-polygon.so

Options:

None

3D Model rendering

Provides support for rendering a 3D model from an OBJ file.

Name:

model3d

Plugin:

libgre-plugin-model3d.so

Options:
novbo

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

External

Enables external applications to render content into the external render extension.

Name:

external

Plugin:

libgre-plugin-external.so

Options:

None

Prev Up Next
Chapter 3. Storyboard Engine Home Custom Shader Support