next_inactive up previous

SoftGenLock Manual:
Software Active Stereo and Genlock for Linux



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: 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 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 :

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 ( and 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


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.


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 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 ( 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 ( 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


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


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 :

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.


It is important to identify each machine according to its role in the parallel cable : 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 : 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 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.

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

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

next_inactive up previous
Bruno Raffin 2002-10-31