Reference Command

Reference Manual - Command

Updated for Snowmix 0.4.4.

This is the reference manual for Snowmix for the commands belonging to the the command class. See also:

• Reserved Commands overview
• Reference manual for general commands
• Reference manual for command macros
• Reference manual for audio feed commands. See also Audio.
• Reference manual for audio mixer commands. See also Audio.
• Reference manual for audio sink commands. See also Audio.
• Reference manual for feed commands.
• Reference manual for text commands. See also Video Text and Snowmix Tutorials on text.
• Reference manual for image commands.
• Reference manual for shape commands. See the manual page on Shapes.
• Reference manual for placed shapes.
• Reference manual for Cairo Graphics Primitives used in shapes
• Reference manual for virtual feed commands.

This section of the manual describe all commands beginning with the reserved keyword command as well describing commands that can be used inside created/defined commands. Please also see the manual page on basic Snowmix Scripting.

Overview

            command addatline <command name> <line number> <command>
            command afterend <command name>
            command at [[+]<time> <command ........>] // time =  [[hh:]mm:]nn[.nnnnn]
            command create <command name>
            command delete <command name>
            command deleteline <command name> <line number>
            command end
            command help
            command list [<command name>]
            command pointer atline [ <command name> [ <line> ]]
            command pop <command name> [ <count>]
            command push <command name> <command>
            command restart <command name>

The following control commands are only available within commands.

            if <condition>
            else
            endif
            goto <label name>
            next [<number>]
            label <label name>
            loop [<number>]

            <condition> = ['!']<cond> [('||' | '&&') <condition>]
            <cond>      = <feedstate> | <prevstate> | <exist>
            <feedstate> = feedstate(<feed no>,<feed state>) |
            <prevstate> = prevstate(<feed no>,<feed state>) |
            <exist>     = exist(command,<command name>);
            <feed no>   = 0....(2^32)-1
            <feed state>= 'SETUP' | 'PENDING' | 'RUNNING' | 'STALLED' | 'DISCONNECTED'

command addatline

Name

command addatline - Inserts a new command line at a specific line in a created command macro.

Synopsis

command addatline <command name> <line number> <command>

Description

The reserved command command addatline adds a command line to a specific already created command macro. The reserved command command list <command macro name> can be used to identify the line at which the new command should be added.

Example

command addatline HelloWorld 4 text string 1 Hello to you too.
command addatline HelloWorld 5 text place 1 1 0 100 120 0 0 0 1.0

This will make the text 'Hello to you too.' appear at 100,120.

See also

command create, command list, command delete, command deleteline, command pop, command push, command at.

command afterend

Name

command afterend - move the macro's execution pointer beyond the end.

Synopsis

command afterend <command name>

Description

The reserved command command afterend is used to set the macro's execution pointer to point beyond the end of the macro. When the execution pointer of a macro is beyond the end, the macro is effectively not doing or changing anything when called. To re-activate the macro again, the command command restart or command pointer atline can be used. Command macros without a loop or some other mechanism to adjust the macro's execution pointer position, will eventually, when called enough times, end up in a state, where the execution pointer is pointing beyond the end of the macro.

Example

command afterend HelloWorld

See also

command create, command restart, command pointer atline, loop

command at

Name

command at - Execute a specific command macro at a given time.

Synopsis

command at [+][[hh:]mm:]nn[.nnnnn] <command ........>
command at

Description

The reserved command command at <command macro name> execute the command macro given once at the specified time. If the time is specified with a preceeding '+', the time given is considered to be relative from the time the command was given. Otherwise the time is considered absolute since Epoch, which is 1st Jan 1970.

Example

command at +1:10 command restart HelloWorld
command at +1:10.5 command HelloWorld

This will reset the macro's command execution pointer in the command HelloWorld to the beginning of that command after 1 minute and 10 seconds and 0.5 seconds later the command will be executed. After a timed command macro has been executed, the macro is deleted from the list of timed commands, but the macro will still exist and can be reused. The reserved **command delete <command macro name> can be used to delete a command macro that is no longer needed.

The command command at without any further specifications will list timed commands awaiting time to elapse.

See also

command create, command list, command addatline, command delete, command deleteline, command pop, command push, command at.

command create

Name

command create, command end - Create a command

Synopsis

command create <command name>
command end

Description

The command create creates a new command macro holding zero or more commands. When the command command create is given, anything written after that will be added to this command until a line with command end is given.

Example

command create HelloWorld
  text string 0 Hello World!
  text font 0 Sans Bold 12
  text place 0 0 0 100 100 0 0 0 1.0
command end
command Show
  overlay text all
