SoftGenLock Manual:
Software Active Stereo and Genlock for Linux

netjuggler.sourceforge.net

Contents

• Introduction
• Software and Hardware Requirements
  • X and 3D application setup
  • Real Time Linux
  • PC to Shutter Glasses Cable
  • Parallel port
  • Synchronization network
  
  
• NVIDIA Graphics cards
  • Ge force / quadro 4
  
  
• Compiling SoftGenLock
  • Makefile
  • sgen_param.h
  • Ready ?
  
  
• Running SoftGenLock
  • First Test
  • Single Display
  • Multiple Displays
  • SoftGenLock Refuse to Start
  • Controlling Genlock Quality
  • Launch the 3D Application First
  
  
• Installing SoftGenLock
• SoftGenLock without Real Time System
• SoftGenLock Directory Organization
• The SoftGenLock Team
• Problems and Feedback
• About this document ...

Introduction

Active stereo rendering requires multi display systems to have their different video outputs genlocked, i.e. to have their different video retrace signals synchronized. Active stereo also requires quad buffering and left/right eye buffer flipping synchronized with the video retrace. Except for some high end cards, off-the-shelf graphics cards do not support genlock. Especially for Linux, today's graphics card drivers generally do not enable quad buffer page flipped stereo. The SoftGenLock library provides a software solution to genlock and active stereo that does not require specific hardware or access to the driver source code. SoftGenLock can be used for:

• active stereo viewing on a single display,
• genlocking several displays driven by different computers,
• active stereo viewing on a multi display system driven by several computers (a Cave like environment driven by a PC cluster for example).

SoftGenLock is currently available for Linux. There is no plan to port SoftGenLock for Windows now. It should work with any graphics cards having VGA registers. It was successfully tested with NVIDIA and Voodoo cards. SoftGenLock was originally designed to be used with Net Juggler, a software harness to run VR Juggler on clusters (See netjuggler.sourceforge.net). But it is totally independent from Net Juggler and thus it should be possible to associated it with any 3D environment. How SoftGenLock basically works :

• It uses the VGA registers to flip the image displayed (right/left eye).
• It uses the VGA registers to slow down the retrace by adding extra invisible pixels. This is the way we achieve genlocking.
• It uses the parallel port or the VGA port for NIVIDA card to send the sync signal to the glasses.
• It uses the parallel port to execute a synchronization barrier to measure how late ("out of genlock") a machine is. Based on this data a machine can decide to slow down its video retrace. When you launch SoftGenLock you see a black line going from the bottom to the top of the screen: this is the convergence phase of the algorithm.
• It uses the VGA registers to know when the vertical no retrace occurs.
• It runs as a real time kernel module so it can wake up right when the vertical no retrace occurs (in fact a fixed number of micro seconds before the end of the vertical no retrace). Such precision can only be acheived with a hard real time system. SoftGenLock supports two of them : RT Linux and RTAI.

Software and Hardware Requirements

The main components required to install and run SoftGenLock are, of course, shutter glasses (Elsa Revelator 3D or StereoGraphics CrystalEyes glasses for example), but also a real time Linux kernel and a fast synchronization network.

X and 3D application setup

SoftGenLock switches between the left and right eye images displayed side by side on a virtual display twice as large as the actual display resolution. If your actual display resolution is 1024x768, then edit the /etc/X11/XF86Config-4 file and add : Virtual 2048 768 in the Screen section. Launch X. Configure the 3D application to draw the 1024x768 left eye image from the coordinate (0,0) of the virtual display and the 1024x768 right eye image from the (1024,0) coordinate. Instead of modifying XF86Config-4, you can copy it in /etc/X11/XF86Config-4.stereo and apply the required modifications to this file. To force XFree to use the stereo enabled configuration file uses : startx - -xf86config XF86Config-4.stereo

Real Time Linux

