                          PMS-grabber package, ver 2.0, 1995, Oct. 13

0. Copyright
============
 (c) Wolfgang Koehler, wolf@first.gmd.de, 1994/95
     Kiefernring 15
     14478 Potsdam, Germany
     0331-863238

The "GNU Public Lincense" policy applies to all programs of this package

This package comes without any warranty, as it is. 
It may be freely copied and distributed to whatever - except military - 
purposes.  

1. Purpose
==========
This package was developed to make use of the PC frame grabber card 
"Pro MovieStudio" (PMS) by MediaVision under Linux. 

My main task is the online grabbing of single pictures for an image processing
 program. 
However, it can also be used as a video-viewer, assumed you have a really fast
 computer - otherwise the frame rate may be boringly slow (if you want to
 have a fast view you may resize the window to say 100x80 pixel - the smaller 
the higher frame rates you will get).
This slowness is mainly due to the concept of this card : the captured image 
is transferred through memory access and not with a feature connector directly
 to the video card like other frame grabber cards do.

The program is in an experimental state and will be developed further. 
Remember, however, my main intention is to use it for image processing.

The program is not a driver so it requires no kernel rebuilding, it runs 
simply as a program at user level. 
On the other hand this means there is no protection against misuse. If you 
start it twice on the same computer it will probably crash.

2. Main features of the programs
================================
* captures frames of the "Pro MovieStudio" frame grabber card
* runs under X-Window in a normal window with various setting options
* online view or capturing of single frames
* arbitrarily resizing of view window (via window manager) (up to ~ 500x500)
* up to 256 (or 65536 on some servers) colors on display 
* frame grabbing in rgb555/565-mode (32768 or 65536 colors) 
* computing of optimal color palettes from a given image
* popup menu for all option settings of the PMS-card
* popup menu for viewing and editing the registers (only for experiments)
* simple image analyzing tools (with mouse cursor in view window)
* save and load functions for ximages, captures and palettes
* comes together with a generally useful X-window package 
* a standalone program for displaying saved images that runs without PMS-card
  on any computer with X-window
 
3. Basics of the use of the PMS-card with Linux
================================================
The part of the program that deals directly with the card was adopted from 
another program from MediaVision ("grabber.c", "SetMVV.c"). 
So don't blame me for this code.
I modified it in a few points.

The Pro MovieStudio board has to be configured by software since it has no 
jumpers or DIPs. 
It uses 3 IO-ports which are selected by writing to port 0x9A01.
This means under Linux : ** IT CAN ONLY BE RUN AS ROOT **. 
If build with make it sets the SUID-bit to enable normal users to use it.
By default the used ports are 0x250 .. 0x252. 
Besides this the PMS uses a memory window of 4k in lower PC memory.
Default value is 0xC8000. 
Since Linux usually does not utilize this region there should be no problem. 
See INSTALL.txt how to customize these default settings.

possible resolutions :
----------------------
I have not been able to get a horizontal resolution above 512 - this 
corresponds to the buffer size of 1k. 
If anyone can tell me if that is possible or principally not I would 
appreciate it. 
The original source from MediaVision gives not much help for this. 
Also, setting vertical resolution above 280 is a little bit tricky. 
Higher values are simply expanded of this line nr.

colors :
--------

The PMS has several color modes : up to True Color with 8 bit for each basic 
color red,green,blue.
I used only the 15/16bit-rgb modes ie. each pixel is transmitted as 16bit word 
The problem is that X can only show up to 256 colors at once on most video 
cards, depending on the X-server you use. On servers that support 16bpp 
a much better visualization can be achieved. 
If the server also supports the "Shared Memory Extension"  this can be used
to a very fast direct mapping, since the representation of pixels is identical
(for the rgb-565 mode), see below.

The program runs in *two modes* 

a) if it detects a TrueColor visual display
  (16bpp) the capturing is also done in this mode. 
  In this mode no problems with allocating color cells or transforming 
  images arise.