command end
overlay finish Show

In the example above, the command HelloWorld is created. If the command HelloWorld is later given, the text 'Hello World!' will appear on the screen. When a command macro is executed, line for line in the command macro will be executed until a next or a loop is reached. If a command macro does not end with a loop, then successive calls to the command macro will not have any effect until the command macro is restarted with the reserved command command restart <command macro name>. A command macro created can not create new command macros. A command macro created can not include a file with the command include for performance reasons. If the reserved command command create <command macro name> is later given for a command macro already created, anything given until command will be appended to the command macro.

See Also

command list, command delete, command afterend, command restart, command addatline, command deleteline, command pop, command push, command at, label, goto, if else endif, loop, next

command delete

Name

command delete - Deletes a created command

Synopsis

command delete <command macro name>

Description

The reserved command command delete <command macro name> deletes a created command macro. If the command specify a command macro that does not exist, nothing will happen.

Example

command delete HelloWorld

See also

command create, command list, command deleteline, command addatline, command pop, command push, command at.

command deleteline

Name

command deleteline - Deletes a specific line in a created command macro.

Synopsis

command deleteline <command macro name> <line number>

Description

The reserved command command deleteline deletes a specific line in a created command macro. If the command specify a command macro that does not exist, nothing will happen. If the line number given is larger than the number of lines the macro holds, the given command will be appended to the macro at the end.

Example

command deleteline HelloWorld 3

See also

command create, command list, command delete, command addatline, command pop, command push, command at.

command help

Name

command help - list available command commands.

Synopsis

command help

Description

The reserved command command help list the available command commands.

Example

command help

See also

help, text help, image help, feed help, virtual feed help, shape help, shape place help, audio feed help, audio mixer help, audio sink help, tcl help.

next

Name

next - postpone further execution of this command macro until the macro is called again.

Synopsis

next [<count>]

Description

The reserved command next when used inside a command macro postpone any further execution of commands in a command macro until the command macro is called again. This command is typically, but not always, used to postpone any further execution of the command until next frame. If the reserved command next is given with a number <count>, the command will postpone further execution of the command macro count times. Not specifying count is equivalent to next 1.
When count of the reserved command next reaches zero, the command execution pointer of the command macro will be advanced to the next line and further execution of the command macro will take place. The reserved command next can only be used inside a command macro and will not have any effect outside a command macro.

Example

command create HelloWorld
  text string 0 Hello World!
  text font 0 Sans Bold 12
  text place 0 0 0 100 100 0 0 0 1.0
  next 25
  text string 0 Goodbye World!
command end

In the example given above, if the command macro is called by the main loop, the text Hello World! will be displayed for 25 frames and then be replaced by the text Goodbye World!.

See also

command create, overlay finish, loop

command list

Name

command list - List name of command macros or list content of a command macro.

Synopsis

command list
command list <command macro name>

Description

The reserved command command list list names of all command macros. The command command list <command macro name> list the content of a specific command macro.

Example

command list

command list HelloWorld

See also

command create, command delete, command deleteline, command addatline, command pop, command push, command at.

command pointer atline

Name

command pointer atline - List name of command macros or list content of a command macro.

Synopsis

command pointer atline [ <command name> [ <line> ]]</line>

Description

The reserved command command pointer atline is used to reposition the execution pointer of a command macro. Using the command without arguments, list the number of lines and the execution pointer position of each command macro defined. Using only a macro name as argument, list the number of lines and the execution pointer for that command macro. Using both a command macro name and a line number as argument reposition the execution pointer of the macro to the specified line. If the execution pointer of a macro is beyond the end of the macro, the line number printed will be -2.

Example

command pointer atline
command pointer atline HelloWorld
command pointer atline HelloWorld 5

See also

command create, command restart, command deleteline, command addatline, command pop, command push.

command pop

Name

command pop - Delete the last line in a command macro.

Synopsis

command pop <command name> [ <count>]

Description

The reserved command command pop is used to delete the last line in a command macro. The command is often used in conjunction with the command push to add a command to a macro before the last line. The last line in a macro is often a loop, but it will of course depend on configuration. The command require a single argument being the name of the command macro for which the last line is to be deleted. If a number is specified as the second argument, the last number* of lines will be deleted from the macro specified.

Example

command pop Show
command push Show image overlay 23
command push Show loop

See also

command create, command deleteline, command addatline, command push.

command push

Name

command push - Add a command to end of a command macro.

Synopsis

command push <command name> <command>

Description

The reserved command command push is used to add commands to the end of a command macro. The command is often used in conjunction with the command pop to add a command to a macro before the last line. The last line in a macro is often a loop*, but it will of course depend on configuration.

