Note: On OS X, run X11 before running Syzygy graphical programs.

For complete functionality, Syzygy programs have to be run in Cluster Mode. However, it's often more convenient to run a single instance of a program in Standalone Mode. The advantage of Standalone Mode is that no Syzygy server or supporting programs are required.

New in Syzygy 1.2: it is now possible to load input device drivers in Standalone Mode.

How a Program Determines Whether to Run in Standalone Mode

When a Syzygy program is run, it goes through the following decision process to determine whether or not it is running in Standalone mode:

  1. It determines the current user's system name (as reported by the native operating system).

  2. It looks for a corresponding Syzygy login file (described in Creating a Cluster: The Syzygy Login Files.

  3. If this file exists and specifies that the user is logged into a Syzygy server, then the program attempts to connect to the server.

  4. If it connects successfully, the program is running in Cluster Mode.

  5. Otherwise, the program is running in standalone mode.

    You can force programs to run in standalone mode by issuing the "dlogout" command. This modifies your Syzygy login file to specify that you are not logged into a server.

    If it is running in standalone mode, your program will print (among many other lines of start-up information) the following line:
    szg:CRITICAL: my_program_name running standalone.
    

    Test standalone mode by running "hspace", a master/slave sample application, and "parade", a distributed scene graph sample application. These are both contained in the base Syzygy distribution and can be downloaded or compiled as described in Getting the Software. For more information on the different styles of Syzygy programs, please consult the Introduction to Syzygy programming.

    When running "hspace" in standalone mode, something looking like a green spiderweb should fill the window. There will also be a small overlay window in the lower right corner showing the tracker simulator interface, whose operation is described in this chapter. When running "parade", you will see a collection of collection of virtual humans marching across the screen, again with the tracker simulator in the lower left corner. More information about these and other sample applications is included in Example Programs.

Configuration Information in Standalone Mode

When a Syzygy program starts, it needs to be configured with information regarding where it should find data files, where it should place its graphics screen on the desktop, and where sound and texture files exist, among other things. In Standalone Mode this information is read from an XML file. By default, the program looks for a file in the current working directory named either szg_parameters.xml or szg_parameters.txt, in that order. However, the file name can be overriden by passing a special command line argument to the program, for example:

my_program_name arg1 arg2 -szg parameter_file=szg_anaglyph.xml
my_program_name arg1 arg2 -szg parameter_file-szg_virtualcave.xml

Note that any arguments prefaced by -szg are interepreted as special Syzygy arguments and are removed from the argument array and processed by the Syzygy libraries before the array is handed to the application code.

If the program cannot open the specified config file it will check to see if the environment variable SZG_PARAM is set; if so, it will use SZG_PARAM's value as a file name and try to load that file.

For a discussion of the format of the information in this file, see the System Configuration chapter. The only aspect of this format that is specific to Standalone Mode regards the specification of the computer name. In Cluster Mode, each computer-specific or local parameter must be defined using the name of the computer, e.g.

my_computer SZG_DATA path C:\Data

In Standalone Mode, on the other hand, the value NULL can be substituted for the computer name (since there's only one computer under consideration):

NULL SZG_DATA path C:\Data

If a program requests the value of a configuration parameter and it is not present in the file, the program will try to get it from an environment variable whose name consists of the parameter's group and name. For example, if the program wants the value of the parameter SZG_DATA/path, it will look for an environment variable named SZG_DATA_path containing the value.

Device Drivers in Standalone Mode

Prior to Syzygy 1.2, applications running in standalone mode could not use input devices; instead, they loaded and displayed the Input Simulator, which allows the user to simulate a tracked head and wand using the mouse and keyboard.

Now, however, standalone applications can load input device drivers. New in version 1.3: Previously, the syzygy libraries had to be dynamically linked (i.e. SZG_LINKING=DYNAMIC) in order to use this capability. Now this is only true with Visual C++. The choice between the Input Simulator and a device driver is made using the database parameter SZG_STANDALONE/input_config, which defaults to "simulator". If given any other value, this is assumed to be the name of a global input device configuration parameter in the parameter file. Any defined input sources (drivers), filters, and PForth filter code are loaded.

Alternate Input Simulators

As of 2/08, you can create your own Input Simulator as a shared library and load it at runtime based on the value of the Syzygy database parameter SZG_INPUTSIM/sim_type. A stupid example called arDefaultInputSimulator is contained in szg/skeleton; it behaves just like the built-in one, but it does show you which methods are available for overriding. Copy the skeleton directory tree somewhere, rename the source file, and modify skeleton/build/makefiles/Makefile.my_app appropriately. To use it, add e.g. the following in an <assign> block in your szg_parameters.xml:

  NULL SZG_INPUTSIM sim_type arDefaultInputSimulator

...and provided your app can find it, it should load an use it.