SoftGenLock must be triggered at regular time intervals (each video retrace) and its execution should not be interrupted. This is achieved using a real time Linux kernel. SoftGenLock supports RT Linux (fsmlabs.com) and RTAI (www.aero.polimi.it/projects/rtai/). Both systems requires to patch and recompile the Linux kernel.

RT Linux

Add in the section of the patched kernel for RTLINUX in /etc/lilo.conf file the line : append="nmi_watchdog=0" and run lilo to update your system. This option is forwarded to the kernel to disable NMI watchdogs. If activated these watchdogs can crash your system when SoftGenLock is running. To start RT Linux (you must be super user) once the machine booted with the patched kernel (check with uname -a): rtlinux start To stop RT Linux : rtlinux stop

RTAI

Add in the section of the patched kernel for RTAI in /etc/lilo.conf file the line : append="nmi_watchdog=0" To start RTAI (you must be super user) once the machine booted with the patched kernel (check with uname -a): ldmod To stop RTAI : remmod

PC to Shutter Glasses Cable

SoftGenLock supports two ways to send the synchronization signal to shutter glasses

NVIDIA graphics cards

SoftGenLock is able to send the sync signal on the pin 12 of the VGA connector when using NVIDIA cards. Shutter glasses, like Elsa Revelator 3D or StereoGraphics CrystalEyes glasses for example, are sold with a special connector to forward this signal to the shutter glasses.

Parallel port

On other way is to send the synchronization signal to shutter glasses through the parallel port. Such cable is not available on the market so you have to prepare one by your own. We propose two solutions depending if you use SoftGenLock with a single or multiple displays. We assume you have shutter glasses with a mini-din 3 VESA connector. If you use SoftGenLock with a single display only, build a cable having on one side a male parallel port connector and a mini-din 3 connector on the other side. Connect the pin 3 (stereo sync signal), 4 (power) and 18 (ground) of the parallel connector with the pins 1,3,2 respectively of the mini-din 3 connector (Table ).

Table 1: The male parallel port connector and the female mini-din 3 connector.

If you use SoftGenLock with multiple displays refer to section 2.5.1.

Synchronization network

If you only want to use SoftGenLock with a single display skip this section. SoftGenLock algorithm uses a fast synchronization barrier to genlock the video signals. We propose two solutions using parallel port based synchronization networks. Note that because SoftGenLock is run as a real time kernel module, it can only access a very limited set of devices. In particular, it cannot access a classical network cards (Ethernet or Myrinet for example). Thus, even if such networks could be fast enough, their use is not possible with SoftGenLock.

ParaCable

This is a simple solution that does not require any skill other than thread solding. The network is a modified parallel cable (ParaCable) with one master and 5 slaves. It is also possible to integrate a mini-din 3 in the design to send the sync signal to the shutter glasses. Here is the wiring diagram of this cable :

Table 2: The ParaCable wiring diagram

Master Node	Slave 1	Slave 2	Slave 3	Slave4	Slave 5
Pin 2	Pin 15
Pin 3		Pin 15
Pin 4			Pin 15
Pin 5				Pin 15
Pin 6					Pin 15
Pin 15	Pin 2
Pin 13		Pin 2
Pin 12			Pin 2
Pin 10				Pin 2
Pin 11					Pin 2
Pin 18	Pin 25
Pin 19		Pin 25
Pin 20			Pin 25
Pin 21				Pin 25
Pin 22					Pin 25

Mini Din 3	Slave 1
Pin 1	Pin 3
Pin 3	Pin 4
Pin 2	Pin 18

The pins 2 to 6 correspond to the bit 0 to 4 of the data register of the parallel port (output bits), while the pins 15,13,12,10,11 correspond to the bits 3,4,5,6 and 7 (inverted) of the status register (input bits). For more details about the parallel port see www.beyondlogic.org/spp/parallel.htm. One possible design consists in pluging 6 female DB25 connectors and one mini-din 3 female connector on one board (Fig 1). Connect them as described in the diagram (table ). Each PC connects on the board with a classical parallel port cable (IEEE 1284) with 2 DB5 male connectors. The IR emmiter of the shutter glasses connect on the mini-din.

