This chapter explains how to configure Syzygy for display devices.

Thanks to Lee Hendrickson for creating Syzygy's "arGUI" flexible windowing.

As discussed in Syzygy System Configuration, a Syzygy parameter or 'dbatch' file contains two types of parameters, local (computer-specific) and global. Specification of graphical display devices falls into the global category; after defining one or more display devices, you define local parameters for each computer specifying which display or displays it will use.

Global Graphics Parameters

The Syzygy graphics system contains a number of different levels of objects linking the 2-D space of your computer screen or screens to the 3-D space of the virtual world. Starting from the 3-D end, which is also the bottom of the object hierarchy, these are:

  1. Screens: rectangular windows in the virtual world.
  2. Cameras: devices for computing the viewing frustum. Some types use screens.
  3. Viewports: regions of a window, each with an attached camera.
  4. Viewport Lists: Sets of viewports within a single window, either enumerated 'by hand' or auto-generated by pre-defined viewing modes.
  5. Windows: windows of your computer's graphical interface.
  6. Displays: the top-level object; each running render program has one and only one. May contain multiple windows (but usually only one).

Screens

A screen is a virtual window into the virtual world. It is defined by three unit vectors (center, normal, and up) that specify its position and orientation and by its width and height in feet. Note that the normal vector points away from the viewer, and the three vectors don't have to specified as unit vectors, they will be normalized. Note also that all of these quantities represent virtual-world coordinates. Generally speaking, you will probably want them to be congruent with the real-world layout of your physical screens, but you certainly don't have to set them up that way.

A screen has a number of other parameters:

Cameras

A camera is an object for computing the viewing frustum. There are three types of cameras:

The other two types of cameras don't use a screen or head object (or head tracking, for that matter). They also specify near and far clipping planes. Ordinarily, Syzygy programs specify their own near and far clipping distances, and the VR camera honors these. The other two camera types don't. For these reasons, they are only useful in special circumstances:

Both are specified with the following two parameters:

Viewports

A viewport binds a camera object to a specific sub-region within a window on your computer screen. Besides a camera, a viewport has the following parameters:

Note that you can specify more than one viewport in the same part of the window, in fact it's sometimes necessary. For example, to manually specify a red/cyan anaglyph stereo window (this is unnecessary, as we'll see below), you would create two viewports with coords=(0/0/1/1): the first with e.g. colormask=(R=yes/G=no/B=no/A=yes) and eyesign value=-1., the second with colormask=(R=no/G=yes/B=yes/A=yes), eyesign=1., and depthclear=yes.

Here's a very ordinary viewport, with the point of view at the midpoint of the eyes.

<param>
  <name>viewport_default</name>
  <value>
    <szg_viewport>
      <szg_camera usenamed="camera_default" />
      <coords left="0." bottom="0." width="1." height="1." />
      <depthclear value="no" />
      <colormask R="yes" G="yes" B="yes" A="true" />
      <eyesign value="0." />
      <ogldrawbuf value="GL_BACK_LEFT" />
    </szg_viewport>
  </value>
</param>

Note that for boolean values, yes/no and true/false are interchangeable.

Viewport Lists

