Plugin Action Definitions

The following actions are only available when optional Storyboard plugins has been loaded.

gra.lua

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 variable myvar 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}.

gra.animate

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.

gra.animate.stop

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]

gra.audio

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.

gra.greio

Send a new event over a Storyboard IO channel.

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 target of the event to generate (optional)

format

The format of the event data (optional)

data

The data payload for the event

gra.perf_state

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.

gra.redirect

Redirect all events to another Storyboard IO channel.

Plugin:

libgre-plugin-redirect.so

Options:
channel

Storyboard IO channel name to send the events to

gra.screen.path

Causes a screen transition to occur by fading the old screen into the new one.

Plugin:

libgre-plugin-screen-path.so

Options:
screen

The screen to transition to

rate

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.

all
delta

moving

The screen(s) to animate with the desired path transition.

both
new only
old only

gra.screen.scale

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

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

gra.screen.glswitch

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

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

gra.screen.glrotate

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

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.

all
delta

gra.screen.glflip

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

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

gra.screen.gldoors

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

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.

all
delta

gra.screen.gltip

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

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.

all
delta

gra.screen.glcube

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

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.

all
delta

gra.screen.rotate

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.

gra.screendump

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

gra.timer

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.

gra.timer.stop

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" />

Media Actions

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

gra.media.new.audio

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

gra.media.new.video

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

gra.media.volume

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

gra.media.seek

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

gra.media.stop

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

gra.media.resume

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

gra.media.pause

Changes the media playback state from playing to paused.

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