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 http://www.gnu.org/copyleft/gpl.html.
Users support: email@example.com
(please report your success/failures)
Developers contact: firstname.lastname@example.org
Anything else: Jeremie.Allard@imag.fr
This release is an alpha. It is not fully tested. Be careful when testing kernel-mode and specially real-time mode operations.
BUGFIX: Pixel-clock adjustment Improved README file
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:
Depending of which functionnalities you want to use, you will need:
The latest release is available at http://sourceforge.net/project/showfiles.php?group_id=30385.
You can also download the bleeding-edge (but often unstable) source code:
cvs -d:pserver:email@example.com:/cvsroot/softgenlock login cvs -z3 -d:pserver:firstname.lastname@example.org:/cvsroot/softgenlock 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:
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...)
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 findgraph.sh 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:
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
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.
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).