Beckman Institute            University of Illinois at Urbana-Champaign             

Documentation Table of Contents

This chapter will show you how to configure Syzygy to work with your display devices.

Thanks to Lee Hendrickson for creating the arGUI toolkit that provides Syzygy with a flexible windowing system.

• Global Graphics Parameters
  • Screens
  • Cameras
  • Viewports
  • Viewport Lists
  • Windows
  • Displays
• Nesting Parameter Definitions
• Local Graphics Parameters
  • Heads
  • Display Selection
• TroubleShooting
• Graphics Configuration Examples

As discussed in Szygy 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:

• headmounted (yes or no) specifies whether the screen's placement (position and orientation) are fixed in the virtual world or relative to the midpoint of the viewer's eyes.
• tile: If you have a number of screens arranged as a video wall, you can specify them as a single Syzygy screen (having the overall dimensions of the wall), in which case this parameter specifies which tile the current screen is. (tilex/tiley/numtilesx/numtilesy). tilex and tiley are zero-based. For example, if this screen is in the middle row, 3rd position from the left of 4x3 wall, then tilex=2,numtilesx=4,tiley=1,numtilesy=3.
• usefixedhead (allow, always, or ignore). For multi-person demos in a CAVE, it is preferable to specify a fixed rendering position rather than to render for the position specified by the single operator's head-tracking sensor. This parameter specifies whether or not this screen should honor this fixed-head mode.
• fixedheadpos is a 3-element vector specifying the rendering position for the current screen for the aforementioned fixed-head mode. The orientation is automatically chosen to face the center of each screen, with the final degree of freedom specified by...
• fixedheadupangle: For vertical screens you generally want the head to be assumed to be upright in fixed-head mode (fixedheadupangle=0). For horizontal screens (i.e. a ceiling or floor) it can be trickier. This parameter allows you to adjust the direction the top of the head is assumed to point in fixed-head mode for the current screen. Note that, for non-headmounted screens, the head orientation only affects the relative displacement between the left- and right-eye images, so if your setup is not stereoscopic this parameter is irrelevant to you.
  Here's how to specify a screen in a parameter file. The structure is XML. For each named global parameter, you create a <param> record with <name> and <value> sub-records.

    <param>
      <name>screen_default</name>
      <value>
        <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>
      </value>
    </param>
  

  This defines a head-mounted screen 8x6 feet in size and 3 feet in front of the viewer. Generally speaking, you want a head-mounted screen to ignore fixed-head mode (it's intended for world-fixed screens as in a CAVE), so we set the usefixedhead parameter accordingly. The two following parameters are of course irrelevant in this case, I've just included them for completeness, and the tile parameter is set to the default value.

Cameras

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

• The default is the Syzygy VR camera. This uses a screen object (see above) and a head object to compute the frustum according to the laws of perspective projection. The head parameters are local parameters, so they are specified separately. The VR camera has no additional parameters.

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:

• A Perspective camera generates a similar frustum to a VR camera. In both cases, objects appear smaller the farther they are from the viewer. BugFix: prior to Syzygy 1.0.1, requesting a perspective camera would actually get you an ortho one.
• An Ortho camera creates an orthographic projection, in which an object appears the same size regardless of distance.

Both are specified with the following two parameters:

• frustum (left/right/top/bottom/near/far) specifies the boundaries of the viewing frustum. In the case of a perspective camera, left/right/top/bottom specifies the dimensions of the near edge of the frustum; an ortho camera's frustum is rectangular, so front and back edges are the same size.
• lookat (viewx/viewy/viewz/lookatx/lookaty/lookatz/upx/upy/upz). The first three specify the viewing position, the second three a point looked at, the final three the 'up' direction.
  Here are examples. The first one's pretty boring, it's a VR camera using the screen object from the preceding example.

    <param>
      <name>camera_default</name>
      <value>
        <szg_camera type="vr">
          <szg_screen usenamed = "screen_default" />
        </szg_camera>
      </value>
    </param>
  

  Here's a perspective camera with the same field of view:

    <param>
      <name>camera_perspective</name>
      <value>
        <szg_camera type="perspective">
          <frustum left="-4." right="4." bottom="-3." top="3." near="3." far="1000000." />
          <lookat viewx="0." viewy="5." viewz="0." lookatx="0." lookaty="5." lookatz="-1." upx="0." upy="1." upz="0." />
        </szg_camera>
      </value>
    </param>
  

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:

• coords (left/bottom/width/height): numbers between 0. and 1., specifying the location of the viewport within a window.
• depthclear (value=yes/no): whether or not the Z-buffer is cleared before rendering into this viewport. Default is no; the Z-buffer for the entire window is cleared at the beginning of each frame. Setting this is necessary for e.g. anaglyph mode.
• colormask (R/G/B/A, all yes/no): which color channels to draw into.
• eyesign (value=a float): Whether this viewport is a right(1.)- or left(-1.)-eye view, or for monocular viewing (0.). This information is used by a Syzygy VR camera (see Cameras above) to modify its frustum appropriately for stereoscopic viewing. The Perspective and Ortho cameras ignore the eye sign.
• ogldrawbuf: many possible values, find "Selecting Color Buffers for Writing" in Chapter 10 of the OpenGL Programming Guide. If in doubt, choose 'GL_BACK_LEFT'. 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 predefined viewing modes are:
   • normal: A single viewport that fills the window.
   • 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/]. 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.
   • 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.
     Here's the simplest possible viewport list: a pre-defined viewing mode and a camera.

       <param>
       <name>vplist_default</name>
       <value>
         <szg_viewport_list viewmode="walleyed">
           <szg_camera usenamed="camera_default" />
         </szg_viewport_list>
       </value>
       </param>
     

     Here's a 'custom' viewport list containing a single viewport: (NOTE: replace this with a more complex and interesting example.)

       <param>
       <name>win_default</name>
       <value>
         <szg_viewport_list viewmode="custom">
           <szg_viewport usenamed="viewport_default" />
         </szg_viewport_list>
       </value>
       </param>
     

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:

