Tcl Interpreter

Snowmix Tcl Interpreter Guide

This page has been updated for Snowmix-0.4.4

Snowmix comes with a built-in Tcl Interpreter for flexible and complex scripting. Snowmix can execute a single line of Tcl command or commands as well as execute Tcl scripts. Furthermore the interpreter has been expanded with functionality to execute Snomwix commands as well as to query Snowmix for its internal settings.

Snowmix has the following Tcl Interpreter related commands:

tcl eval <tcl command>
tcl exec <command macro>
tcl help
tcl reset

These commands are explained further down in this text.

The interpreter gets initialized when Snowmix first meet a line beginning with 'tcl'. This can either be in the ini file, on the control console later or through a control connection to Snowmix. The interpreter can be cleared and re-initialized using the Snowmix command tcl reset.

Within the Tcl Interpreter, Snowmix offers the following additions to standard Tcl offered by the Interpreter:

snowmix info .....
snowmix message <text>
snowmix parse <snowmix command>
snowmix parse silent <snowmix command>
snowmix parses <snowmix command>

These commands are explained further down in this text.

tcl eval

A single tcl command can be executed in the interpreter using the command prefix tcl eval. Anything on the line following tcl eval is send to the Interpreter. The following example is the "Hello world" example

tcl eval puts "Hello world!"

This example prints the text string "Hello world! on the Snowmix Console. If executed on a control connection, the result will also print the text string to the Snowmix Console and not the control connection.

The above example could also be implemented like this:

tcl eval set a "Hello world!"
tcl eval puts $a

Or as a one-liner:

tcl eval set a "Hello world!" ; puts $a

tcl exec

In addition to the command tcl eval, that only can execute one line at a time, the command tcl exec offers to execute multiple lines of code stored in a Snowmix macro. This is shown in the following example:

command create HelloWorld.tcl
  set a "Hello"
  set b "world!"
  puts "$a $b"
command end
tcl exec HelloWorld.tcl

One important thing to note is that the last 4 characters of the command macro containing the tcl script are '.tcl'. This is not strictly necessary, but it can prevent a lot of error messages printed on the Snowmix console. The issue is that when a command macro is defined, ie. when the command command end is detected, the created macro is parsed for identifying Snowmix if-then-else-endif sections and label entries etc. However this is skipped if the last 4 characters of the macro name is '.tcl'.

Executing Snowmix commands within the interpreter.

The interpreter offers two ways of executing Snowmix commands directly from within the interpreter. The two ways are:

snowmix parse <snowmix command>
snowmix parse silent <snowmix command>

The two ways are identical except the parse silent will prevent printing messages on the control connection sending the command, should the Snowmix command otherwise normally print such messages. The parse silent can also be written as:

snowmix parses <snowmix command>

Note that all commands executed as part of excuting the command macro set for either overlay pre or overlay finish will always be silent.

The examples above demonstrates how to execute a Snowmix command from within a tcl script. When used from the Snowmix command line, the command will need the prefix tcl eval. The following example shows this:

tcl eval set a "This is a string"
tcl eval set b 2
tcl eval snowmix parse "text string $b $a"

This example set the Snowmix text string id 2 to "This is a string".

Printing to the Snowmix control connection

If a script should write its output to the control connection sending the tcl command or the tcl script, the command or script must use the command snowmix message. It can not use the puts as this will only write to Snowmix Console. Using the *snowmix message is demonstrated in the example below:

tcl eval set a "message"
tcl eval snowmix message "This is a $a"

If executed through a control connection, the following will be written to the control connection:

MSG: This is a message

It will include a terminating newline.

Getting internal Snowmix settings into the interpreter

THIS SECTION IS BEING DEVELOPED.

Snowmix offers the following commands within the Tcl interpreter to query Snowmix for its internal settings:

snowmix info audio (feed | sink) (info | status | extended | syntax) (format | ids | maxid | nextavail | <id_list>)
snowmix info audio mixer (info | status | extended | source info | source status | source extended | syntax) (format | ids | maxid | nextavail | <id_list>)
snowmix info command ( names | list | at | syntax ) [ format | <name> ]
snowmix info feed (geometry | status | extended | state | syntax) (format | ids | maxid | nextavail | <id_list>)
snowmix info image (load | place | move | extended | syntax) (format | ids | maxid | nextavail | <id_list>)
snowmix info text (string | font | place | move | backgr | linpat | syntax) (format | ids | maxid | nextavail | <id_list>)
snowmix info (vfeed | virtual feed) (place | move | extended | syntax) (format | ids | maxid | nextavail | <id_list>)
snowmix info shape (info | list | place | move) ( format | ids | maxid | nextavail | <id_list> )
snowmix info system (info | status | maxplaces | overlay | syntax) [ format ]
snowmix info shape ( syntax | ( ( info | list | place | move ) ( format | ids | maxid | nextavail | <id_list>) )
snowmix info system (info | status | maxplaces | overlay | syntax) [ format ]

All the commands are also available on the Snowmix command line by pre-pending the command with tcl eval. However as the function snowmix info is returning a string rather than printing anything, the following command will appear not to have any result.

tcl eval snowmix info system info

However we can ask Snowmix to print a string from within the interpreter by using the snowmix message function like this:

tcl eval snowmix message [snowmix info system info]

Depending on the internal settings of Snowmix, the result printed to the control connection may look like this:

MSG: {1280 720} ARGB 4 30.000000000 3686400 {127.0.0.1/32 192.168.1.0/24 192.168.10.0/24} 0.4.4 {pmm-mac.local}

This is a Tcl list with 9 elements. The first element is "MSG:". The second element is a list with 2 elements "1280" and "720". The third element is "ARGB etc. To understand what is what we can execute the following command

tcl eval snowmix message [snowmix info system info format]

The extra format parameter will make the function snowmix info return its format like this:

MSG: geometry pixel_format pixel_bytes frame_rate block_size host_allow version system_name

Here we see the second element being the "geometry" and when we executed the command before without the format argument, we found the second element in the list to be a list with the two elements "1280" and "720".

The Snowmix Libraries system.slib has two functions that helps getting information. These are GetFromKey and GetFromKeyId. Using these functions has the advantage that should the command snowmix info in the Interpreter change its output, functions using GetFromKey etc. should still work while code using a specific order in the list output from snowmix command may fail.

The following example shows how to use GetFromKey to get the system geometry assuming the system.slib has been loaded:

tcl eval snowmix message [GetFromKey "system info" geomerty]

The example may result in this being printed to the control connection including a terminatin newline:

MSG: 1280 720

To print the geometry of image loaded 2, the following can be used:

tcl eval snowmix message [GetFromKeyId "image load" geometry 2]

may result in the following printed:

MSG: 1280 720

Please see the documentation for system.slib for additional documentation on the functions.

Please ask questions in the forum regarding snowmix info if you want tips and tricks.

Executing a string returned by the interpreter

In Snowmix prior to version 0.5.0, a string returned by a call to the interpreter would be executed by Snowmix if pre-pended by a newline. This will disappear in version 0.5 and onward, but is still present in 0.4.x so be careful about returns.

It is recommended that a tcl procedure/function for the interpreter is always ended with an empty return, when nothing is returned. This is demonstrated in the following example:

command create example.tcl
  set b ""
  proc MyFunction {a} {
    snowmix message "MyFunction called with $a. b was $b"
    set b "\n$a"
    return
  }
command end
tcl exec example.tcl
tcl eval MyFunction "text string 2 Hello world"

The above example is safe because the return ensures that the function returns an empty string. Without the empty string, the function would return the result of the last action in the function and as this was a text string pre-pended with a newline and a valid snowmix command, it would set the text string id 2 to "Hello world".

---

The rest of this document is out of date and needs to be rewritten for Snowmix 0.4.4.

Snowmix offers an interface to a Tcl interpreter for flexible scripting. Results from the interpreter can automatically be feed into the command parser of Snowmix thus offer full integration between Snowmix's command parser and the TCL scripting language. For further explanation, let's look at an example. We assume we have a feed 0 with geometry of 1024x576.

    virtual feed add 0 Main Feed
    virtual feed source feed 0 0
    tcl eval set x 0 ; set y 0; set width 512 ; set height 288; set id 0
    tcl eval set scale_x [expr $width / 1024.0]
    tcl eval set scale_y [expr $height / 576.0]
    tcl eval return [format "\nvirtual feed place rect %d %d %d %d %d 0 0 %f %f 1.0" $id $x $y $width $height $scale_x $scale_y]

The first line defines a virtual feed number 0. The second line defines the virtual feed to be sourced by the real feed 0. The third and fourth line sets up some variables in tcl to be used in the fifth line. The lines are executed individually and state is kept across each tcl evaluation. The third, fourth and fifth line do return a single result string from the execution, but it is ignored, as Snowmix discard anything returned until the first encountered newline.

The sixth line returns a the following string preceeded with w newline:

    virtual feed place rect 0 0 0 512 288 0 0 0.500000 0.500000 1.0

This string after the leading newline will be executed as snowmix command and if the virtual feed is defined to be displayed in the main loop, feed 0 will be displayed scale by 50% and placed at 0,0. If the tcl evaluation returns multiple lines, each line after the leading newline will be excuted as a snowmix command.