Figure 1: A board for the SoftGenlock synchronisation network. Six DB35 connector are soldered on a copper board. The master connector is on the right hand side. Below the first slave (left-hand side), we can distinguish the mini-din 3 connector for the IR emmiter of the shutter glasses.

With such a network, it is possible to synchronise the 6 machines in about 6 $\mu$s. If you want to genlock only 2 machines and do not need the mini-din 3 connector on the cable you can use a simple laplink parallel cable. It is probably not too difficult to connect more than 6 PCs using several ParaCable but we did not explore in detail such a solution.

TTL_PAPERS Synchronization Network

A highly scalable synchronization network is obtained with a TTL_PAPERS like synchronization network ( www.aggregate.org). PCs are connected to a PAPERS box through parallel port cables. A PAPERS box can typically accept up to 4 PCs. Several boxes can be tree assembled to connect an arbitrary large number of nodes. A 4 PC synchronization takes only about 4 $\mu$s. Each extra tree level adds about a hundred of nano-seconds. TTL_PAPERS like networks are not commercially available. You thus have to build your own. Even if it is not really difficult you should better have some skills in electronics. Reserve this solution if scalability is critical for your project.

NVIDIA Graphics cards

To enable SoftGenLock with NVIDIA graphics cards page flipping must be disabled. Edit the /etc/X11/XF86Config-4 file (or XF86Config-4.stereo) and add : Option "PageFlip" "0" in the Screen section of the nv driver.

Ge force / quadro 4

The Ge force/ quadro 4 cards have 2 video outputs. Softgenlock works properly with only one of these output (the addresses of the vga registers of the other output are not available). On the Ge force 4 SoftGenLock requires to use the DVI ouptut.

Compiling SoftGenLock

Download the SoftGenLock distribution (netjuggler.sourceforge.net). unzip and untar it:

gunzip softgenlock-version.tar.gz
tar -xf softgenlock-version.tar

The two main files you may have to edit to customize SoftGenLock are Makefile and sgen_param.h

Makefile

SoftGenLock configuration is controled by commenting in or out the following variables in the Makefile :

• USE_FLIP: Enable left/right image flipping
• USE_GLASSES: Enable Stereo sync signal generation. By default the signal is sent to the parallel port.
• USE_NVIDIA: Send the stereo sync signal to the VGA DCC bit for NVIDIA graphics cards.
• USE_GENLOCK: Enable genlock.
• USE_MPI: Use a MPI synchronization barrier. for genlocking. Cannot be used with a Real Time system.
• USE_PARBOX: Use a TTL_PAPERS like synchronization network.
• USE_PARCABLE: Use the modified parallel cable ParaCable.
• USE_RTLINUX: Use RT Linux (by default SoftGenLock is compiled as a classical linux user proram)
• RTLDIR=/usr/rtlinux: Installation directory of RT Linux.
• USE_RTAI: Use RTAI (by default SoftGenLock is compiled as a classical linux user proram)
• TOPDIR=/usr/src/rtai: Installation directory of RTAI.
• LINUXDIR=/usr/src/linux: Directory of the linux kernel sources patched for RTAI.
• DEBUG: Verbose SoftGenLock for debugging.

sgen_param.h

SoftGenLock adjusts automatically most of the parameters required for the algorithm. However some still need manual tunning. Only 3 parameters may require adjustments for a normal use of SoftGenLock: HSIZE, GLASS_LATENCY and GENLOCK :

