The vgTcl Suite

Tcl/Tk Bindings, Scripts, and Utilities for
Vega 3.4, AudioWorks2 3.4, and IRIS Performer 2.2.x

MultiGen-Paradigm Inc.
14900 Landmark Blvd, Suite 400
Dallas TX 75240 USA
972-960-2301

http://www.paradigmsim.com/
vggifts@paradigmsim.com

PLEASE NOTE
*** The vgTcl Suite is a vgGift. ***

vgGifts are provided as unsupported freeware. They are not official MultiGen-Paradigm products. No warranty expressed or implied. If it breaks, you get to keep both pieces.

Your feedback is welcome and appreciated. Send your comments and suggestions to vggifts@paradigmsim.com; please do not contact Paradigm Customer Support.

Contents

For the latest updates, search for "New in vgTcl 3.4"

Related Docs

0.0 What Is It?

The vgTcl Suite is a set of Tcl/Tk bindings, example scripts, and utilities for the Vega, AudioWorks2, and IRIS Performer APIs. Most functions available through the C APIs are available interactively at runtime. Applications no longer must be monolithic binaries of bounded capability; apps can be assembled at runtime of small interactive scripts, with capabilities added as needed.

Tcl/Tk (pronounced tickle-tea-kay) is the scripting Tool Command Language and graphical user interface Tool Kit created by John Ousterhout. Tcl/Tk runs on all Unix/X systems, Microsoft Windows, and Apple Macintosh. The source code is freely available on the net.

The vgTcl Suite offers a flexible continuum of development options:

This document describes vgTcl Suite version 3.4. If you are familiar with a previous version, please refer to the change log for important differences.

The vgTcl Suite is built for OpenGL and the MIPS "n32" ABI. Full source code is provided for your reading and recompiling pleasure.

0.1 Definitions

The vgTcl Suite
the package of shared libraries, script libraries, and tools to enable the development and control of applications using Vega, AudioWorks2, and IRIS Performer through the Tcl/Tk language. vgTcl, awTcl, pfTcl, psish, and the libpfpftcl loader are components of the Suite. Available free of charge as a vgGift.

vgTcl
the environment and libraries which provide Tcl/Tk access to the MultiGen-Paradigm Inc. Vega realtime visual simulation toolkit. If there are no relevant differences, the term vgTcl may be used to refer to vgTcl, awTcl, and pfTcl collectively.

awTcl
the environment and libraries which provide Tcl/Tk access to the MultiGen-Paradigm Inc. AudioWorks2 realtime audio simulation toolkit.

pfTcl
the environment and libraries which provide Tcl/Tk access to the Silicon Graphics IRIS Performer visual simulation toolkit.

the libpfpftcl loader
a IRIS Performer loader which evaluates ".pftcl" files.

tcltk803
An IRIX 6.x n32 build of Tcl, Tk, and Extended Tcl version 8.0.3. Welch97 is a good reference for tcltk803. Distributed with the vgTcl Suite free of charge as a vgGift. tcltk803 will not interfere with the sgitcl already installed on your system.

Vega
Vega is MultiGen-Paradigm's industry leading simulation software environment for real-time visual simulation, virtual reality, and general visualization applications. It is a high-level user-friendly graphics development environment layered on Silicon Graphics' IRIS Performer toolkit.

AudioWorks2
AudioWorks2 is MultiGen-Paradigm's real-time 3D spatialized audio simulation software environment. Its is available stand-alone, or fully integrated with Paradigm's Vega visual simulation and virtual reality software.

IRIS Performer
IRIS Performer is a high performance 3D rendering toolkit for developers of real-time, multiprocessed, interactive graphics applications for the Silicon Graphics product line.

1.0 Prerequisites

IMPORTANT: Verify your system is up to date with the current recommended patchset. Previous versions of IRIX (before IRIX 6.5) require patches for these n32 binaries to function. At time of writing, significant patches are 2153, 2580, and 2715. See http://support.sgi.com/ for the latest information regarding patches.

2.0 Installing

Use swmgr or inst to install tcltk803 and the vgTcl Suite.

3.0 Demonstrations

3.1 Quick Demo 1