Example

command pop Show
command push Show image overlay 23
command push Show loop

See also

command create, command deleteline, command addatline, command pop.

command restart

Name

command restart - Set the execution pointer of a macro to the beginning.

Synopsis

command restart <command name>

Description

The reserved command command restart is used to reset the execution pointer of a macro to the beginning of a macro. Any counter associated with the commands loop and next* within the macro will also be reset.

Example

command restart Show

See also

command create, command pointer atline, command afterend.

loop

Name

loop - postpone further execution of this command macro until the macro is called again and eventually reset the command execution pointer of a command macro

Synopsis

loop [<count>]

Description

The reserved command loop when used inside a command macro postpone any further execution of commands in a command macro until the command macro is called again. Furthermore the command execution pointer of the macro will be reset to the start of the macro. This command is typically used to both reset the command execution pointer of a macro to the start and to postpone any further execution of the command until next frame. If the reserved command loop is given with a number <count>, the command will loop count times. Not specifying count will ensure that the command always loops which will reset the command execution pointer of the command macro the command loop appear in. If count of the reserved command loop is specified and when the count reaches zero, the command execution pointer of the command macro will be advanced to the next line and further execution of the command macro will take place.

Example

command create HelloWorld
  text string 0 Hello World!
  text font 0 Sans Bold 12
  text place 0 0 0 100 100 0 0 0 1.0
  loop 25
  text string 0 Goodbye World!
  next 25
  text string 0 See You Soon.
  next 24
  loop
command end

In the example given above, if the command macro is called by the main loop, the text Hello World! will be displayed for 25 frames and then be replaced by the text Goodbye World! for 25 frames and then be replaced by the text See You Soon for 24+1 frames. The command will then loop and start over.

See also

command create, overlay finish, goto

goto, label

Name

goto - change the command execution pointer of a command macro to jump to the label given by the command.

Synopsis

goto <label name>
label <label name>

Description

The reserved command goto when used inside a command macro will change the command execution pointer of a macro to the line specified by the label name. If the label name does not exist, the command will have no effect.

The reserved command label when used inside a command macro is used to specify a jump point that can be used by the reserved command goto. The label command it self has no effect.

Example

command create HelloWorld
  text string 0 Hello World!
  text font 0 Sans Bold 12
  text place 0 0 0 100 100 0 0 0 1.0
  goto SeeYou
  label Goodbye
  text string 0 Goodbye World!
  next 25
  label SeeYou
  text string 0 See You Soon.
  next 25
  goto Goodbye
command end

In the example given above, if the command macro is called by the main loop, the text Hello World! will be displayed for 25 frames and then be replaced by the text See You Soon. for 25 frames. It will then jump to the label Goodbye and execute from there etc.

See also

command create, overlay finish, next

if, else, endif

Name

if, else, endif - for conditional execution

Synopsis

if <condition>
  command
  command
  ...
else
  command
  command
  ...
endif

The syntax for condition is:

<condition> = ['!']<cond> [('||' | '&&') <condition>]
<cond>      = <feedstate> | <prevstate> | <exist>
<feedstate> = feedstate(<feed no>,<feed state>)
<prevstate> = prevstate(<feed no>,<feed state>)
<exist>     = exist(command,<command name>)
<feed no>   = 0....(2^32)-1
<feed state>= 'SETUP' | 'PENDING' | 'RUNNING' | 'STALLED' | 'DISCONNECTED'

Description

The reserved command if, else and endif when used inside a command macro will allow for conditional execution of command lines. All if line must have a corresponding endif line. A if line can have a corresponding else line. Lines with if can be nested**.

If a condition given is true, the lines below the if line will be executed until the line with else if given. If else is not specified, execution will then continue after the line with the corresponding endif. If the condition given is false, execution will continue at the else line if present. Otherwise execution will continue after the endif line.

Example

command create HelloWorld
  text string 0 Running
  text string 1 Disconnected
  text string 2 Stalled
  text font 0 Sans Bold 12
  if feedstate(1,STALLED)
    text place 0 2 0 100 100 0 0 0 1.0
  else
    if feedstate(1,RUNNING)
      text place 0 0 0 100 100 0 0 0 1.0
    else
      if feedstate(1,DISCONNECTED)
        text place 0 1 0 100 100 0 0 0 1.0
      endif
    endif
  endif
  next 10
  loop
command end

In the example given above, if the command macro is called by the main loop, the text a text display the state of feed 1 will be shown. If the state of the feed change, this change will be shown with a delay of 10 frames - assuming the command is called at every frame.

See also

command create, overlay finish, next, loop, goto, label