The following actions are only available when optional Storyboard plugins has been loaded.
Cause a Lua script function to execute.
- Plugin
-
libgre-plugin-lua.so
- Options:
-
- script
-
The name of the Lua function to invoke
Additional arguments can be passed to the function by providing additional key/value pairs to the action. The key/value pairs are provided to the Lua function as values in the argument table.
For example to call the Lua function
myfunction
with an extra argument,firstargument
, that corresponds to the value of the application variablemyvar
you would simply add a new entry to the parameter list.The corresponding call to the Lua function would fill the entry into the argument table such that:
function myfunction(mapargs) print("The value is: " .. tostring(mapargs.firstargument)) end
would print out the value of
${app:myvar}
.
Cause a JavaScript function to execute.
- Plugin
-
libgre-plugin-js
- Options
-
- script
-
The name of the Lua function to invoke
Additional arguments can be passed to the function by providing additional key/value pairs to the action. The key/value pairs are provided to the JavaScript function as values in the argument object.
For example to call the JS function myfunction with an extra argument, firstargument, that corresponds to the value of the application variable myvar you would simply add a new entry to the parameter list.
The corresponding call to the JS function would fill the entry into the object such that:
function myfunction(context) { print("The value is: " + context.firstargument.tostring()); }
would print out the value of ${app:myvar}.
Cause a C function to execute. This action is only availbale on Storyboard Lite platforms. The functionality can be simulated in Designer though through Lua. The C Callback plugin will search for a Lua function that has the same name as the C function.
- Plugin
-
libgre-plugin-ccallback.a
- Options:
-
- function
-
The name of the C function to invoke
Start an animation. Animations are started based on their name. Each animation can have an optional identifier (id) which is used to ensure that animations run in an exclusive manner. If an existing animation is running that uses the same identifier, then that animation is stopped before this animation is started. The data argument is as follows:
- Plugin
-
libgre-plugin-animation.so
- Options:
-
- name
-
The animation name to start
- id
-
An optional instance id to be associated with the animation. Animation identifiers can be used with different animations to ensure that only one animation of the set is running at a time.
When the animation stops it will emit a notification event in the form of gre.animate.complete.[name]
. This event will be delivered within the context of the gra.animate action and will be delivered to the object which invoked the action.
Stop an animation. If you stop an animation only by name then all running animations with that name will stop and emit a complete event. If you stop an animation by id then only that specific animation will stop and emit a complete event. The data argument is as follows:
- Plugin
-
libgre-plugin-animation.so
- Options:
-
- name
-
The animation name to stop
- id
-
An optional instance id associated with the name
When the animation stops it will emit a notification event in the form of gre.animate.complete.[name]
Start or stop the asynchronous playback of a WAV audio file. The data argument is as follows:
- Plugin:
-
libgre-plugin-audio.so
- Options:
-
- filename
-
A filename to play, or empty to stop the current playback.
Transform data according to the specified type of transform. Currently, only one type of transform is implemented with more to come in the future.
- Plugin
-
libgre-plugin-math-expression.so
- The following types of transformations are available:
-
- map
-
map incoming data with the specified range to outgoing variable with a specified range with the following arguments:
- rate
-
The rate at which to apply the mapping (linear/easein/easeout/easeinout/bounce/etc...)
- in
-
The incoming data to use for the transform calculation
- in_min
-
The minimum value for the incoming data
- in_max
-
The maximum value for the incoming data
- out
-
The outgoing data to set
- out_min
-
The minimum value for the outgoing data
- out_max
-
The maximum value for the outgoing data
Send a new event over a Storyboard IO channel. This action is best suited for name only event delivery. It is possible to use this action for simple single data item payloads (ie a single string or a single numeric value) but it is not recommended. The Lua API provides a more comprehensive Storyboard IO event delivery mechanism via the gre.send_event
or gre.send_event_data
function calls.
The action parameters below map directly to the Storyboard IO C API and a more comprehensive explanation of their use can be found there and in the Storyboard architecture and Working with Eventssections of this document.
- Plugin:
-
libgre-plugin-greio.so
- Options:
-
- name
-
Storyboard IO channel name to send the event to (required)
- event
-
The name of the event to generate (required)
- target
-
The fully qualified name of the target for the event as a string. (optional)
- format
-
The format of the event data (optional). Only a single data format element can be provided in this action (ie 1s0 or 4s1)
- data
-
The data payload for the event (optional). This data must match the type associated with the format string to be properly interpreted.
Control the capture of performance data
- Plugin:
-
libgre-plugin-logger.so
- Options:
-
- state
-
Turn off (0) or on (1) performance data capture
In order for this action to be used, the libgre-plugin-logger.so
must have been started with performance logging enabled, but not necessarily to have it start capturing the performance data. For example sbengine -ologger,perf=0
will enable performance logging but not start capturing events at startup while sbengine -ologging,perf=1
will enable performance logging and immediately start capturing events.
Redirect all events to another Storyboard IO channel.
- Plugin:
-
libgre-plugin-redirect.so
- Options:
-
- channel
-
Storyboard IO channel name to send the events to
Configure a screen drag plugin to track mouse movements and perform screen transitions.
- Plugin:
-
libgre-plugin-screen-drag.so
- Options:
-
- type
-
The type of screen transition animation. The corresponding plugin must be present. Default is screen replace which is the default action gra.screen.
replace path fade 3dcube 3dtip - rate
-
Animation rate string that defines how the screens will move over time:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
all delta - moving
-
The screen(s) to animate with the desired transition (not available on all types).
both new old - left
-
The screen to transition to on the left (when dragging towards the right)
- right
-
The screen to transition to on the right (when dragging towards the left)
- up
-
The screen to transition to on the top (when dragging towards the bottom)
- down
-
The screen to transition to on the bottom (when dragging towards the top)
- x_threshold
-
The horizontal amount which needs to be dragged when released to transition to the next screen, less than this amount will result in animating back to our original screen. Between 0.0 and 1.0, default is 0.3
- y_threshold
-
The vertical amount which needs to be dragged when released to transition to the next screen, less than this amount will result in animating back to our original screen. Between 0.0 and 1.0, default is 0.3
This will enable tracking mouse events for screen drag transitions with the previous configuration specified with the gra.screen.drag.config action.
- Plugin:
-
libgre-plugin-screen-drag.so
This will disable tracking mouse events.
- Plugin:
-
libgre-plugin-screen-drag.so
Causes a screen transition to occur by sliding the old screen out and/or the new one in from a given direction.
- Plugin:
-
libgre-plugin-screen-path.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the screen(s) will move over time:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- direction
-
The direction to transition from
left right top bottom - layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
all delta - moving
-
The screen(s) to animate with the desired path transition:
both new only old only
Causes a screen transition to occur by scaling the old screen into the new one.
- Plugin:
-
libgre-plugin-screen-scale.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the alpha values will change:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
all delta
Causes a screen transition to occur by using 3D to switch the old screen into the new one.
- Plugin:
-
libgre-plugin-screen-3d.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the alpha values will change:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
delta
Move all layers between source and destination screens
delta
Collapse common topmost and bottom most visible layers and only move the layers in between that are different between screens.
Causes a screen transition to occur by using 3D to rotate the old screen in the x-axis into the new one.
- Plugin:
-
libgre-plugin-screen-3d.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the alpha values will change:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- direction
-
The direction to transition from:
left right top bottom - layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
delta
Move all layers between source and destination screens
delta
Collapse common topmost and bottom most visible layers and only move the layers in between that are different between screens.
Causes a screen transition to occur by using 3D to switch the old screen into the new one.
- Plugin:
-
libgre-plugin-screen-3d.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the alpha values will change:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
delta
Move all layers between source and destination screens
delta
Collapse common topmost and bottom most visible layers and only move the layers in between that are different between screens.
Causes a screen transition to occur by using 3D to switch the old screen into the new one using a door opening animation.
- Plugin:
-
libgre-plugin-screen-3d.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the alpha values will change:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- direction
-
The direction to transition from:
left right top bottom - layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
delta
Move all layers between source and destination screens
delta
Collapse common topmost and bottom most visible layers and only move the layers in between that are different between screens.
Causes a screen transition to occur by using 3D to switch the old screen into the new one by tipping the display forward.
- Plugin:
-
libgre-plugin-screen-3d.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the alpha values will change:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- direction
-
The direction to transition from:
left right top bottom - layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination:
delta
Move all layers between source and destination screens
delta
Collapse common topmost and bottom most visible layers and only move the layers in between that are different between screens.
Causes a screen transition to occur by using 3D to switch the old screen into the new one using a cube animation.
- Plugin:
-
libgre-plugin-screen-3d.so
- Options:
-
- screen
-
The screen to transition to
- rate
-
Animation rate string that defines how the alpha values will change:
linear easein easeout easeinout bounce - fps
-
Number of frames per second
- duration
-
Length of the transition in milliseconds
- direction
-
The direction to transition from:
left right top bottom - layers
-
The layers to transition, all of the layers or just the layers that are different between source and destination.
delta
Move all layers between source and destination screens
delta
Collapse common topmost and bottom most visible layers and only move the layers in between that are different between screens.
Causes a screen transition where the new screen is rotated.
- Plugin:
-
libgre-plugin-screen-rotate.so
- Options:
-
- screen
-
The screen to transition to
- rotation
-
The rotation value to apply to the new screen.
Dump the contents of the screen to an image file.
- Plugin:
-
libgre-plugin-screencapture.so
- Options:
-
- filename
-
The filename of the image file to create. The directory path to the filename must exist and the filename will be overwritten if it is. The filename must end with either a .bmp extension to generate BMP formatted images or .tga to generate TGA formatted images
Dump a subsection of the screen, defined by the clip rectangle of the specified model object, to an image file.
- Plugin:
-
libgre-plugin-screencapture.so
- Options:
-
- fqn
-
The fully qualified name of the object, should be NULL for application-level variables
- filename
-
The filename of the image file to create. The directory path to the filename must exist and the filename will be overwritten if it is. The filename must end with either a .bmp extension to generate BMP formatted images or .tga to generate TGA formatted images.
Dump a rectangular subsection of the screen to an image file.
- Plugin:
-
libgre-plugin-screencapture.so
- Options:
-
- x
-
The x coordinate of the top left corner of the rectangle (4s1)
- y
-
The y coordinate of the top left corner of the rectangle (4s1)
- w
-
The width of the rectangle (4s1)
- h
-
The height of the rectangle (4s1)
- filename
-
The filename of the image file to create. The directory path to the filename must exist and the filename will be overwritten if it is. The filename must end with either a .bmp extension to generate BMP formatted images or .tga to generate TGA formatted images.
Dump the contents of the screen to an image file.
- Plugin:
-
libgre-plugin-screen-dump.so
- Options:
-
- filename
-
The filename of the image file to create. The directory path to the filename must exist and the filename will be overwritten if it is. The filename must end with either a .bmp extension to generate BMP formatted images or .tga to generate TGA formatted images.
Execute a system command. System commands will be dependent on the underlying operating system. The result of the command will be logged to standard output.
- Plugin:
-
libgre-plugin-system.so
- Options:
-
- command
-
A system command to execute in text form.
Start, stop and control a timer.
- Plugin:
-
libgre-plugin-timer.so
- Options:
-
- name
-
The name to use to identify this timer (required)
- rtime
-
The time delay in milliseconds relative to the action invocation. Specify a value of 0 to stop an existing timer.
- repeat
-
The number of milliseconds to delay after the timer first fires, used to provide a stable repeat timer. Specify 0 for a one shot timer.
- count
-
The number of times that the timer should repeat before automatically stopping, assuming that the timer is not a one shot timer. Specify -1 to allow an unlimited number of repeat firings
rtime must be specified and a value of 0 for rtime and repeat indicates that the timer should stop firing.
For example, to start a timer that fires in 1s from the event and then every 500ms afterwards:
<action ... type="gra.timer" data="name=MyTimer,rtime=1000,repeat=500" />
Then to stop the timer:
<action ... type="gra.timer" data="name=MyTimer,rtime=0,repeat=0" />
An event will be generated each time that the timer fires and will be named timer.<name> so for the examples above, the event would be generated would be timer.MyTimer.
Stop a timer.
- Plugin:
-
libgre-plugin-timer.so
- Options:
-
- name
-
The name to use to identify this timer (required)
For example, to start a timer that fires in 1s from the event and then every 500ms afterwards:
<action ... type="gra.timer" data="name=MyTimer,rtime=1000,repeat=500" />
Then to stop the timer:
<action ... type="gra.timer.stop" data="name=MyTimer" />
The following actions can be used to control the media playback. Note that all actions take a “channel_name” argument. This is used to target a specific playback channel. For example if a video is started with “gra.media.new.video” with “channel_name=video1” then any subsequent action which wants to act on this video, such as play/pause, must set the channel “video1”.
Tells the plugin to play a new audio file.
The action arguments are:
- channel_name
-
The channel name the new video is to be played on
- media_name
-
The name of the media to play, full path to an audio file
- volume
-
The initial volume value to play the media at. The value should be between 0 and 100.
- update_interval
-
The number of milliseconds to wait in between update messages
- emit_time_events
-
A value that is set to 1 to emit time update events, 0 otherwise
- extra_data
-
Any extra data that should be passed to the backend, can be NULL
Tells the plugin to play a new video file.
The action arguments are:
- channel_name
-
The channel name the new video is to be played on
- media_name
-
The name of the media to play, full path to a video file
- volume
-
The initial volume that the media should be played at
- object_name
-
The name of the external object to display content on. This is necessary when using an external render extension to display the content, please refer to the external render extension documentation
- external_buffer_name
-
The name of the render extension to display content on. This is necessary when using an external render extension to display the content, please refer to the external render extension documentation
- update_interval
-
The number of milliseconds to wait in between update messages
- emit_time_events
-
A value that is set to 1 to emit time update events, 0 otherwise
- output_width
-
The width of the video
- output_height
-
The height of the video
- output_depth
-
The output depth of the video in bytes per pixel. 16bit = 2, 24bit = 3, 32bit = 4
- extra_data
-
Any extra data that should be passed to the backend, can be NULL. See each backend for a description of this data
Triggers a change in the playback volume.
The action arguments are:
- channel_name
-
The channel name to change the volume on
- volume
-
The value to change the volume to, a number between 0 and 100
- emit_volume_event
-
A value that is set to 1 if an event should be emitted or 0 otherwise
Triggers a change to the current playback position of the media that is playing.
The action arguments are:
- channel_name
-
The channel name to change the seek position on
- seek_num
-
The new seek position for the media file
- emit_state_event
-
A value that is set to 1 if an event should be emitted or 0 otherwise
Changes the media playback state to stopped.
The action arguments are:
- channel_name
-
The channel name to change the state on
- emit_state_event
-
A value that is set to 1 if an event should be emitted or 0 otherwise
Changes the media playback state from paused to playing.
The action arguments are:
- channel_name
-
The channel name to change the state on
- emit_state_event
-
A value that is set to 1 if an event should be emitted or 0 otherwise