Execute the following, one line at a time, and observe the effects:
(This demonstration assumes the Vega special effects module is installed and licensed.) 
    cd /usr/local/PSI/vgtcl/demo/quick1
    /usr/local/PSI/bin/vegax.tcl ./quick1.adf &	# start a Vega renderer
    /usr/local/PSI/bin/addpanel.tcl		# add a GUI window
    ./circle.tcl tank &				# drive the tank in a circle
    ./spin.tcl xyz r 5 &			# roll the XYZ
    ./drop.tcl bomb tank &			# drop bomb on the tank
Summary: The behaviors of three players (tank, xyz, and bomb) are controlled by separate processes outside the simulation, all communicating with a simple Vega application written in Tcl.

3.2 An Interactive Demo

Execute the following, one line at a time, and observe the effects:
(This demonstration assumes you do not have a $HOME/.psishrc initialization file.) 
    /usr/local/PSI/bin/psish
    ## Make the base Vega API available to Tcl.
    package require Vgtcl_ogl
    ## Initialize Vega
    vgInitSys
    puts "You are using vgTcl [vgtcl version]"
    ## Load an ADF and create the Vega window
    vgDefineSys /usr/local/PSI/vgtcl/demo/quick1/quick1.adf
    vgConfigSys
    ## Render a single frame
    vgSyncFrame; vgFrame
    ## What #defines are available for vgGfx?
    vgtcl keywords VGGFX*
    ## Turn on wireframe and render a single frame
    vgProp [vgGetGfx 0] VGGFX_WIREFRAME 1; vgSyncFrame; vgFrame
    ## Turn off wireframe and render a single frame
    vgProp [vgGetGfx 0] VGGFX_WIREFRAME 0; vgSyncFrame; vgFrame
    ## What Vega classes are available?
    vgtcl names
    ## What are the names of all the existing vgPlayers?
    vgtcl names vgPlayer
    ## Make a simple GUI
    pack [button .b -text "Quit" -command {vgExit 0}]
    ## Turn on timing statistics and render a frame
    vgProp [vgGetChan 0] VGCHAN_STATSSEL VGCHAN_TIMING; vgSyncFrame; vgFrame
    ## Start infinite loop to render frames
    vgtcl render
    ## Click on "Quit" button to terminate the app
Summary: This demo does not run any pre-existing Vega executable; the simulation is created interactively, line-by-line, at runtime.

3.3 Quick Demo 2

Run the vostok demo, and add a GUI to it at runtime: 
    cd /usr/local/PSI/vgtcl/demo/vostok
    ./vostok.tcl vostok.adf &
    /usr/local/PSI/bin/addpanel.tcl
Summary: The executable in this demo is a line-for-line translation of a C code executable to Tcl/Tk code. The demo reuses the addpanel.tcl script introduced earlier. addpanel.tcl can be reused with many vgTcl apps to add a simple GUI window whenever one is needed.

4.0 Using the vgTcl Suite for your Application

4.1 Using the psish Interactive Shell

psish is a version of the standard Tcl/Tk wish windowing shell, customized for use with the vgTcl Suite. For general information regarding wish, please see the References section.

psish startup files

psish loads startup files depending on the name by which it is invoked. Before any other evaluation occurs, a system-wide startup file named /usr/local/lib32/tcl8.0/system.EXENAMErc is evaluated, where EXENAME is the basename of the executable. A good way to automatically load libraries for a class of scripts is to create a symlink to psish with a new name and create a system.newnamerc script, which will package require the needed libraries and do any customized startup necessary. For a typical example, see /usr/local/lib32/tcl8.0/system.psishrc.

On interactive runs, a per-user startup script called $HOME/.EXENAMErc is also evaluated just before starting the commandloop. That script can be used by individuals to setup commonly used procedures or to override default behavior. That is a handy place to put things like "wm withdraw ." to conceal the pesky Tcl/Tk root window. For a typical example, see /usr/local/PSI/vgtcl/demo/home/.psishrc.

4.2 Embedding a Tcl Interpreter in a C/C++ Application

To build Tcl/Tk support directly into an application, call:
    Tcl_Interp *interp = Psitcl_CreateInterp( argv[0], "vega", NULL );
