SoftGenLock 2.0-alpha

Multi-display Software Genlock and Page Flipped Stereo for Linux

SoftGenLock 2.0a2, Copyright (C) 2003-2004 LIFO, Universite d'Orleans
SoftGenLock comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions, for details go to

Users support:
(please report your success/failures)
Developers contact:
Anything else:


This release is an alpha. It is not fully tested. Be careful when testing kernel-mode and specially real-time mode operations.


SoftGenLock 2.0a2

  BUGFIX: Pixel-clock adjustment
  Improved README file

SoftGenLock 2.0a1

  Initial Release


SoftGenLock provides a software solution to genlock and active stereo. It does not require specific hardware or access to the driver source code.

SoftGenLock can be used for:


SoftGenLock 2 is a nearly full rewrite of SoftGenLock. The goal is to have a much more flexible system in order to support several approaches for genlocking or stereo. SoftGenLock 1.0 supported only one way to access the graphic card (by using vga-compatible registers). This release support additionnal possibilities, currently only supported on NVIDIA graphics cards:

  1. Accessing geforce-specific registers: in particular the register controlling the pixel-clock
  2. Accessing the vga CRTC registers for both video heads An important advantage of the first method is that there is no concurrency issues anymore between softgenlock and the graphics card driver, so hopefully no more corruptions and random crashes.


Depending of which functionnalities you want to use, you will need:


The latest release is available at
You can also download the bleeding-edge (but often unstable) source code:

  cvs login
  cvs -z3 co softgenlock2

To compile you must use the command make in softgenlock2 directory with the following options:

By default make builds everything.

For kernel and real-time modules you must compile using the kernel version you want to use with softgenlock. Linux kernel sources must be installed.

If softgenlock doesn't find rtai files, you need to add an argument RTAI=dir, where dir is the directory where you installed RTAI.


For user-mode program, no installation is necessary. However you can copy the bin/sgl_user program to any directory you like.

For kernel modules, use make install to install both modules into /lib/modules, or just make install-kernel without RTAI. Note that you must be logged as root.


It is recommended to use the user-mode program for any first-time test. Once the compilation is done, this program is the file bin/sgl_user. This is a console program. It will reads the configurations commands from its input (see next section). A blank line is interpreted as the end of the configuration. Then the genlocking/stereo algorithm is started. Use CTRL+C to stop the program. Command-line options are:

You can use "make test" for a quick test. Your screen should flicker. Note that you must have root access to run this test. If an error is returned please refer to next section for configuring scripts/graph.

The kernel modules can be launched by using the insmod or modprobe command:

  insmod ./bin/sgl_kernel.o # For kernel mode module
  modprobe sgl_rtai         # For real-time mode after installation

Once the module is started a /dev/softgenlock device file is created (this requires devfs to be activated in the kernel). To view the messages generated by softgenlock use:

  cat /dev/softgenlock

Issuing commands is done by writing to this file:

  cat _scriptfiles >/dev/softgenlock # Using a file to send commands
  cat >/dev/softgenlock # Forwarding keyboard inputs.

A blank line is interpreted as the end of the configuration. "1" starts the algorithm. "0" stops it.

To remove the module from the kernel, first kill all programs accessing /dev/softgenlock, then use the rmmod command:

  rmmod sgl_kernel
  rmmod sgl_rtai    # for rtai (surprisingly...)


  1. If you set access rights to the /dev/softgenlock file so that non-root users can read/write it, then it is not necessary to be root to use softgenlock :-).
  2. The module is inactive if no commands are issued. It is possible to load it during boot or automatically using the /etc/modules.conf file


SoftGenLock is based on a sequential tasks loop model. The user specify which tasks are required to run. Then the system schedule theses tasks depending on the running environment (user-mode, kernel-mode, real-time).

Several scripts are distributed with SoftGenLock in the directory scripts. The scripts/graph file should be customized depending on your hardware. It defaults to graph=nv which should work for any NVIDIA card. Replace with graph=vga for vga-compatible access or change the other parameters for other option (in particular video head CRT/DVI to use with the nv_head parameter).

When launching sgl_user if an error "SYS[ERROR]: Error opening file "/proc/bus/pci/01/00.0"" is returned you must specify the graphic card's PCI address using the nv_device parameter in scripts/graph. You can use the shell script to find the right address.

The other scripts each specify different functionnalities. Please see each script's header for more details, or refers to the next section for a few usage cases.

To test a script (stereo1 for example), you can use the following command:

  cat scripts/graph scripts/stereo1 | ./bin/sgl_user -rtc -fifo

The script syntax is line-based. Each line can be:

  1. A system parameter: "parameter = value"
  2. A new task: "task_name"
  3. A parameter for the current task: "whitespace parameter = value"
  4. A comment starting with //

An empty line marks the end of the script

You can (and you are encouraged to) customize each script depending on your setup.
When using keyboard input, SoftGenLock will tell you wich tasks are available, and which parameters can be set, by issuing wrong names in the commands. For example:

Once a script is known to work on your setup, you can use it is kernel/real-time mode by using:

  cat scripts/graph scripts/stereo1 >/dev/softgenlock
  echo 1 >/dev/softgenlock # GO!
  cat /dev/softgenlock # read the outputs
  echo 0 >/dev/softgenlock # STOP

Single-display Page-flipped Stereo

A simple stereo mode is obtained using the script scripts/stereo1. You must first configure the X Server to have a virtual screen 2 times as wide as you screen. scripts/graph must be customized to your setup (see previous section). To script scripts/stereo1 can be customized as follow:

You can test your setup by forwarding the scripts/graph and scripts/stereo1 to bin/sgl_user:

  cat scripts/graph scripts/stereo1 | bin/sgl_user

Once this setup is working you can comment-out the view task (debugging outputs) and use the (real-time) kernel version for more reliable operations.

Genlocked Multi-display Page-flipped Stereo

Genlocking is based on a master node sending a reference signal on the parallel port and several independant slaves nodes reading this signal and synchronizing their video signal with it. The glasses are connected to one of the nodes. The default scripts assume that the glasses are connected using pin 3 for alimentation and that the slaves nodes received the master signal thru pin 15. Please customize the tasks parameters for other setups (refer to previous section). Depending wether you glasses are connected to the master node or not, you have to use either scripts/master1 or scripts/master1-glasses on the master node:

  cat scripts/graph scripts/master1 | bin/sgl_user

Once the master node is running you can launch the slaves nodes. There are two algorithms available for slaves node genlocking: pixel-count based (as in SoftGenLock 1.0) and pixel-clock based (only for NVIDIA cards). The new pixel-clock based algorithm should be more reliable and depending on your equipement produce less flickers. Please use either scripts/slave1-clock or scripts/slave1-count to launch either method:

  cat scripts/graph scripts/slave1-clock | bin/sgl_user

Once this setup is working you can comment-out the view task (debugging outputs) and use the (real-time) kernel version for more reliable operations. If this is not the case please try simpler scripts (scripts/stereo1 to test page-flipping, scripts/testread to see the signals received on the parallel port).

Known bugs