MATRIX VISION - mvTITAN Technical Documentation
Quickstart

Hardware installation

Attention
"Electro Static Discharge (ESD)"

Please take all proper Electro Static Discharge (ESD) precautions during the installation of your new hardware!

Before starting the installation, turn off your computer and all peripheral devices. Disconnect the computer from the power supply and all necessary components.

Note
To avoid doing damage to the hardware, discharge yourself of static charge by touching e.g. the casing. Beware of touching contacts of the frame grabber or of the computer.
  • Select a free busmaster slot (PCI). Remove the slot's cover at the back of the computer and keep the screw.
  • Carefully insert the board into the slot by holding the board at the top and gently pushing both ends into the slot at the same time. Press onto the upper edge of the board to make sure it is seated in the slot firmly.
  • Do not force the board into the slot! You run the risk of bending the contacts. If the board does not fit easily, pull it back out, and try again.
  • Fasten the board's bracket at the back of the computer using the screws you saved from the shield.
  • Put the cover back on the computer and reconnect the peripheral devices.
  • Start the computer.

Windows

System Requirements

Currently supported Windows versions are:

  • Microsoft Windows 7 (32-bit, 64-bit) (requires min. 2 GB main memory)
  • Microsoft Windows 8.1 (32-bit, 64-bit) (requires min. 2 GB main memory)
Note
Working on Windows XP you must enable at least the following advanced user right when not working with an Administrator account: "Increase scheduling priority" (for the German version of Windows: "Anheben der Zeitplanungsprioritaet"). These settings can be made on Windows XP via 'Settings -> Control Panel -> Administrative Tools -> Local Security Policy -> Local Policies -> User Rights Assignment').

Consecutively the installation for Windows will be described. The description for the Linux installation can be found here: Linux .

Software installation

All necessary drivers for Windows and Linux are contained in the mvIMPACT CD-ROM or DVD-ROM. For newer driver versions we recommend to visit the MATRIX VISION website at www.matrix-vision.de, section Support/Download/Hardware.

After the Hardware installation the boot sequence shows "Found New Hardware" and starts the Windows Hardware Wizard. Closed this windows and insert the mvIMPACT CD-ROM or DVD-ROM into your drive and select "Driver installation ..." and the needed mvIMPACT Acquire driver (e.g. "mvTITAN / mvGAMMA").

Figure 1: Start window

After the click on the needed driver the installation process starts.

Figure 2: mvTITAN/mvGAMMA installer - Start window

Select the folder, where you want to install the software.

Figure 3: mvTITAN/mvGAMMA installer - Select folder

Select the features, which you want to install. Following features exist:

  • "Base Libraries"
    This feature contains all necessary files for property handling and display. Therefore, it is not selectable.
  • "mvTITAN/mvGAMMA driver"
    This is also not selectable.
  • "Tools"
    This feature contains tools for the frame grabber (e.g. to acquire images (wxPropView)).
  • "mvIMPACT acquire API"
    The "mvIMPACT acquire API" contains the header for own programming. Additionally you can choose the examples, which installs the sources of wxPropView, mvIPConfigure and various small examples. The project files shipped with the examples have been generated with Visual Studio 2013. However projects and makefiles for other compilers can be generated using CMake fairly easy. See CMake section in the C++ manual for additional details.
  • "Documentation"
    This will install this manual as single HTML help file (.chm).
Figure 4: mvTITAN/mvGAMMA installer - Select features

Confirm the installation by clicking "Next".

Figure 5: mvTITAN/mvGAMMA installer - Confirm installation

The installation process copies the files to Windows. Then Windows shows a message to signal that this driver is not checked through Microsoft. This is only an attempt to make insecure and it is recommended to ignore it.

Press "Continue Anyway" and finish the driver installation.

Figure 6: mvTITAN/mvGAMMA installer - Windows logo testing

Short after this a dialog box for the input of the DMA buffer appears. The frame grabber works with another kind of DMA buffer, which is applied and released on run-time. In this case the input of the size happens via the configuration file (*.ini).

Figure 7: mvTITAN/mvGAMMA installer - Setup of the DMA buffer

The DMA buffer displays a reserved area in the memory. The frame grabber saves all images in this memory. From there the images will be displayed and processed. The size of the DMA buffer is conformed with the size of min. one image. The size of one image can be calculated as follows: horizontal resolution and vertical resolution multiply by the necessary space of the pixel.

Memory requirements M = <horizontal resolution> * <vertical resolution> * <Bytes per pixel>
Horizontal resolution = 720
Vertical resolution = 576
Bytes per pixel = 4 (= 32 bits per pixel)
Memory requirements = 720 * 576 * 4 Bytes = 1658880 Bytes = 1.58 MByte

The minimum size of the DMA buffer amounts to 2 MB.

Note
mvIMPACT uses a double buffer method to acquire images. This means, that the image data is saved alternating between two memories in the DMA buffer. Thus, the minimum size of the DMA buffer is twice as big as the memory requirements of one image.

After the input of the necessary DMA buffer size, click on OK. Now, the installation process is finished.

Figure 8: mvTITAN/mvGAMMA installer - Installation complete

After this, you have to restart the system.

Figure 9: mvTITAN/mvGAMMA installer - Restart the system

After the restart, you can acquire images with the frame grabber. Simply start the application wxPropView (wxPropView.exe).

See also
wxPropView

Linux

The standard MATRIX VISION frame grabber drivers have been ported to Linux. A common code base ensures that the names and parameters of all the functions are identical to the Windows / DOS versions. This makes porting your existing Windows applications to Linux especially easy. We are constantly improving and updating so you should always take a look at our website for newer versions (http://www.matrix-vision.de). The driver consists of two parts:

  • A kernel module called matrixfg.o, sigma.o, xsigma.o or titan.o. (From Linux kernel 2.5 onwards these will be called matrixfg.ko, sigma.ko, xsigma.ko and titan.ko). These modules handle kernel mode memory and I/O access and/or interrupts.
  • A library which provides user programs with access to all the MATRIX VISION standard frame grabber functions as defined in the header file mv.h

System Requirements

Software requirements

  • Linux kernel 2.4.x or 2.6.x running on i386 CPU.
    Note
    It is possible that older kernels will also work.
    You will need to have support for kernel modules turned on in your kernel configuration. (This is the default for all major Linux distributions). For the shared versions of the library, the GNU C runtime library libc6 is required. All recent Linux distributions should have this (e.g. SuSE Linux 9.0, 9.1, 9.2). The libraries have been compiled using glibc 2.3.3. on a SuSE 9.0 installation. If you use an older version of glibc you may experience problems. The libraries have been compiled using gcc version 3.3.1 (SuSE Linux). Using a system based on gcc 2.x is not recommended and may not work correctly. For display functions: a framebuffer, the svga library or for X applications, a correctly installed X system. It is also possible to use a framebuffer device. Check your distribution for a package called svga (or similar) or download and compile the sources for this library if you are not using X and you wish to display images or use a framebuffer (e.g. vesafb, rivafb etc.). To compile the kernel modules you will need a correctly configured GNU compiler and at least the kernel header files and Makefiles installed. It is usually advisable to install all of the kernel sources. The kernel configuration should exactly match the kernel you are using. During installation the kernel modules will be compiled for your system using exactly the same configuration as for the kernel. If you have not compiled your own kernel you will probably have to install the source package for your kernel and retrieve the correct kernel configuration for the running kernel too. This is often stored as file in the /boot directory (Red Hat, Debian, Mandrake) or can be generated from /proc/config.gz in the case of SuSE or for 2.6.x kernels which have the appropriate kernel option turned on.

Hardware requirements

  • i386 compatible PC. (PowerPC versions of the software are currently being prepared.).

One of the following types of MATRIX VISION frame grabber:

  • mvDELTA
  • mvSIGMA
  • mvGAMMA
  • mvTITAN

Software Installation

  1. Copy the appropriate driver tarball from the CD or web to your computer (e.g. CD-ROM is mounted on /cdrom and directory /mypath exists):
    >cp -v /cdrom/linux/dist_titan-030801.tgz /mypath
    
  2. Unpack the tgz-file using:
    >tar -xvzf dist_titan-030801.tgz
    
  3. Make the test programs and kernel modules by changing to the top-level directory:
    >cd /mypath/dist_titan-030801
    
  4. and then...

    > ./configure
    > make
    

    It is also possible (and sometimes necessary) to start the configure program with options. See the INSTALL file for full details. Two common options are:

    > ./configure --with-kernel=<kernel source directory>
    

    (to enter an alternative location for the kernel sources. The default location is /usr/src/linux).

  5. Ensure you are logged on as "root" and then install the kernel modules on your computer with:
    >make install
    

Allocator kernel module

Some MATRIX VISION frame grabbers support a linear DMA buffer in Hard Live mode. In order to ensure that we have a linear memory area, we use a modified version of the allocator kernel module from Alessandro Rubini's book Linux Device Drivers (O'Reilly 1998 ISBN: 1-56592-292-1). This originally handled only linear memory blocks above the top of the memory range usually used by the kernel (highmemory). The allocator module from Rubini will not work correctly on systems with more than 1 GB of memory. In fact, on 2.4.x kernels the upper limit is mem=896M. In order to address this problem we have significantly rewritten parts of the allocator module to use a different method and this is now used by default. The two methods are described below:

  1. Method 1 "MATRIX VISION kmalloc method":

    This method makes use of the kernel function kmalloc to reserve blocks of memory. Since this function is only capable of reserving small blocks of memory (normally 128 kB) it must be called several times to reserve a block of, say 2 MB. If kmalloc is called early in the boot process before too many applications have used up memory (and possibly returned it to the pool, thereby creating "holes" in the memory map) then it is very likely that successive calls to kmalloc will return successive linear blocks of memory. On a machine with, say, 1GB of RAM the chances are very high that you will be able to get 2MB of continuous memory. The longer the computer runs the less likely is this method to work. Therefore it is essential that the allocator module is loaded as early as possible in the boot process and not unloaded again, as long as it is needed. The way to do this depends on your Linux distribution. Some, like Debian, allow you to enter the name of kernel modules that should be loaded during boot in a file (/etc/modules). Others, like SuSE or United Linux, allow boot scripts in /etc/init.d/boot.d which are capable of loading required modules. If you can find a way to load the allocator module during booting you may use this method and you will not need to pass a mem= parameter to your kernel in the boot loader.

  2. Method 2 "Rubini's Method":

    In order to reserve space for allocator you need to start the kernel with an extra parameter which instructs it to use slightly less than all the memory. e.g If your computer contains 256 MB of RAM start the kernel with the parameter:

    mem=252M
    

    The kernel will be able to use 252MB of memory and 4 MB may be used by allocator. A computer with 512 MB of RAM could be started with:

    mem=508M
    
    Note
    Method 1 is only available if you are using a kernel with a version number >= 2.4.20.
    If you do not start your kernel using this parameter the allocator module will still load without an error but linear DMA access will not work correctly. The amount of high memory you should reserve depends on the resolution and colour depth you are going to use and on your application.
    Method 2 will not work correctly on systems with more than 1 GB of memory. In fact, on 2.4.x kernels the upper limit is mem=896M
  3. Parameters:

    Some kernel module parameters are available to affect the way allocator works:

    Parameter Description Default Used by Method Available for Kernel
    linsizemb size to reserve (MB) 4 Method 1 >=2.4.20, 2.6.x
    maxresmb max RAM to search (MB) 1/2 RAM Method 1 >=2.4.20, 2.6.x
    use_kmalloc use Method 1 1 Methods 1, 2 any, but only useful for 2.4.0 >=kernel < 2.4.20
    himem assume this available (MB) <undefined> Methods 2 2.4.x
    check_pci paranoid check for bad PCI 0 Methods 2 2.4.x

    Examples:

    If you need to reserve more RAM (e.g. 8MB) then use linsizemb=8.
    If you want a more conservative search (100 MB) then use maxresmb=100
    If you want to force Method 2 use use_kmalloc=0 (only on 2.4.x kernels).
    If you know that you have reserved exactly 8MB using the kernel mem=parameter (Method 2) but you do not want the allocator module to search for this free memory then try use_kmalloc=0 himem=8

  4. Summary:

    Assuming you have an up-to-date kernel method 1 will be used by default to reserve 4 MB of RAM and you will normally not need to provide any parameters. Up to half of your available RAM will be searched for this 4 MB. You should load allocator during the boot process. If you have a kernel older than 2.4.20 then method 2 will be used and you must provide a mem= parameter to your kernel boot loader and cannot use more than 896 MB of RAM (even if more is installed in your computer). You can load or unload allocator anytime you want.

Frame grabber kernel module

You can create the kernel modules individually, if you want:

  1. Login as root.
  2. Change directory to the
    driver/os/linux/allocator 
    
    and
    driver/os/linux/matrixfg (or driver/os/linux/titan for e.g. mvTITAN)
    
    subdirectories in succession and
  3. compile the kernel modules using the following command in each directory:
    >./configure
    
    > make
    
  4. You can install the kernel modules (allocator.o and matrixfg.o or titan.o) by copying them to the appropriate directory on your computer (e.g. "/lib/modules/2.2.16/misc") and then typing this command in the appropriate directory:

    >make install
    

    You can now load the kernel modules by calling the script

    mvload matrixfg (or mvload titan) 
    

    to be found in the "bin" subdirectory. This will also create the appropriate device nodes after loading the modules. The script

    mvunload matrixfg 
    

    unloads both modules and deletes the device nodes.

    Note
    Device numbers for MATRIX VISION frame grabbers have not yet been officially assigned so we use a dynamic major device number technique which will usually assign a number of 254. See the script mvmodprobe or Rubini's book for more details. If you want to assign a fixed number (e.g. one of the numbers used for experimental drivers, for example 60) you can load matrixfg with a parameter (see below). Fixed major numbers also allow automatic loading of the kernel modules if you enter the appropriate alias lines in /etc/modules.conf. If everything has worked correctly you should see that both allocator and matrixfg(or titan) have been loaded by using the command:
    >lsmod
    This will list all the loaded kernel modules like this....
    Module Size Used by
    matrixfg 17212 0 (unused)
    allocator 2104 0 [matrixfg]
    ... etc.
    >
    
    A very small part of the driver is supplied in binary form only. If you do not wish to "taint" your kernel then please use the GPL version of the driver. The GPL version contains most of the features of the non-GPL version with the exception of e.g. fast channel switching and triggered capture of images.
  5. Parameters:

    The kernel modules matrixfg or titan may be loaded using one or more of the following parameters:

    Parameter Description Example
    vidmem=p (long) Major Device Number major_dev_num=60.
    Tells the kernel module to use the device with a major device number of 60. If you do not use this parameter or you set the number to 0, the kernel module will choose its own major device number.
    maxresmb Video Memory Address vidmem=0xd8000000.
    Tells the kernel module to assume that the VGA card's linear memory begins at the address specified. This should only be needed if your VGA card is not recognized automatically by the kernel module. Check the output in the system log when loading matrixfg (or titan ) to see which address is being used. If necessary, check the list of PCI devices (>cat /proc/pci) to see the possible addresses used by your VGA card.
    debug=n (long) Debug Message Level debug=0x3b.
    Tells the kernel module to output more debug messages in the system log.

VGA card

In order to display live images on your screen the driver attempts to determine the starting address of the linear memory used by the installed VGA card. It is possible to do this if the X-Windows system is running using function calls to an extended library (DGA). However, this library is not installed on all X-Windows systems, so the configure script will attempt to find out if DGA is being used on your system. Sometimes it may be helpful to turn on DGA by altering the configuration file for X-Windows (usually /etc/X11/XF86Config). To do this you need to have "root" access and you need to add a line to the section called "Module" like this:

Section "Module"
Load "extmod"
..
etc.

Using PCI mapping information the driver can determine which of your cards is the VGA card and which memory areas are mapped. However, it is not always possible to tell which of the mapped areas is the linear image memory. If the VGA card is a common one it should be known by the driver and the VGA detection will work correctly. New cards are constantly appearing on the market and it is not always possible to keep the driver up-to-date. In order to ensure that your VGA card is correctly detected please follow the procedure described below:

You may check whether the VGA card has been correctly detected by looking at your kernel message file (using dmesg or look at the file /var/log/messages). If you find (after some searching) a line like this

Sep 10 11:00:45 .... kernel: mv_vga Unknown video memory base address.

it means that the VGA card is unknown. If we don't know the VGA card then we can't be sure of the linear display memory address which we need as the destination for our DMA transfers. In this case we need:

  1. to find out the address and start the kernel module by hand with an extra parameter and/or
  2. add the information to a table in the kernel module sources and recompile.

In fact, the best way is to try it out using (1) and then do (2).

Here's how to do it.: Open the file driver/os/linux/kmod/vgatable.h and read the comments in the header area. It tells you how to add the vendor ID and device ID for your graphic card to the driver, Alternatively you can load the matrixfg kernel module using an extra parameter like this:

vidmem=0xd8000000 (Example for a NVidia card)

Just replace 0xd8000000 with the correct PCI memory address for your card. You can find this out by using "lspci -v" or "cat /proc/pci". If your card has more than one memory area you might have to try them all out until, when loading the kernel module, the error message (Unknown video memory base address) disappears and the test program works.

Note
The table in driver/os/linux/kmod/vgatable.h shows you which of the base addresses (PCI_BASE_ADDRESS_0 or PCI_BASE_ADDRESS_1) most of the usual cards use. PCI_BASE_ADDRESS_0 is the first address that "lspci -v" or "cat /proc/pci" shows and PCI_BASE_ADDRESS_1 is the second address, Some dual-head cards have 3 addresses. Note that the command lspci is actually deprecated and it may be necessary to examine the PCI cards using a different command or the command "cat /proc/pci".

Example Here is part of the output for Linux computer at MATRIX VISION ("lspci -v"):

01:00.0 VGA compatible controller: nVidia Corporation GeForce 256 (rev 10)
(prog-if 00 [VGA])
Subsystem: Guillemot Corporation: Unknown device 5022
Flags: bus master, 66Mhz, medium devsel, latency 32, IRQ 11
Memory at e0000000 (32-bit, non-prefetchable) [size=16M]
Memory at d8000000 (32-bit, prefetchable) [size=128M]
Expansion ROM at <unassigned> [disabled] [size=64K]
Capabilities: [60] Power Management version 1
Capabilities: [44] AGP version 2.0

And here's the same thing using "lspci -nv" (showing numeric IDs). Class 0300 is a VGA card:

01:00.0 Class 0300: 10de:0100 (rev 10)
Subsystem: 14af:5022
Flags: bus master, 66Mhz, medium devsel, latency 32, IRQ 11
Memory at e0000000 (32-bit, non-prefetchable) [size=16M]
Memory at d8000000 (32-bit, prefetchable) [size=128M]
Expansion ROM at <unassigned> [disabled] [size=64K]
Capabilities: [60] Power Management version 1
Capabilities: [44] AGP version 2.0

Trying out the address 0xe0000000 does not work here. But the second address (0xd8000000) does work. So the following line needs to be added to the table in vgatable.h and matrixfg.o needs to be recompild, installed and loaded. The vendor ID is 0x10de and the device ID is 0x0100 (from the output above):