at initialization time, then call: 
    Psitcl_Update();
during the simulation loop. More sophisticated features are available; see psitcl_shell.h, and the sample code vgtcl_basic.c and pftcl_simple.c

If the environment variable PSITCLRC is defined, Psitcl_CreateInterp() will execute that string as a Tcl/Tk script.

4.3 Using the libpfpftcl Performer loader

The new libpfpftcl loader is a regular Performer file loader, and is automatically invoked by pfdLoadFile() for any file with the extension ".pftcl".

A loader's job is: given the name of a file, return the top node of a scene graph represented by the file. That task is typically accomplished by a file parser that reads data structures from the file and invokes the appropriate API (usually pfdBuilder) to create the Performer scene graph structures. In a typical Performer loader, that mapping between data structures and scene graph API invocations is cast in stone by the loader's algorithm coded in C.

With the libpfpftcl loader, the loader creates a Tcl interpreter, then hands the "datafile" to the interpreter. The interpreter then evaluates that file as a script; it's the datafile/script's job to invoke whatever API (pfdBuilder or anything) gets the job done. There is no hardcoded data/API mapping; the data are API invocations and can be any algorithm. The loader never sees (and doesn't care about) the contents of the file.

The pftcl loader is great for creating algorithmic geometry. For example, for performance testing, using two nested for loops, one can create a 2D grid with thousands of copies of a test model. You can also create geometry exactly to specification, without learning/using a modeller. None of this is magic; you could do the same thing by modifying application code using the Performer C API and recompiling. The point is, with the libpfpftcl loader, you don't need to modify an app; loading a bunch of cars is as easy as
perfly parkinglot.pftcl

Want a 3D grid of cars? Create a file with a 3rd for loop, then
perfly cube-o-cars.pftcl

A .pftcl "datafile" can even pop open a GUI to ask how to build the geometry; see starmaker.pftcl.

Of course, Vega loads .pftcl files too.

If the environment variable PSITCLRC is defined, libpfpftcl will execute that string as a Tcl/Tk script before loading the first .pftcl file.

The "interpreter object"

The libpfpftcl loader works great at loadtime, but what about runtime?

For a Tcl interpreter to be active at runtime, it needs two things:

  1. to be created and initialized (i.e. Psitcl_CreateInterp)
  2. to have its update function called often (i.e. Psitcl_Update)
The libpfpftcl loader does #1 at load time, but at runtime the interpreter sits there doing nothing. Enter the "interpreter object": it is a simple .pftcl file that creates a new pfGroup and sets the PFTRAV_APP pfNodeTravFunc to call the interpreter update function. Performer invokes that callback every frame during the APP traversal, and voila, that's all it takes to wake up the interpreter at runtime.

So to add an interactive interpreter to any Vega/Performer application (including Vega Active Preview), all we need to do is load a .pftcl file which performs those steps; see pfinterp.pftcl and vginterp.pftcl.

The decision to have an interpreter at runtime is now up to the simulation user, not the developer.

Using the libpfpftcl loader with Vega Active Preview

New in vgTcl 3.4
By default, Vega Active Preview (VegaAP) processes keyboard events to provide common capabilities such as toggling texture and wireframe modes. Using the interpreter object, it is possible to install your own vgTcl key handling routine into VegaAP. However, your vgTcl key handler and VegaAP will race to receive key events. You can disable VegaAP's handling of key events by setting the VGAP_NOKEY environment variable.

5.0 Techniques for writing vgTcl scripts

This section describes specific details about writing scripts using the vgTcl Suite. For general Tcl/Tk programming information, please see the References section.

5.1 Loading vgTcl extensions

Before a script can execute commands using a vgTcl API, the interpreter must first load the package that provides that API. For example, if a script executes the following commands, 
package require Vgtcl_ogl
package require Vgfxtcl_ogl
package require Pftcl_ogl
the base Vega, Vega Special Effects, and Performer APIs will be available.

The following packages are available in the vgTcl Suite, as defined by the package index file /usr/local/lib32/PSI/pkgIndex.tcl:

5.2 Automatically loading vgTcl extensions

New in vgTcl 3.4
The Vgu_AutoPackageRequire procedure will determine the Vega modules that are currently active, and will automatically invoke the appropriate package require commands. It is typically most useful for C programs that have already executed the vg*Init() functions for the necessary Vega modules.

5.3 Automatically initializing Vega modules

New in vgTcl 3.4
Given the name of a Vega ADF, Vgu_InitAdfActiveModules will invoke the vg*Init procedures for the Vega modules declared active by the ADF. Useful for creating a general-purpose vgTcl executable without knowing ahead of time which Vega modules might be needed. See vegax.tcl as an example.

6.0 Contents of the vgTcl Suite

This is a quick summary of many of the components of the vgTcl Suite. See the individual script files themselves for detailed usage information and additional documentation.

6.1 Contents of /usr/local/PSI/bin/

psish
(pronounced sigh-shell) The "Paradigm Simulation Inc." Tcl/Tk shell.
An enhanced version of the standard Tcl/Tk wish shell, customized for the Vega/AudioWorks2/Performer/IRIX environment.

psicon
(pronounced sigh-con) A remote console for controlling Tcl/Tk apps.
psicon provides an interactive commandline to any vgTcl app. Use the menu to select which application psicon controls.

pospeek.tcl
Creates a general purpose GUI for displaying the position of any Vega object. Has an optional "map" mode which can display a background image. Clicking/dragging on the map sends positioning commands back to the parent application.

posgrab.tcl
Creates a general purpose GUI for grabbing the position of any Vega object. Each grabbed position is saved to a list for later recall by clicking on that list. Each position may be given a descriptive name. Position lists may written to and read from files. Position files can be turned into vgPath and vgSplineNavigator files with genpath.tcl.

vgpos.tcl
Creates a general purpose GUI for manipulating the position of any Vega object. Sliders make it easy to tune exact positions.

addpanel.tcl
When executed, adds a simple GUI panel to any running vgTcl application. That GUI panel controls stats mode, general vgGfx states, and various vgChannel parameters.

genpath.tcl
Given a file of positions as written by posgrab.tcl, generate vgPath and vgSplineNavigator files. Can also be used to algorithmically generate paths.

send
A UNIX commandline version of the Tcl/Tk send command.
Permits interactive control of a vgTcl without starting up a psicon.

vegax.tcl
A simple Vega application, written in Tcl, with some handy predefined key bindings created using the VgtclUtil.tcl library. Press the "?" key to pop open a help window.

showheir.tcl
New in vgTcl 3.4
Prints the heirarchy of a Performer database file. Demonstrates the pftclTraverse command, which executes Tcl scripts as callbacks during the scenegraph traversal.

speedometer.tcl
New in vgTcl 3.4
A general purpose GUI for displaying the velocity of a motion model.

winvis.tcl
New in vgTcl 3.4
Queries a running Vega app to determine the X visual actually received for each vgWindow.

jsftiles
New in vgTcl 3.4
A map display GUI for selecting and displaying tiling information about the MultiGen-Paradigm Joint Strike Fighter database.
It has no dependency on vgTcl, and runs without modification on IRIX and Windows.

6.2 Contents of /usr/local/PSI/vgtcl/demo/

4view/
A simple demo of four Vega windows reparented within a Tcl/Tk window.

8chan/
A GUI control for testing an 8 channel speaker configuration using awTcl. Channels 1-4 are the bottom quad, 5-8 are the top quad.

siren/
An AudioWorks demo with GUI using awTcl, which enables you to explore the effects of various AudioWorks2 features.

caffeine/
A vgTcl app with integrated GUI to explore the effects of single precision jitter.
See the README.

home/
An example ".psishrc" psish interactive startup script for your home directory.
See the README.

vgbasic/
An example of adding Tcl/Tk support to a Vega C application.

pfsimple/
An example of adding Tcl/Tk support to a Performer C application.

vostok/
Direct C to Tcl translation of /usr/local/PSI/sample/fx/vostok.c

misc/
A random collection of other examples, such as micro.tcl, the world's smallest Vega executable (136 bytes).

town/
New in vgTcl 3.4
An example using pospeek.tcl with a map image as a plan-view display for the Vega "town" database.
See the README.

jsf/
New in vgTcl 3.4
An example using pospeek.tcl with a map image as a plan-view display for the MultiGen-Paradigm Joint Strike Fighter database.

socket/
New in vgTcl 3.4
A demonstration of a remotable Tcl/Tk GUI that can be run across multiplatform environments with no code modifications.
It consists of a simple Vega rendering app and a separate control panel GUI app that use sockets for communication instead of the Tcl/Tk send command, so the apps do not require a shared X server to communicate.
The GUI app is portable, and will run without modification on IRIX or Windows.
See the README.

6.3 Contents of /usr/local/lib32/PSI/

Psiutil.tcl
Generic tcl/tk utility procedures for managing Tcl interpreters and toplevel windows.

VgtclObjectSwitch.tcl
A dialog box for adding/removing vgObjects from the vgScene.

VgtclSimpleGui.tcl
Components for a simple Vega GUI, including checkboxes, menu bar, and sliders.

VgtclUtil.tcl
Vega utility procedures for managing key bindings, toggling properties, managing objects in vgScenes, and much more.

6.4 Contents of /usr/local/PSI/demo/

These .pftcl model files can be referenced by LynX when creating Vega Application Definition Files (ADFs), or loaded directly into perfly; e.g.: perfly starmaker.pftcl.

square.pftcl
A multicolored square created using pfTcl.

octo.pftcl
A multicolored octohedron created using pfTcl.

parkinglot.pftcl
A grid of cars created using two Tcl for loops.

starmaker.pftcl
Pops open a GUI to specify how a star should be built.

vginterp.pftcl
Creates an "interpreter object" customized for Vega.
Example using an ADF that references vginterp.pftcl: 
	vega /usr/local/PSI/adf/vginterp_demo.adf &
	send vega vgGetNumObj
vega will return the number of vgObjects defined in the ADF. 
	send vega info command vg\*
vega will return a list of commands beginning with "vg".

pfinterp.pftcl
Creates an "interpreter object" customized for Performer.
Example: 
	setenv PFPATH /usr/local/PSI/demo
	perfly pfinterp.pftcl octo.pftcl &
	send performer pfGetSharedArenaSize
perfly will return the size of the shared arena. 
	send performer info command pf\*
perfly will return a list of commands beginning with "pf".

argtest.pftcl
New in vgTcl 3.4
Demonstration of a experimental "command line argument" passing mechanism for communicating with a pftcl script.

7.0 API Additions

A command has been added to each of the vgTcl/awTcl/pfTcl environments; individual operations are implemented as subcommands.

Subcommands of vgtcl

vgtcl names
Returns a list of Vega class names; for example,
vgtcl names
might return something like "vgMotion vgObject vgWindow vgChannel..."

vgtcl names classname [pattern]
Returns a list of Vega instances of classname; for example,
vgtcl names vgPlayer
returns a list of the existing vgPlayer names.
If provided, only names that match pattern are returned.

vgtcl keywords [pattern]
Returns a list of Vega manifest constants; for example,
vgtcl keywords VGGFX_*
returns a list of vgGfx constants.
If provided, only keywords that match pattern are returned.

vgtcl value keyword
Returns the value of a Vega manifest constant; for example,
vgtcl value VGGFX_FADERANGE
returns 2008.

vgtcl getpos handle
vgtcl getpos handle x y z h p r
The first form returns the XYZHPR of a vgCPos as a list of six values. The second stores the XYZHPR in the six variables provided. A shortcut similar to vgGetPos/vgGetPosVec.

vgtcl setpos handle x y z h p r
Sets XYZHPR of a vgCPos. A shortcut similar to vgPosVec/vgPos.

vgtcl reparent tkwindow vgwindow
Reparent a Vega window within a Tcl/Tk window.

vgtcl render [proc]
Infinite loop to render graphics; a shortcut similar to:
while {1} { vgSyncFrame; vgFrame; update }
If provided, proc is evaluated every iteration of the loop. If proc executes a Tcl break command, the loop terminates.

vgtcl break
Terminates a vgtcl render loop from outside the loop.

vgtcl version
Returns a library version number.

vgtcl modules [pattern]
Returns a list of Vega product modules available.
If provided, only names that match pattern are returned.

Subcommands of awtcl

awtcl names
Returns a list of AudioWorks class names.

awtcl names classname
Returns a list of AudioWorks instance names of classname.

awtcl keywords [pattern]
Returns a list of AudioWorks manifest constants.
If provided, only keywords that match pattern are included.

awtcl value keyword
Returns the value of an AudioWorks manifest constant.

awtcl getpos handle
awtcl getpos handle x y z h p r
The first form returns the XYZHPR of an awCommon as a list of six values. The second stores the XYZHPR in the six variables provided. A shortcut similar to awGetPos/vgGetPosVec.

awtcl setpos handle x y z h p r
Sets XYZHPR of an awCommon. A shortcut similar to vgPosVec/awPos.

awtcl render [proc]
Infinite loop to render audio; a shortcut similar to:
while {1} { awFrame [awGetClockSecs]; update }
If provided, proc is evaluated every iteration of the loop. If proc executes a Tcl break command, the loop terminates.

awtcl break
Terminates a awtcl render loop from outside the loop.

awtcl version
Returns a library version number.

Subcommands of pftcl

pftcl keywords [pattern]
Returns a list of Performer manifest constants.
If provided, only keywords that match pattern are included.

pftcl value keyword
Returns the value of an Performer manifest constant.

pftcl version
Returns a library version number.

7.1 API Changes

While changes to the C API were minimized whenever possible, some C idioms do not map well to Tcl/Tk's native representations; in those situations "Tcl-isms" were substituted. For example, the following C prototype:

int vgGetPosVec( vgPosition *pos, float *x, float *y, float *z, float *h, float *p, float *r );

is implemented in vgTcl as:

vgGetPosVec pos

which returns a Tcl list consisting of an integer status value, followed by six floats representing XYZHPR.

Commands provide a help message if called with incorrect arguments, so feel free to experiment.

7.2 Environment Variables

PSITCLRC
The contents of PSITCLRC are evaluated by Psitcl_CreateInterp() as a Tcl script. Typically used to specify a startup command to be run during Tcl interpreter creation.
A typical example:
setenv PSITCLRC "wm withdraw ."

PSITCLDISPLAY
Used by various vgTcl scripts to specify on which X display to open Tcl/Tk GUI windows; see Psiutil.tcl.
If unset, the value defaults to the standard DISPLAY environment variable.
This variable does not affect the opening of Vega/Performer windows.

8.0 Known Bugs and Limitations

  1. X input events are sometimes not received by Vega windows reparented within Tcl/Tk windows.
  2. The demo scripts are short on exception handling.
  3. Tcl/Tk is not MP-safe, and thus should only be used in the APP process.
  4. Portions of the Vega and Performer API are not supported, particularly those involving callbacks or varargs.

9.0 About Tcl/Tk and X server security

The X Window System provides two separate security mechanisms, xauth and xhost. xauth is usertoken-based, and is much more secure than xhost, which is hostname-based.

To use the Tcl/Tk interprocess communication mechanism (as provided by the send command), Tcl/Tk enforces a conservative security configuration where:

By default, SGI X servers are configured in exactly the opposite state, providing no security at all.

How to enable xauth

  1. Become superuser:
    su
  2. Edit the X Display Manager configuration file:
    vi /var/X11/xdm/xdm-config
  3. Change the line saying:
    DisplayManager*authorize: off
    to
    DisplayManager*authorize: on
  4. Restart the X server and X Display Manager (Note: this will log you out!):
    (/usr/gfx/stopgfx; killall xdm; /usr/gfx/startgfx) &

How to disable xhost

Update: X authorization in IRIX 6.5

New in vgTcl 3.4
In IRIX 6.5, it appears that xhost is disabled by default (which is good). However, the toolchest now provides a couple tempting menu items: Those menu items manipulate xhost. Do not use Enable Remote Display, as it will simply invoke "xhost +".

10.0 References

Copyright 1998-1999 MultiGen-Paradigm Inc. -- ALL RIGHTS RESERVED
$Id: README.html,v 2.17 1999/06/11 20:34:13 mew Exp $