• HSIZE (1024 * 2): Horizontal resolution. If display resolution is 1024*768*32 then HSIZE must be set to 1024 * 4 (32 bits == 4 bytes).
• STARTWORK_BEFORE_VNEND: How long before VNEND (vertical no retrace end) occur SoftGenLock should start to work.
• WRITE_REGISTERS_BEFORE_VNEND: How long before VNEND SoftGenLock should write the VGA card registers.
• GLASS_LATENCY: Shutter glasses latency (time required to flip the shutters). If the top lines of your display are kind of blurry there is good chance this value is not high enough.
• GENLOCK: Minimum time required to have the genlocking algorithm working properly. GENLOCK should be long enough so SoftGenLock has some time left before VNEND to detect when small modifications of the video signal (not detected by the screen) are required. If your image seems unstable there is a chance this value is not large enough.
• GENLOCK_TOLERANCE: How accurate genlocking should be. If you put here 10 $\mu s$, SoftGenLock will make everything possible so that all video retraces start in a range of 10 $\mu s$.

Ready ?

Did you modify the Makefile ? Did you adjust the value of HSIZE ? Did you boot your system with a linux kernel patched for RTAI or RTLinux (check with uname -a) ? Ok you can compile SoftGenLock :

make all

Running SoftGenLock

Did you started the real time system ? Did you plug your glasses and the sync network , Did you launch X with the double horizontal resolution ? Are you super user ? Ok you can launch SoftGenLock.

First Test

For a first test put an Xterm window on the left side of the virtual screen and nothing on the right side. Start SoftGenLock and put the shutter glasses. Close the left eye. You should not see the Xterm window. Congratulation, you successfully installed SoftGenLock.

Single Display

You just have to load the SoftGenLock module : insmod softgenlock.o To stop SoftGenLock unload the module: rmmod softgenlock

Multiple Displays

TTL_PAPERS network

On each machine load the SoftGenLock module: insmod softgenlock.o To stop SoftGenLock unload the module on each machine. rmmod softgenlock Note that once a machine stopped SoftGenLock the other machines will wait for a while (few seconds) and stop SoftGenLock, but the module is still loaded.

ParaCable

It is important to identify each machine according to its role in the parallel cable :

• Master : node 0
• Slave 1 : node 1
• Slave 2 : node 2
• Slave 3 : node 3
• Slave 4 : node 4
• Slave 5 : node 5

On each machine load the SoftGenLock module with the rank of the node and the total number of machine involved (counting the master). For exemple if you whant to use 3 machines load the module on the :

• master : insmod softgenlock.o size=3 rank=0
• slave 1 : insmod softgenlock.o size=3 rank=1
• slave 2: insmod softgenlock.o size=3 rank=2

To stop SoftGenLock unload the module on each machine. rmmod softgenlock Note that once a machine stopped SoftGenLock the other machines will wait for a while (few seconds) and stop SoftGenLock, but the module is still loaded.

SoftGenLock Refuse to Start

Stereo is not activated right after SoftGenLock is started, because SoftGenLock first takes time to measure some internal parameteres and sync itself with the vertical retrace. This step may take few seconds. In the case you are using muplitple displays it may stop itself during or after this calibration step. This is a side-effect of a watchdog machanism we integrated in SoftGenLock to avoid locking the kernel while waiting in an endless synchronisation barrier. If you are experiencing this problem increase the value of the variable SGEN_COMM_EXIT_BARRIER_TIME in the Comm/comm.h file.

Controlling Genlock Quality

Once SoftGenLock is working, wear the shutter glasses. If a black line appears on one screen the genlock is not perfect yet. But it may take some time for SoftGenLock to converge to a genlocked state. As SoftGenLock progress, you should see this black line progressively going up or down the screen and them disapear. If the top lines of your display(s) are kind of blurry there is good chance the latency of your glasses is higher than what you put in the sgen_param.h file. Increase the value of GLASS_LATENCY. If you image seems unstable (image flipping occurs after the video retrace started) try to increase the value of GENLOCK in sgen_param.h.

Launch the 3D Application First

SoftGenLock must be lauched after the 3D application. Doing the opposite, SoftGenLock may fail to properly display in stereo or genlock the displays. When launched, SoftGenLock first starts to measure some parameters of the video signal (retrace time for exemple). These parameteres may change when you start X or a 3D appication. SoftGenLock is not (yet) able to detect these changes and recalibrate itself.