{0x10de, 0x0100, "Geforce 256", PCI_BASE_ADDRESS_1},

Sometimes the IDs have already been defined in the kernel headers (/usr/source/linux/include/linux/pci.h (or pci_ids.h) and you can use sensible names instead of numbers like this (an invented example, doesn't really exist):

{PCI_VENDOR_ID_NVIDIA, PCI_DEVICE_ID_NVIDIA_GEFORCE2_256, "Geforce 256",
PCI_BASE_ADDRESS_1}

If you are successful you might like to inform MATRIX VISION what you have added to the table so that it can be included in future releases.

Note
Normally all chips from the same family use the same address base. e.g. All current NVidia chips use PCI_BASE_ADDRESS_1 which is the second address shown in lspci -v.

Libraries

The libraries are supplied as shared versions. The libraries are to be found in the subdirectory lib. The command

make install

will copy the appropriate library file for your frame grabber to the standard library path on your computer e.g. /usr/lib depending on the prefix you passed to

./configure

Alternatively you may leave the libraries in the lib subdirectory or copy the library to any other directory but you will have to set the environment variable LD_LIBRARY_PATH to include this directory.

E.g. for the bash shell:

>export LD_LIBRARY_PATH=$ LD_LIBRARY_PATH:/mypath/lib

Yet another alternative is to change the configuration file for your ldconfig command or use the mvldconfig script in the MATRIX VISION bin directory. The shared libraries contain the version number within the name. E.g. if the library for the mvSIGMA-SLC is called libslc.so.3.22.0, you will find symbolic links to the libraries within the lib directory:

>ls -l lib
drwxrwxr-x 3 technik users 1024 Sep 25 17:20 .
drwxrwxrwx 21 technik users 2048 Sep 25 17:26 ..
lrwxrwxrwx 1 technik users 16 Sep 24 09:53
libslc.so -> libslc.so.3.22.0
lrwxrwxrwx 1 technik users 16 Sep 24 09:54
libslc.so.3 -> libslc.so.3.22.0
-rwxrwxr-x 1 technik users 561114 Aug 30 13:11
libslc.so.3.22.0
>

The following is a list of the libraries available and their function. The names of the libraries actually supplied may vary depending on the current version/build number (e.g. libtitan.so.1.0.2 instead of libtitan.so.1.0.1 ).

Note
The term mvTITAN series is used for all mvTITAN and mvGAMMA products

Name Frame grabber Notes
libmvos.so All except mvTITAN series Common functions for most frame grabbers running on Linux
libmvvga.so All except mvTITAN series VGA Display using (s)vgalib
libmvdga.so All except mvTITAN series VGA Display information read from X server with DGA
libmvx11.so All except mvTITAN series VGA Display information read from X server
libmvfb.so All VGA Display information read from a frame buffer device
libmvnodisp.so All Dummy for no live display
libmvvgattn.so mvTITAN series VGA Display using (s)vgalib
libmvdgattn.so mvTITAN series VGA Display information read from X server with DGA
libmvx11ttn.so mvTITAN series VGA Display information read from X server
libsg.so pcIMAGE-SG  
libsrgb.so pcIMAGE-SRGB  
libsdig.so pcIMAGE-SDIG  
libslc.so mvSIGMA-SLC, mvSIGMA-SQ, mvDELTA Uses GPL kernel module called sigma.o
libslx.so mvSIGMA-SLC, mvSIGMA-SQ, mvDELTA Uses non-GPL kernel module called xsigma.o
libtitan.so mvTITAN series  

Writing your own applications

A number of test applications have been included to show you how to write programs that use the MATRIX VISION frame grabber driver. Some of these test programs may not be contained in the driver version you receive but at least linuxtest should always be available.

linuxtest

The files contained in the subdirectory linuxtest can be used to make simple test programs for all the MATRIX VISION frame grabbers. An image will be shown on the screen in hard live or soft live mode. You can make versions without any display at all (nodisp), VGA (vga) , X (x11) or Frame buffer (fb) versions. The top-level configure script will already have made the test programs for you and you will find them in the subdirectories called nodisp, vga, x11 and fb. Alternatively you may change directory to the linuxtest subdirectory and type

>./configure
> make

to (re)make the programs. The configure script will examine your system and only make test programs according to the libraries installed on your system. I.e. the SVGA versions will only be made if the SVGA library has been installed and can be found by the configure script. Likewise, if you only have the MATRIX VISION libraries for the mvTITAN series, the test programs for mvTITAN will be the only ones created. If you install other display libraries later you will have to repeat the configure, make process so that they are recognised.

Example for mvTITAN series: The command

>xtitantest --help

will show a list of possible parameters for the test program. You will also need a file called titantest.ini which contains information about the color depth, camera definitions etc. A number of example INI files are supplied within the linuxtest/examples subdirectory. You should copy and rename or use symbolic links as appropriate. In general, the INI file required is named after the test program:

Test program INI file required
titantest, xtitantest, ftitantest or ntitantest titantest.ini
slctest, xslctest, fslctest or nslctest slctest.ini

See the README file in the linuxtest directory for more details.

sdltest

The files contained in the subdirectory sdltest can be used to make simple SDL based test programs for all the MATRIX VISION frame grabbers. These programs are heavily based on linuxtest but use SDL to create and manage a Window. If you are running X and you have the correct SDL libraries installed on your system these programs will be created by the top level configure script. Again, you may change to the subdirectory and call configure and make there if you wish.

See the README file in the sdltest directory for more details.

Special notes for Linux

VGA applications

When using the VGA library for display you should add an extra, as yet undocumented function to the INI file used to initialize the frame grabber:

UseLibVga 1024 768 8 0

The parameters are

  • x resolution in pixels for the display
  • y resolution in pixels for the display
  • color depth in pixels for the display
  • set to 0 if using the first 3 parameters

Alternatively you may specify a number representing the VGA mode as the fourth parameter and leave the first three parameters as 0. See the VGA library documentation for details about the modes. E.g.

UseLibVga 0 0 0 12

will set VGA mode 12.

Note
In order to change VGA modes you need access rights as root.

Frame buffer applications

When using the frame buffer display library (libmvfb) for display you will need to be running a valid framebuffer otherwise you will get unpredictable results and/or crashes. The kernel must contain frame buffer support - either vesafb (for VESA-compatible cards) or a frame buffer that supports your graphic card directly (e.g. rivafb).

Copyrights

We have tried our best to adhere to the terms of all software licenses. Please contact us if you feel we have misinterpreted anything.

Some of the original work on the matrixfg, sigma and titan kernel modules was based on the source code for the bttv driver, in particular the routines to detect the VGA card and some memory management routines. Since the original code was released under the terms of the GNU General Public License (GPL), we are happy to supply our kernel module source code and give full credit to the original authors (see header files). Our kernel driver source code is therefore also released under the terms of the GPL, the full text of which may be found in the file GPL/COPYING. Loading these kernel modules will not "taint" your kernel!

The xsigma kernel module is an exception. Not all the source code for this module is supplied and this module is not released under the GPL. It contains no "foreign" GPL code (i.e. copyright not held by MATRIX VISION GmbH) or code derived from "foreign" GPL code. If this is a problem for you please use the sigma kernel module and libslc instead. The GPL version has a slightly reduced functionality.

The allocator module is Copyright © 1998 Alessandro Rubini and is released under the terms of the GPL. We have made some alterations which are documented in the source files.

The tutorial and test program for X are Copyright © 1998- 2005 MATRIX VISION GmbH and are distributed under the terms of the GPL. Please note that KDE/QT programs you develop may require a commercial license from TrollTech unless you also distribute them under the GPL or QPL, See http://www.trolltech.no or http://www.trolltech.com for more details. The VGA library used by some of the display libraries is free software and may be distributed and modified without restriction. The X libraries appear to be distributed under similar terms. See the header files on your Linux system for details.

The GNU C library is distributed under the terms of the GNU Library General Public License (GLPL). Applications. According to the terms of this license, "work that uses the library" is not restricted by the license. The full text of this license may be found in the file GPL/GLPL.html.

The frame grabber shared libraries for MATRIX VISION frame grabbers are based solely on the original Windows source code developed by us and contain no GPL code. These files are Copyright © 1992-2005 MATRIX VISION GmbH and the source code is not included here. You may distribute the binaries together with your own applications if you include the above Copyright notice in your documentation. Programs that use kernel services and functions are not derived form the kernel and are therefore not covered by the GPL like the kernel sources themselves.

The library libtitan.so.x.x for the mvTITAN series of frame grabbers uses some binary code from the Trimedia® code relocation library (libload.a) supplied by Philips. These functions are © Copyright Philips Semiconductors Trimedia Product Group 1997-2000.

Settings behavior during startup

Settings contain all the parameters that are needed to prepare and program the device for the image capture. Every image can be captured with completely different set of parameters. In almost every case, these parameters are accessible via a property offered by the device driver. A setting e.g. might contain

  • the gain to be applied to the analog to digital conversion process for analog video sources or
  • the AOI to be captured from the incoming image data.

So for the user a setting is the one an only place where all the necessary modifications can be applied to achieve the desired form of data acquisition.

Now, whenever a device is opened, the driver will execute following procedure:

Figure 10: wxPropView - Device setting start procedure
  • Please note that each setting location step in the figure from above internally contains two search steps. First the framework will try to locate a setting with user scope and if this can't be located, the same setting will be searched with global (system-wide) scope. On Windows® this e.g. will access either the HKEY_CURRENT_USER or (in the second step) the HKEY_LOCAL_MACHINE branch in the Registry.
  • Whenever storing a product specific setting, the device specific setting of the device used for storing will be deleted (if existing). So when the user is currently working with a device 'VD000001' belonging to the product group 'VirtualDevice' and there is a setting exclusively for this device storing a product specific setting now will automatically delete the setting for 'VD000001'. Otherwise a product specific setting would never be loaded as a device specific setting will always be found first.
  • The very same thing will also happen when opening a device from any other application! wxPropView does not behave in a special way but only acts as an arbitrary user application.
  • Whenever storing a device family specific setting, the device specific or product specific setting of the device used for storing will be deleted (if existing). See above to find out why.
  • On Windows® the driver will not look for a matching XML file during start-up automatically as the native storage location for settings is the Windows® Registry. This must be loaded explicitly by the user by using the appropriate API function offered by the SDK. However, under Linux XML files are the only setting formats understood by the driver framework thus here the driver will also look for them at start-up. The device specific setting will be an XML file with the serial number of the device as the file name, the product specific setting will be an XML file with the product string as the filename, the device family specific setting will be an XML file with the device family name as the file name. All other XML files containing settings will be ignored!
  • Only the data contained in the lists displayed as "Image Setting", "Digital I/O" and "Device Specific Data" under wxPropView will be stored in these settings!
  • Restoring of settings previously stored works in a similar way. After a device has been opened the settings will be loaded automatically as described above.
  • A detailed description of the individual properties offered by a device will not be provided here but can be found in the C++ API reference, where descriptions for all properties relevant for the user (grouped together in classes sorted by topic) can be found. As wxPropView doesn't introduce new functionality but simply evaluates the list of features offered by the device driver and lists them any modification made using the GUI controls just calls the underlying function needed to write to the selected component. wxPropView also doesn't know about the type of component or e.g. the list of allowed values for a property. This again is information delivered by the driver and therefore can be queried by the user as well without the need to have special inside information. One version of the tool will always be delivered in source so it can be used as a reference to find out how to get the desired information from the device driver.
< prev. section: Introduction | top | next section: Technical Data >