• size (width/height in pixels).
• position (x/y in pixels from upper-left screen corner).
• fullscreen (yes/no). If yes, the window is zoomed or maximized after being created.
• decorate (yes/no). Whether or not the window has a frame, close widget, etc.
• stereo (yes/no). This refers to active stereo, in which your scene is rendered in alternation for the left and right eyes and you view it through LCD shutter glasses that are synchronized with the vertical refresh of the graphics card (see e.g. the Barco Active Stereo page). If you set this to 'yes' and your graphics card does not support active stereo, applications will crash. Note that this setting is independent of the stereo viewing modes described above. For normal active stereo, you would set stereo to 'yes' and viewmode to 'normal'.
• zorder (normal/top/topmost). Whether or not your window tries to stay on top of other windows. 'topmost' is stronger than 'top', in that 'top' only tries to stay above other 'normal' windows, but 'special' windows (particularly on Win32) might cover it. 'topmost' tries to stay on top of everything.
• bpp. Color depth (bits/pixel). MS Windows only, I think.
• title. Appears in window title bar, task bar, etc.
• xdisplay. Only meaningful on Unix sytems (Linux, Mac, Irix). Gives the name of the X display where the window should appear. Default is ":0.0".
• cursor (arrow/none/help/wait). The appearance of the mouse cursor when it's inside the window.
  Here's a definition for a fullscreen window:

    <param>
    <name>win_default</name>
    <value>
      <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 usenamed="vplist_default" />
      </szg_window>
    </value>
    </param>
  

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:

• framelock (wildcat/none): specifies whether the display supports hardware gen-locking, currently only 3D Labs Wildcat genlocked cards are supported.
• threaded (yes/no): In a multi-window display, are the windows rendered by separate program threads.
  Not much to it:

    <param>
    <name>display_default</name>
    <value>
      <szg_display framelock="none" threaded="no">
        <szg_window usenamed="win_default" />
      </szg_display>
    </value>
    </param>
  

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 Distributed OS for a definition of these terms.

A head has the following parameters:

• eye_spacing: The inter-ocular separation in feet. Defaults to 0.2 (about 6.1 cm.), which is just a bit below the average for the adult population.
• eye_direction: A unit vector specifying the direction from the midpoint of the eyes to the right eye as measured in the coordinate system defined by the head-tracking sensor. Three-element vectors are represented in the parameter database as '/'-delimited strings of numbers. eye_direction defaults to 1/0/0, i.e. the positive X direction.
• mid_eye_offset: A three-element vector specifying the position of the midpoint of the eyes in the head-tracking sensor coordinate system.
• fixed_head_mode: As discussed in the section on screens, Syzygy supports a fixed-head rendering mode that is preferable for multi-person demos in a CAVE or other fixed-screen environment. This variable (a boolean, i.e. one of yes/no/true/false) is the switch that puts a program in that mode. It can be overridden for an individual screen object by the appropriate choice of the usefixedhead parameter.

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

• The distance between the eyes is 0.2 feet.
• The unit vector from the midpoint of the eyes towards the right eye in the head tracker coordinate system is (x=1,y=0,z=0).
• The offset in feet to the midpoint of the eyes in the tracker coordinate system (i.e. with respect to the head-tracking sensor) is (x=0.29,y=0,z=0).
• Fixed-head mode is turned off. Fixed-head mode is a special viewing mode intended for group demos. Instead of rendering the virtual world for the head position specified by the tracker, each computer renders it for a specified head position and orientation. See the Screens section.

      Machine SZG_HEAD eye_spacing 0.2
      Machine SZG_HEAD eye_direction 1/0/0
      Machine SZG_HEAD mid_eye_offset 0.29/0/0
      Machine SZG_HEAD fixed_head_mode false
  

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:

• Defining a Virtual Cube in a Single Window (Using Viewports)
• Passive Stereo
• Easy Demo Passive Stereo Display in Standalone Mode
• Fixed-Screen Virtual Environments
• Head-Mounted Displays
• Multiple Screens on a Single Computer

[Schedule] [Labs] [Beckman Meeting Rooms] [Equipment] [Projects] [CUBE Projects] [Syzygy] [VSS] [People] [Events] [Publications]