b) If it runs on a PseudoColor display (8bpp) the capturing is done in 
  rgb555 mode and transformed for displaying to a subset of the 256 colors.
 
  For displaying images in 8bpp I use a palette vector, ie. a mapping 
  from 32**3 to 256 X-color values. 
  Each X-color entry again corresponds to RGB-value which is set by XStoreColor.
  The use of the right palette is a quite complicated task. 
  You also have to keep in mind that a X-application should be co-operative with
  respect to limited resources like color tables. 
  Ie. if one application grabs all free entries all others programs running 
  parallel will fail. 
  The program "PMS-view" does exactly this : it grabs all it can get. 
  However, the resulting color mapping is nevertheless quite poor. 
  The standard palette which is used by default uses a mapping to RGB332 values,
  ie. red and green are represented as 3 bit values, blue by 2 bits.
  However, there is a method implemented to generate optimized palettes for 
  given images, which usually produces very good results. 
  It is accessible through the "eval"-menu (see below). 


compression :
-------------
the PMS allows to compress images, this feature is not used here. 

interrupt driver:
-----------------
There has been a complete driver program from David Etherton. However, this
has considerable drawbacks. First, the driver mechanism requires a double
copying of the frames : once from the interruput handler to local buffers
and a second time from driver to user space. This is quite slow.
Second, the setting of parameters via IOCTL-calls is cumbersome.

My program uses the driver only as a unblocking signal for the read function;
the actual reading is done by the user program. Therefore it can also run
without any driver, but then asynchronously, of course.

Shared Memory :
---------------
For realistic live video this feature is absolutely necessary. Check, if your
display server supports this with the command "xdpyinfo". Then you should
enable it in the Makefile (see INSTALL.txt). 
The timings for my "Diamond Stealth Video 64" card show a speedup of 50 (!!) 
for the PutImage operation when SHM is used.


3. Building & Files 
===================
The package you got should contain the following files:

PMS-view.C :	main program for online viewing of images from the PMS-board, 
		controlling the settings, etc. see below
image-view.C :	a standalone program for displaying saved images, it may be
		run at any computer with X-windows (not Linux-specific) 
		and requires no PMS-card

view.C :
view.h :	functions for displaying an image under X-window
Makefile : 	for building the executables
mvv_parms.h : 	configuration file for setting IRQ, Port and Address
irq_driver.c :	the interrupt driver
SetMVV.C : 	basic setting functions for PMS-board, included by grabber.C
evaluation.C : 	palette & image processing; eval-popup
evaluation.h
grabber.C : 	Linux specific, port setting, memory mapping, capture function
grabber.h
ximage.C : 	functions for XImage file saving & loading
ximage.h

in the grafix subdirectory
window.h :
window.c :	all functionality to deal with X-Window, display, buttons, 
		popup menus, pulldown menus, etc.
eventnames.h, icon.h : belong to window.c
image.pix : 	a sample picture (my little niece) that should demonstrate
		the power of the palette computing algorithm 
		(340x255 pixels in 203 colors)
		loadable from the file menu in PMS-view or image-view
		(see below)

For a building it should normally be sufficient to invoke "make".

4. program PMS-view.C
=====================

This is the demonstration program for the whole package. 
Here I will shortly describe how to use its control buttons.
After starting a window pops up with life video from the PMS-card (if all 
settings are correct). 

On the top is a menu bar with control buttons :

grab : capture a single frame (not in life mode)

life : a toggle button between continuous capture / single frame capture

MVV set : gives a popup menu for all basic functions of the PMS card
	(frame rate, horizontal start, vertical start, Hue, Color Killer,
	switch sensitivity, ....) It has 10 scrollbars for numerical values,
	5 toggle buttons and 10 pulldown menues for selection.
	The "default" button resets them all to the initial values.
 	(the initial values can be changed in "SetMVV.C" by modifying the 4th
	column of struct "option_vector" to fit personal needs)
	Note: after a selection is made a new capture is automatically done
	to show the effect (in continuous mode not necessary).
	Setting "frame rate" only has the effect that too low frame rates will
	result in grabbing the same frame more than once. Too high rates have
	almost no effect at all.
	Not all selections are active.

