------------------------------------------------------------
        Copyright (c) 2005-2008 by NCast Corporation
                    All rights reserved.

      VGA/Video digitizer device V4L2 driver README

                      Version 2.1.0
------------------------------------------------------------


                          CONTENTS

1. Introduction
2. Recommended hardware
3. System requirements
4. Installation
5. De-installation
6. Firmware update
7. Module parameters
8. /proc file system interface
9. Sample applications


                        INTRODUCTION

The NCast Corporation VGA/Video Digitizer Card is a high performance
PCI plug-in card which can capture and digitize RGB and video signals
for use in applications such as webcasting, desktop conferencing, device
monitoring and graphics presentations. The design of this card with dual
memory buffering and multiple inputs makes it one of the highest performing
cards available on the market.

This document describes the initial version of the Linux drivers for this
card. These drivers are based on Video-for-Linux (V4L2) which is widely 
supported by many applications programs. This release does not support
the old generation interface, V4L.

Key features of this card are listed here:

1. Video and graphics capture up to 60 fps

   Permits smooth graphics animations and quality video.

2. VGA, DVI, Composite and S-Video inputs

   Multiple graphical and video sources are supporte and can be switched
   in real-time during a webcast or conference.

3. Input autodetection mode

   The card will automatically seek an active input if none is specified.

4. All capture sizes from 320x240 up to 1920x1200 supported, with hardware scaling.
   Provides compatibility with popular encoding software.

5. I420 and BGR24 (reversed RGB24!) colorspace supported.
   I420 A standard colorspace supported by most graphics programs.
   Temporarily removed support of RGB24.

6. Picture-in-Picture (PIP) support for multi-window video overlays or side-by-side
   captures.
   
Also, please note that there are some software/hardware limitations:

1. For BGR24 format capture size is limited to UXGA (1600x1200).
   It's due to required amount of DMA Accessible Memory that needs
   to be allocated by the driver for optimal performance.
   (software limitation)

2. For I420 format capture sizes (width and height) must be even. 
   It's due to format I420 specification details.

3. For I420 format capture size width muliplied by height must divide by 16.
   It's current hardware requirment. All standard capture sizes meet this
   requirement.

                    RECOMMENDED HARDWARE

Capturing and processing large graphics images requires CPU cycles and PCI
bus bandwidth. The following hardware requirements are considered minimal:

1. Intel Pentium 4 processor with HyperThreading

2. 256MB of memory


                    SYSTEM REQUIREMENTS

Before starting installation please make sure your system
meets the following requirements:

1. Linux kernel version 2.6.x

2. Configured kernel headers (sources)

3. Video For Linux 2 support enabled in the kernel

4. /proc file system support enabled in the kernel

5. GCC compiler tools

6. Root access


                        INSTALLATION

To install the driver you must compile the source code, copy
the generated module to the appropriate location and use the modprobe
command to install the module in the kernel. Please enter the
following commands from the UNIX shell:

1. Decompress the driver file digitizer3-x.x.x.tgz:

        tar xzf digitizer3-x.x.x.tgz

2. Change current directory to the driver sources:

        cd digitizer3-x.x.x

3. Compile the driver sources:

        make

4. Copy the driver module to appropriate location:

        make install

5. Install the driver module in the kernel:

        modprobe digitizer3

You may check the results of your work by using the "lsmod" command
to see if this module has been installed and is listed.


                       DE-INSTALLATION

Please enter the following commands from the UNIX shell:

1. Change current directory to the driver sources:

        cd digitizer3-x.x.x

2. Uninstall the driver module:

        make uninstall


                       FIRMWARE UPDATE

To capture up to 1920x1200 firmware version 2.00 installed on the board is required. 
For up to UXGA resolution capture firmware version 1.02 is sufficent, but at least
1.05 is recommended. You may check the installed version in the 
/proc/digitizer entry:

        cat /proc/digitizer

The firmware version 2.00 file is located in digiupdate directory. To
receive newer versions please contact NCast Corporation.

Please enter the following commands from the UNIX shell to update
the digitizer board to firmware version 2.0:

1. Change current directory to the driver sources digiupdate directory:

        cd digitizer3/digiupdate

2. Start firmware update script for firmware_2_00.hex file:

        digitizer3update firmware_2_00.hex


                     MODULE PARAMETERS

The driver module accepts two optional parameters. You can
set these parameters from the command line when installing the
module using the insmod and modprobe commands.
 
1. video_nr

        The "video_nr" module parameter can be used to set the
        device file allocated by the driver module. For
        example, setting "video_nr" to 3 will force the
        driver module to allocate the "/dev/video3" device file.
        When this parameter is omitted the driver module
        will use the first free device file.

2. debug

        Setting this parameter to value 1 or greater will
        enable the generation of debug messages.


                 /proc FILE SYSTEM INTERFACE

After the driver module installation a new /proc file system
entry "/proc/digitizer" will be available. This file system entry
may be used to get or set the state of the digitizer3 parameters.

Use this command to show digitizer board status information:

        cat /proc/digitizer

To run commands to alter the digitizer3 state use the "echo" command.
For example, to set input to VGA type:

        echo "set_vga" > /proc/digitizer

Commands can be run at any time. Signal detection after an
input switch will take 2-5 seconds during which a black screen
will be captured.

The driver module accepts following commands via this entry:

1. set_vga

        Set main input to VGA.

