Syzygy Documentation

Where To Begin

The documentation's "Getting Started" system teaches you how to

• build or otherwise obtain the software,
• run the sample applications in "standalone" mode
• set up a Syzygy cluster
• run the samples on your cluster.
  

Gradually work up to a full cluster, taking time to understand how Syzygy's distributed operating system works. Learn how the included applications are built and how their data files are installed. This will make it easier for you to write your own portable cluster applications.

When you're comfortable with the introductory material, learn how to write Syzygy programs in C++ or Python, and read descriptions of some of the APIs in Syzygy Programming.

What Does "ar" Mean?

In its source code, Syzygy objects are all prefixed with "ar", which stands for "artificial reality". The "vr" prefix, which would be another logical choice, is simply too common, and, in any case, Syzygy is useful in domains other than VR.

Getting Started

• GettingSoftware: Downloading and compiling the source code. If using Microsoft Visual C++, also see VisualStudioBuildVars. Syzygy can be compiled on Windows using the  MinGW GNU compiler, and in fact the newer SIP-based Python bindings have only been built with the GNU compiler.
• SupportingLibraries: Installing and using libraries that add features to Syzygy.
• Standalone: Running on a single, unclustered, PC.
• ExampleCode: Running the included examples, where to put their data files, etc.
• InputSimulator: Emulating a tracked input device (Intersense, Ascension, etc.) with Syzygy's inputsimulator, e.g. in standalone mode.
• SystemConfiguration: Specifying parameters of a VR system with the Syzygy Database, in both Standalone and Cluster modes. This includes:
  • GraphicsConfiguration: Arranging display devices. See also Examples.
  • PathConfiguration: Defining search paths for sound files and texture maps.
  • Setting Up, Testing, and Managing a Syzygy Cluster: Configuring a cluster's input devices and virtual computers.

Creating Syzygy Programs

• Programming: Writing programs using Syzygy's application frameworks.
• QuickPort: Porting an OpenGL/GLUT-based application, in a hurry.
• CompileCPP: Compiling and linking C++ programs.
• If you're planning on modifying the libraries, see also Compiler Idiosyncrasies
• PythonBindings: Writing Python programs.
• Sound: The spatial sound system.
• 3DObjectFiles: External meshes (.obj or .3ds) and animations in.
• Navigation: Navigating a 3D world in an application.
• Interaction: Classes and functions for picking, grabbing, and interacting with objects in a 3D world.
• PortabilityLayer: OS-independent classes and functions for sockets, serial ports, time, threads, mutexes, etc.
• RandomNumbers: Generating shared sequences of pseudo-random numbers in all running instances of a master/slave application (described in  Programming).

Setting Up, Testing, and Managing a Syzygy Cluster

• ClusterMode: Setting up PC clusters and running programs on them (see also Configuring Virtual Computers.)
• ClusterTest: Basic testing of a cluster.
• InputDevices: Using input devices in a cluster.
• InputDevices-Drivers: List of supported input devices.
• InputDeviceConfiguration: Configuring input devices.
• PForth: The PForth ("Pseudo-FORTH") input-filtering language. A stack-based language for transforming streams of input events (e.g., re-mapping input device button indices).
• TrackerCoordConversion: How to map the coordinates reported by your tracking device into the Syzygy coordinate system.
• Vrtest: A "sanity check" application for narrowing down misbehaviors.
• AppFeatures: Tricks for managing cluster applications using the 'dmsg' command.

Miscellaneous

• szgview: szgview is a viewer for certain 3D file formats.
• SyzygyEnvironmentVariables: A complete listing of environment variables either affecting or affected by Syzygy operation.

Advanced Topics

• InputClasses: Arcane details about the code objects that handle input data.
• InputFilters: Writing an input-event filter in C++. Usually PForth is better than C++.

Background Information

• Architecture: Overall design.
• Goals: Goals.
• ChangeLog: Changes between versions, since the beginning.
• Testing: Tested configurations and testing procedures.
• Bugs: Known bugs, problems, and issues with the current version.