This chapter will show you how to configure Syzygy to work with your equipment.
Syzygy maintains a database for storing useful bits of information in a way that your program can easily get at. Some of this information is used by the Syzygy libraries to configure your application; you can also use it for storing your own application parameters.
In Standalone Mode, the information is read in from a parameter file (by default, named either szg_parameters.xml or szg_parameters.txt) in the current directory. You make changes to the configuration by editing this text file before launching the application.
In Cluster Mode, this database is maintained by the Syzygy Server
and accessed from within the application by means of the arSZGClient
object. The database parameters can be examined and changed one at a time
dset commands, or they can be set in large batches
by invoking the
dbatch command with the name of a parameter file.
Happily, the parameter
file for the
dbatch command has the same format as the Standalone Mode
parameter file. A separate set of parameters is maintained for each user,
so any database commands will access the database for the last user logged
in to the Syzygy server using the
This is the simplest way to load a large number of parameters in to the Syzygy database. To load a file-full of parameter information:
dbatch <file path>
<file path> can be either an absolute or relative path from the current directory
or a file name. If the latter,
dbatch will look for the file in the current working
directory. If it isn't there, it will query the Syzygy database for the value of the
local parameter SZG_SCRIPT/path. If this parameter is defined it
will interpret it as a directory path and look for the named file there.
To print all of the current user's database parameters:
If you redirect this to a file (``dget -a >myparams.xml"),
that file can be used for subsequent
To list all parameters containing a particular string (either in the computer name, group name, parameter name, or value):
dget -a <string>
dget -a my_computer lists all parameters defined for the computer
'my_computer`, and any others that happen to contain that string (such as single lines from
virtual computer definitions).
Parameters in the Syzygy database are either global (not tied to any particular computer) or local (computer-specific).
There are two main types of global parameters: graphics configurations and input device descriptions. These parameters allow the user to define complex attributes of the system --for example, a graphics window corresponding to one eye of a head-mounted display, or the configuration of a tracking device--without having to consider which computer will perform those functions. This facility makes it easier to re-arrange and replace computers in your cluster.
Global parameters are keyed only by name, and their values are specified in XML. Their structure can be quite complex, so they are discussed in two separate chapters:
Read the Syzygy Graphics Configuration chapter.
Read the Syzygy Input Device Configuration chapter.
When running a Syzygy cluster, it is possible (although not very practical) to get and set values of individual global parameters at the command line.
To set a single global parameter using the
dset parameter_name parameter_value
However, the value is typically a longish XML string; global parameters are generally specified in a parameter file.
Similarly, you could set a single parameter value using:
Local parameters give information that is particular to a given computer. They are specified or keyed within the database by the computer name, a parameter group, and the parameter name. In documentation, these are typically written as a slash-delimited string, i.e.
<computer name>/<parameter group>/<parameter name>
For example, the parameter to tell a computer named 'my_computer' the standard location for data files, is represented by:
However, to set these parameters, use the format below.
When interacting with the database, either via
dset in Cluster Mode
or in a parameter file, the key elements are separated by spaces. A parameter file
entry line for the parameter above might look like:
my_computer SZG_DATA path G:\Data
or to set it in Cluster Mode using
dset my_computer SZG_DATA path G:\Data
If you then typed
dget my_computer SZG_DATA path
the command would return the value
See the relevant section in the Syzygy Graphics Configuration chapter.
See the relevant section in the Syzygy Graphics Configuration chapter.
Read the chapter on Resource Path Specification.
A virtual computer is a means of specifying how a set of computers are wired together and what functions each will perform. You run a program on a virtual computer by issuing a single command; the separate instances of the program and any supporting services are then launched automatically.
Syzygy parameter files are written in XML. A parameter file can contain 3 types of XML records, <comment>, <assign>, and <param>. These records cannot be nested. For instance, a <comment> block cannot appear within an <assign>. They can appear in the file in any order, however, and there can be any number of them.
A <comment> record contains a comment. These are discarded by the parser. An <assign> record contains either a list of local parameter definitions or a virtual computer definition. Finally, a <param> record contains a global parameter definition.
Here is an example. Note the required <szg_config>/</szg_config> tags that enclose the entire file:
<szg_config> <comment> This is what comments look like in a complex parameter file. The following 'assign' record contains a number of local parameter definitions. </comment> <assign> smoke SZG_DATA path /home/public/Data smoke SZG_RENDER texture_path /home/public/Texture smoke SZG_RENDER text_path /home/public/Texture/Text smoke SZG_SOUND path /home/public/Sounds smoke SZG_DISPLAY0 name head_mounted </assign> <comment> The following 'param' record contains a global device definition. </comment> <param> <name> windows_joystick_filter </name> <value> define filter_axis_0 getCurrentEventAxis 0.000031 * setCurrentEventAxis enddef define filter_axis_1 getCurrentEventAxis -0.000031 * setCurrentEventAxis enddef </value> </param> </szg_config>
We've included several templates for the main parameter files in use at the Illinois Simulator Lab. For each template, a valid configuration file for a particular user is generated by substituting his Syzygy user name for "THE_USER_NAME".
The file cube.txt gives a template parameter file for a 6-sided fixed screen VR environment (virtual computer=cube). It also demonstrates how different virtual computers (cube and wincube) can share the same virtual computer location (cube).
The file lab.txt gives a template parameter file for a lab containing a group of workstations, a dual-headed passive stereo display (virtual computer=passive), an Immersadesk-style active stereo display (virtual computer=idesk), and a 3x2 video wall (virtual computer=wall). This template also demonstrates the use of include directives in dbatch files. The include locations are given by SZG_SCRIPT local parameters and the included files contain screen configurations, device configurations, and virtual computer definitions respectively.
The file cave.txt gives a template parameter file for a 4-sided fixed screen VR environment (virtual computer=cave).