MVV regs : gives a popup menu for viewing and playing with the registers of the
	PMS. This is only useful for experimenting with the board but not for 
	normal operation. There is also a small edit window "edit regs" which
	allows to set a register interactively (most useful in life mode).
	To change a value enter hex. register index followed by dec. value.
	If value > 255 the high byte is set into reg+1. The edit window accepts
	following keys : ESC (clears), Backspace, delete, Enter (confirms).
	Note: the edit only works if the cursor is inside the small frame !

	The display color of a register changes to red if the value changes. 
	The reset button sets all back to black.

set pal : is a pulldown menu for selecting the display palette. (The capture 
	mode is not affected from this). 
	You may choose between : 
		standard palette (RGB332), 
		grey scale palette (96 scales), 
		and captured palette (see below for explanation)

eval : gives a popup menu, mainly for palette computation 
	first it has a scrollbar to set the numerical value of the colors to 
	use for this palette. To perform computing use the button "new palette"
	The computing method uses the current image displayed to choose those
	colors for display that are mostly relevant for the image. The method
	is a recursive splitting of the 3-dimension color space. As optimizing
	criterion the resulting variance reduction is used. 
	However, while this gives quite brilliant results for a single image,
	or similiar images the computed palette will be useless for other
	images.

file : a pulldown menu for saving and loading files. 
	Each entry pops up a file selection box (either for reading or writing)
	Before overwriting existing files a confirmation is querried.
	Supported file types are: 
		"pix" = 8bit color (with palette)
		"cap555", "cap565" = direct 15/16 bit color
		"ppm" = standard ppm format for exchange with other graphic 
			programs, like xv,
			uses a 3byte per pixel format (see ppm(1))

	The file names should be "*.pix" "*.cap555" and "*.pal555" and "*.ppm"
	"image.pix" uses a format similiar to XImage, ie. one byte per pixel,
	"capture" uses the direct capture format as rgb555,
	"palette" saves a computed palette together with its XColor values.
	Note that if you load a "image"-file there is no corresponding 
	capture in the memory. That means the info line will display garbage.
	Secondly, loading an image file requires a certain number of free 
	colors (depending on the saved file). If there are too much allocated 
	by other X-programs the loading will fail.

At the bottom of the display there is an "info line" which shows some 
statistics of the captured frame, mainly the times for capturing and 
displaying in life mode. 
If you switch to single mode you are able to inspect the captured image. 
The info line then shows the RGB- values of the pixel under the cursor, the 
luminance value, the percentages of each color (or the displayed color 
normalized to the range 0..31).

Resizing :
----------
 The usual window resizing feature (from the window manger by drawing the 
window borders) performs an resolution adaption. 
That means, if you make the window smaller the resolution of the grabbed frame
will also diminish which results in a drastic acceleration of the grabbing.

5. program image-view
=====================
This program is an extract of PMS-view that implements a viewer for saved 
images independently of the PMS-board. 
Therefore it is also usable on any computer that runs X-window.
It has the buttons "set palette" , "evaluate" and "file" which work like 
described above. 
If you start it in this directory it will come up with the loaded image from 
"franzi.pix".

6. window functionality
=======================
This functionality is implemented in "window.c" and "window.h".
I will not describe it here, since this is part of a larger package "grafix"
which is published independently.
If you want to understand more have a look at window.c and window.h.
It should be available at all ftp-sites that mirror sunsite.

7. personal remarks
===================
If you find this package useful it would be nice to send me message about this.
If you have improvements or remarks that can be considered of public interest 
send them to me I will try to implement them and possibly republish the 
improved package.
However, I'm not sure how widespread this PMS-board is so I don't know how 
many Linuxers might use it.

8. Times
========
measured on a Pentium P90 computer, with a simple unenhanced ISA video card
(ET4000) and without interrupt driver (polling mode)
tcap is the capture time, tdisp the time for color transformation and display

  size    depth   tcap tdisp
340 x 255 15bit - 0.11s 0.11s
200 x 150 	- 0.05s 0.03s
120 x 80 	- 0.02s 0.01s

with an accelerated Diamond Stealth (polling mode) and display depth of 16bpp
(since it uses SHM the display time is unmeaserable, ie. below 0.01s)
frt is the frame rate.

  size    depth   tcap 	frt
500 x 400 16bit  0.105s  9
340 x 255 16bit  0.065s 15
200 x 150        0.025s 40