2. set_dvi

        Set main input to DVI.

3. set_composite

        Set main input to Composite.

4. set_svideo

        Set main input to S-Video.

5. set_auto

        Set main input autodetection mode.

6. set_pip_vga

        Set PIP input to VGA.

7. set_pip_dvi

        Set PIP input to DVI.

8. set_pip_composite

        Set PIP input to Composite.

9. set_pip_svideo

        Set PIP input to S-Video.

10. set_pip_auto

        Set PIP input autodetection mode.

10. swap_main_pip

        Swap main and PIP inputs.

11. set_pip_on

        Show PIP window.

12. set_pip_off

        Hide PIP window.

13. set_window     X[%] Y[%] WIDTH[%] HEIGHT[%]
    set_pip_window X[%] Y[%] WIDTH[%] HEIGHT[%]

        Position the main or PIP window within the capture window. You can use pixels
        or percentages. Here are some examples:
        
        a) Set the main window to fullscreen
        
            echo "set_window 0% 0% 100% 100%" > /proc/digitizer

        b) Position the PIP window into the top-left corner
        
            echo "set_pip_window 0% 0% 25% 25%" > /proc/digitizer

        c) Position the PIP window into the top-right corner
        
            echo "set_pip_window 75% 0% 25% 25%" > /proc/digitizer

        d) Set the main window and the PIP window side-by-side
        
            echo "set_window 0% 25% 50% 50%" > /proc/digitizer
            echo "set_pip_window 50% 25% 50% 50%" > /proc/digitizer

        e) Set the main window position to the top-left corner and size to 1024x768
        
            echo "set_window 0 0 1024 768" > /proc/digitizer

14. set_vga_hpos [-|+]OFFSET

        Adjust image horizontal position, range -10 to 10 pixels. Use this command
        when the image captured from VGA input is shifted. The new position will be saved
        and used the next time.

15. set_vga_vpos [-|+]OFFSET

        Adjust image vertical position, range -10 to 10 pixels. Use this command
        when the image captured from VGA input is shifted. The new position will be saved
        and used the next time.

16. set_vga_brightness VALUE

        Set brightness for VGA input, range 0 to 100, default 50. 

17. set_vga_contrast VALUE

        Set contrast for VGA input, range 0 to 100, default 50.

18. set_vga_saturation VALUE

        Set saturation for VGA input, range 0 to 100, default 50.
        
19. set_vga_hue VALUE

        Set hue for VGA input, range 0 to 90, default 45.
        
20. set_dvi_brightness VALUE

        Set brightness for DVI input, range 0 to 100, default 50. 

21. set_dvi_contrast VALUE

        Set contrast for DVI input, range 0 to 100, default 50.

22. set_dvi_saturation VALUE

        Set saturation for DVI input, range 0 to 100, default 50.
        
23. set_dvi_hue VALUE

        Set hue for DVI input, range 0 to 90, default 45.
        
24. set_svideo_brightness VALUE

        Set brightness for S-Video input, range 0 to 100, default 50. 

25. set_svideo_contrast VALUE

        Set contrast for S-Video input, range 0 to 100, default 50.

26. set_svideo_saturation VALUE

        Set saturation for S-Video input, range 0 to 100, default 50.
        
27. set_svideo_hue VALUE

        Set hue for S-Video input, range 0 to 90, default 45.
        
28. set_svideo_sharpness VALUE

        Set sharpness for S-Video input, range 0 to 44, default 15.

29. set_composite_brightness VALUE

        Set brightness for composite input, range 0 to 100, default 50. 

30. set_composite_contrast VALUE

        Set contrast for composite input, range 0 to 100, default 50.

31. set_composite_saturation VALUE

        Set saturation for composite input, range 0 to 100, default 50.
        
32. set_composite_hue VALUE

        Set hue for composite input, range 0 to 90, default 45.
        
33. set_composite_sharpness VALUE

        Set sharpness for composite input, range 0 to 44, default 15.

34. reset

        Reset the 80186 controller on the digitizer board.


                    SAMPLE APPLICATIONS

The driver is compatible with many popular capture, playback and encoding
programs available for Linux. Two such programs are open source project
MPlayer (available from www.mplayerhq.hu) and commercial Real Producer
(free version is available from www.realnetworks.com/producst/producer).
Below are listed examples of typical usage:

1. Capture and display 640x480 frames from S-Video input

        mplayer tv:// -tv driver=v4l2:outfmt=i420:width=640:height=480:input=2 

2. Capture and display 1024x768 frames from VGA input

        mplayer tv:// -tv driver=v4l2:outfmt=i420:width=800:height=600:input=0 

3. Capture and encode to AVI file 60 seconds of 640x480 frames from VGA input

        mencoder tv:// -tv driver=v4l2:outfmt=i420:width=640:height=480:input=0 -ovc lavc -endpos 60 -o out.avi

4. Capture and preview with xawtv.

   This program should open default V4L/V4L2 device, if you have more than one, please specify:
   
       xawtv -c /dev/video0
       
   Program is available at: http://linux.bytesex.org/xawtv/

5. Upload images onto http server using ftp connection. After proper setting up type: 

       webcam
       
   Program is available at: http://linux.bytesex.org/xawtv/
	
6. Newest version of GnomeMeeting, called Ekiga.

   Program is available at: http://www.gnomemeeting.org/