Installing SoftGenLock

We detail in the following how to install the SoftGenLock module with the other Linux kernel modules. This install eases starting/stopping SoftGenLock. For each machine edit the /etc/modules.conf file and add the following line with the correct values for the size and rank options : options softgenlock size=3 rank=1 Copy softgenlock.o into the /lib/modules/<kernel-version>/misc directory cp softgenlock.o /lib/modules/<kernel-version>/misc/.
Execute the thedepmod command. This command identifies all other modules required to load softgenlock (in particular the modules of the real time system). Now to start SoftGenLock with the correct options and the real time system you just have to tape in: modprobe softgenlock
To stop SoftGenLock and to unload all modules that become useless (the modules of the real time system): modprobe -r softgenlock

SoftGenLock without Real Time System

Up to now we did not speak about using SoftGenLock without a real time kernel. This possible. You just have to select the good configuration in your Makefile. But because strong restrictions apply to this configuration we reserve it for a first test only. When compiling SoftGenLock without a real time system, SoftGenLock is a simple user program. Linux does not guarantee SoftGenLock has access to the CPU when required, i.e. during the vertical retrace, so flickers may affect the stereo effect especially if the CPU has other programs to run. In this case to run SoftGenLock just launch the program (you need to be super user only if you use the parallel port):

• softgenlock for a single display
• softgenlock on each machine for multiple displays and a TTL_PAPERS network
• softgenlock size=... rank=... on each machine for multiple displays and ParaCable.
• mpirun -np ... softgenlock on one machine for multiple displays and MPI. NOTE: we do not support MPI any more. This solution requires MPI to be installed. Note that MPI cannot be used with a real time kernel (real time modules have very limited I/O accesses).

SoftGenLock Directory Organization

Each component of SoftGenLock corresponds to a directory and each subdirectory to an implementation. Place your custom code on a subdirectory and reference it in the Makefile, and it should work... The required functions to implement are documented in the .h header file in each directory.

• Algorithm: main SoftGenLock algorithm. This should not need modifications other than bug correction or performance improvements.
• Comm: communication system
  • Comm/ParaBox: parallel port synchronization network
  • Comm/ParaCable: parallel cable
  • Comm/MPI: use MPI_BARRIER for synchronization.
• Doc: Documentation
• Glasses: stereo sync signal for shutter glasses
  • Glasses/DDC: SVGA DCC SDA pin 12 connector (using functions in Graph/VGA).
  • Glasses/ParallelPort: parallel port access.
• Graph: graphics card
  • Graph/VGA: vga compatible cards (with NVIDIA extension support).
• Main: main program
  • Main/RTAI: RTAI module
  • Main/RTLinux: RTLinux module
  • Main/Standard: User level program
• MyTime: timer
  • MyTime/i586: i586 cycle counter register.
  • MyTime/None: no timer (this should not be used).
  • MyTime/Posix: standard gettimeofday unix function.
  • MyTime/RTLINUX: RT Linux timer.
  • MyTime/RTAI: RTAI Timer.
• ParallelPort: parallel port access
  • ParallelPort/Kernel: IO perms for kernel level programs
  • ParallelPort/User: IO perms for user level programs

The SoftGenLock Team

The SoftGenLock team includes Jérémie Allard (the main programmer), Valérie Gouranton, Loïck Lecointre, Sébastien Limet, Souley Madougou, Emmanuel Melin, Olivier Riffaut, Laboratoire d'Informatique Fondamentale d'Orléans, France, and Bruno Raffin, Laboratoire Informatique et Distribution, Grenoble, France.

Problems and Feedback

For problems and feedbacks use the SoftGenLock mailing lists (see netjuggler.sourceforge.net)

About this document ...

SoftGenLock Manual:
Software Active Stereo and Genlock for Linux

This document was generated using the LaTeX2HTML translator Version 2K.1beta (1.62)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 SoftGenLock.tex

The translation was initiated by Bruno Raffin on 2002-10-31