A viewport list may contain one or more viewports. They can be specified in a couple of different ways:

  1. By setting the viewmode parameter to 'custom' and defining a viewport list in which you enumerate a set of viewports using the parameters described above.
  2. By setting the viewmode parameter to one of the pre-defined viewing modes. In these viewing modes, you only specify a camera that is shared by the viewports; the software automatically generates one or more viewports. The number of viewports generated depends on whether or not the window's "stereo" parameter is set to "true" (for active stereo). In each case, two sets of viewports are created if active stereo is in use; one set has eyesign set to -1 and ogldrawbuf set to GL_BACK_LEFT, while the other has eyesign set to +1 and ogldrawbuf set to GL_BACK_RIGHT. Each set is as described below. If active stereo is not in use, all viewports have ogldrawbuf set to GL_BACK_LEFT. In most of the viewing modes, pairs of viewports are generated with eyesign equal to 1 and -1.

    The predefined viewing modes are:
    • normal: A single viewport that fills the window, i.e.:
        <szg_viewport_list viewmode="normal">
          <szg_camera usenamed="camera_default" />
        </szg_viewport_list>
      
      ...is equivalent to:
        <szg_viewport_list viewmode="custom">
          <szg_viewport>
            <szg_camera usenamed="camera_default" />
            <coords left="0." bottom="0." width="1." height="1." />
            <depthclear value="no" />
            <colormask R="yes" G="yes" B="yes" A="true" />
            <eyesign value="0." />
            <ogldrawbuf value="GL_BACK_LEFT" />
          </szg_viewport>
        </szg_viewport_list>
      
      ...or if active stereo is in use, to:
        <szg_viewport_list viewmode="custom">
          <szg_viewport>
            <szg_camera usenamed="camera_default" />
            <coords left="0." bottom="0." width="1." height="1." />
            <depthclear value="no" />
            <colormask R="yes" G="yes" B="yes" A="true" />
            <eyesign value="-1." />
            <ogldrawbuf value="GL_BACK_LEFT" />
          </szg_viewport>
          <szg_viewport>
            <szg_camera usenamed="camera_default" />
            <coords left="0." bottom="0." width="1." height="1." />
            <depthclear value="no" />
            <colormask R="yes" G="yes" B="yes" A="true" />
            <eyesign value="1." />
            <ogldrawbuf value="GL_BACK_RIGHT" />
          </szg_viewport>
        </szg_viewport_list>
      

    • anaglyph: As described above, for stereo viewing with red/cyan anaglyph glasses, available from [http://www.berezin.com/3D/3dglasses.htm] or [http://www.3dglassesonline.com/]. This:
        <szg_viewport_list viewmode="anaglyph">
          <szg_camera usenamed="camera_default" />
        </szg_viewport_list>
      
      ...is equivalent to (without active stereo; note colormask and depthclear values):
        <szg_viewport_list viewmode="custom">
          <szg_viewport>
            <szg_camera usenamed="camera_default" />
            <coords left="0." bottom="0." width="1." height="1." />
            <depthclear value="no" />
            <colormask R="yes" G="no" B="no" A="yes" />
            <eyesign value="-1." />
            <ogldrawbuf value="GL_BACK_LEFT" />
          </szg_viewport>
          <szg_viewport>
            <szg_camera usenamed="camera_default" />
            <coords left="0." bottom="0." width="1." height="1." />
            <depthclear value="yes" />
            <colormask R="no" G="yes" B="yes" A="yes" />
            <eyesign value="1." />
            <ogldrawbuf value="GL_BACK_LEFT" />
          </szg_viewport>
        </szg_viewport_list>
      
      Note that this will only work properly if your scene is rendered in gray-scale.
    • walleyed: Divides the window in half horizontally, with the left-eye image in the left half and the right-eye image on the right. For e.g. the Screenscope viewer. This:
        <szg_viewport_list viewmode="walleyed">
          <szg_camera usenamed="camera_default" />
        </szg_viewport_list>
      
      ...is equivalent to:
        <szg_viewport_list viewmode="custom">
          <szg_viewport>
            <szg_camera usenamed="camera_default" />
            <coords left="0." bottom="0." width=".5" height="1." />
            <depthclear value="no" />
            <colormask R="yes" G="yes" B="yes" A="yes" />
            <eyesign value="-1." />
            <ogldrawbuf value="GL_BACK_LEFT" />
          </szg_viewport>
          <szg_viewport>
            <szg_camera usenamed="camera_default" />
            <coords left=".5" bottom="0." width=".5" height="1." />
            <depthclear value="no" />
            <colormask R="yes" G="yes" B="yes" A="yes" />
            <eyesign value="1." />
            <ogldrawbuf value="GL_BACK_LEFT" />
          </szg_viewport>
        </szg_viewport_list>
      
    • crosseyed: The converse of the above, with the right-eye image on the left and vice versa.
    • overunder: Divides the window in half vertically, for viewers like the View Magic.

As stated above, all of the viewing modes described here can be combined with active stereo. This is not something you'd want to do for normal VR, but it's there if you need it.

Windows

A Syzygy window corresponds to a window of your computer's graphical interface. A window contains a viewport list and the following additional parameters:

Displays

Each Syzygy rendering program will attach itself to a display. As of Syzygy 0.8, a display contains one or more windows; previously each process could only open one window.

Other parameters of displays are:

Nesting Parameter Definitions

Putting it all together: Up til now I've been putting each object in it's own <param> block and then referring to it later by name. Which is elegant and flexible, but verbose. You can also glom it all together into one XML record, as shown here:

<param>
  <name>display_glommed</name>
  <value>
    <szg_display framelock="none" threaded="no">
      <szg_window>
        <size width="400" height="300" />
        <position x="50" y="50" />
        <decorate value="false" />
        <fullscreen value="true" />
        <cursor value="none" />
        <title value="A Syzygy Window" />
        <stereo value="false" />
        <zorder value="topmost" />
        <szg_viewport_list viewmode="walleyed">
          <szg_camera type="vr">
            <szg_screen>
              <center x="0." y="0." z="-3." />
              <up x="0." y="1." z="0." />
              <normal x="0." y="0." z="-1." />
              <dim width="8." height="6." />
              <headmounted value="yes" />
              <usefixedhead value="ignore" />
              <fixedheadpos x="0.0" y="5.0" z="0.0" />
              <fixedheadupangle value="0.0" />
              <tile tilex="0" numtilesx="1" tiley="0" numtilesy="1" />
            </szg_screen>
          </szg_camera>
        </szg_viewport_list>
      </szg_window>
    </szg_display>
  </value>
</param>

or, omitting default and unimportant values:

<param>
  <name>display_compact</name>
  <value>
    <szg_display>
      <szg_window>
        <size width="400" height="300" />
        <position x="50" y="50" />
        <decorate value="false" />
        <fullscreen value="true" />
        <cursor value="none" />
        <zorder value="topmost" />
        <szg_viewport_list viewmode="walleyed">
          <szg_camera type="vr">
            <szg_screen>
              <center x="0." y="0." z="-3." />
              <up x="0." y="1." z="0." />
              <normal x="0." y="0." z="-1." />
              <dim width="8." height="6." />
              <headmounted value="yes" />
              <usefixedhead value="ignore" />
            </szg_screen>
          </szg_camera>
        </szg_viewport_list>
      </szg_window>
    </szg_display>
  </value>
</param>

(Actually, headmounted="yes" is the default, but I figure that's important enough to always specify explicitly).

Basically, any tag beginning with 'szg_' represents a record that can either be embedded within another record or split off into its own named parameter.

Local Graphics Parameters

As mentioned in the Syzygy System Configuration chapter Syzygy configuration parameters are global or local. There are three sets of local parameters that are relevant to the display of your virtual world: head parameters, selection of displays, and resource paths. If one of these parameters is not defined in the parameter database, then Syzygy will query an appropriate environment variable for the value (see Standalone Mode for an explanation).

Heads

As mentioned above in the Cameras section, a Syzygy VR camera requires a head object to compute the viewing frustum. This object contains information about the spatial relationships between the eyes and a tracking sensor on the user's head. These do not need to be defined on every computer, just on each computer that is either a master or trigger (NOTE: need a link here). A master computer is one on which the master instance of a master/slave application runs; the controller program of a distributed scene graph application runs on the trigger computer. These programs will share the head information with relevant other programs running on the cluster. When running in Standalone Mode, the current computer is both master and trigger for the purposes of this section. Please see the chapter on the Cluster Mode for a definition of these terms.

A head has the following parameters:

An example. The following block of parameters specifies that, for computer 'Machine':

Display Selection

As discussed in the section on displays, each computer can be assigned one or more display objects. These are differentiated on the basis of a 0-based index, i.e. the default display is #0, the next #1, etc.

A simple example should suffice to demonstrate the selection of two displays (we'll use named displays defined above) for the computer named 'Machine':

  Machine SZG_DISPLAY0 name display_default
  Machine SZG_DISPLAY1 name display_compact

TroubleShooting

The global graphics parameter portions of a Syzygy parameter ('dbatch') file are not parsed when the file is loaded, but when an application is launched and about to open a window. Error messages will typically begin with:

  szg:ERROR: arGUIXML ...

...and will usually give a fairly accurate indication of where the error occurred.

Besides XML syntax errors, the parser will catch mis-spelled attribute names. It will also catch illegal attribute values if the set of legal values is small (e.g. if the value must be one of yes/no/true/false). It makes no attempt to check that numerical values are reasonable, so to catch that sort of error you'll have to inspect the virtual scene display itself.

Graphics Configuration Examples

A number of special Graphics Configuration Examples are included in a separate chapter: