Re: SGI video ioctls

(Wow, a chance to contribute!...)

I've never used SGI's or the IndyCam myself, but I went poking around on
 one of the SGI's here at lab, and came up with this....

It seems that video on an SGI is controlled via the VL (Video Library), which
 in addition to setting hardware parameters, also specifies data paths and
 pipes.  With regards to the IndyCam (and the digital video input), the only
 device specific parameters are:

	Automatic Gain Control enable/disable
	Auto White Balance on/off
	Shutter speed
	Gain (manual)
	Red/Blue color balance
 most of which are color-specific attributes.

It doesn't seem like there is any core of useful camera-specific ioctl's; 
 short of reproducing the entire VL, there doesn't seem to be any standard
 to be gleaned from SGI's example.  I don't see any IndyCam-specific device,
 just "vino", whose output is in funky VL data streams.

I'm curious, though, is there a free version of VL available?  I know that
 "mesa" is a free clone of the SGI GL (graphics library)... maybe someone
 has done the job of writing a standard, free, generic video API already?

For fun, I tacked on the man pages for "vlintro" and "vino" to the end here...
  (Sorry about the ctrl chars; read through "more" for that real man-page

-matt m
 mit ai lab



     VLintro, libvl, vl	- IRIS Video Library for SGI workstations

     ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////vvvvllll....hhhh>>>>


     The IRIS Video Library (VL) provides a software interface for working
     with video	devices	and image data.	It provides a device-independent
     programming interface to the various SGI video products.

     The VL model is based on data paths. These	paths represent	ways in	which
     video data	can be moved through the system.  Paths	consist	of nodes,
     buffers and controls.  A node is a	building block of a path. The source
     and drain of a video stream, as well as any filters which affect data
     flowing between the source	and drain are all types	of nodes.

     Nodes have	controls associated with them. Controls	dictate	the behavior
     of	the node, and of any path containing that node.

     Once a path is setup, transfers can be initiated which cause data to flow
     from source to drain.  Transfers involving	host memory, or	memory nodes,
     require the use of	a ring buffer. Events are delivered to paths to	report
     changes in	the system which affect	it.

     vlAddNode(3dm), vlRemoveNode(3dm) - Add or	remove nodes in	a path

     vlCreateBuffer(3dm), vlDestroyBuffer(3dm) - Buffer	creation routines for
     transfers involving memory	nodes

     vlGetNextValid(3dm), vlPutFree(3dm), vlGetNextFree(3dm), vlPutValid(3dm)
     - ring buffer management routines

     vlCreatePath(3dm),	vlDestroyPath(3dm) - manage video paths

     vlGetControlInfo(3dm) - Get information about a specified control

     vlGetControlList(3dm) - Get list of valid video controls for a path

     vlGetControl(3dm),	vlSetControl(3dm) - Get	or set control value

     vlGetTransferSize(3dm) - Get video	ring buffer frame size

     vlNextEvent(3dm), vlCheckEvent(3dm), vlPeekEvent(3dm) - Get or peek at
     next video	event

									PPPPaaaaggggeeee 1111


     vlOpenVideo(3dm), vlCloseVideo(3dm) - Open	or close a connection to the
     video server

     vlPerror(3dm), vlStrError(3dm), vlErrno(3dm) - Video-library Specific
     Error Routines

     vlSelectEvents(3dm) - Select Video	Events of Interest

     vlSetErrorHandler(3dm), vlSetIOErrorHandler(3dm) -	Set the	VL non-fatal
     or	fatal error handler

     vlSetupPaths(3dm) - Setup video paths

     vlBeginTransfer(3dm), vlEndTransfer(3dm) -	Initiate, End transfer on
     video path

     The following example demonstrates	the creation of	a path between a
     memory source and a video drain.

	VLServer svr;
	VLPath path;
	VLNode src, drn;

	if (!(svr = vlOpenVideo(NULL)))

	/* Set up a source node	in memory */
	src = vlGetNode(svr, VL_SRC, VL_MEM, VL_ANY);

	/* Set up a video drain	node */
	drn = vlGetNode(svr, VL_DRN, VL_VIDEO, VL_ANY);

	/* Create a path on the	first available	device */
	path = vlCreatePath(svr, VL_ANY, src, drn);
	if (!path) {

	/* Set up the hardware for and define the usage	of the path */
	if (vlSetupPaths(svr, (VLPathList)&path, 1, VL_SHARE, VL_SHARE)<0)

									PPPPaaaaggggeeee 2222


     The Video Library has a set of buffer management calls which allow	the
     sending or	receiving of frame data	to or from host	memory.

     A VLBuffer	consists of a list of frame-sized regions of memory each with
     an	associated header block. Buffers are needed for	transfering data to or
     from memory nodes.	To receive a frame, the	reader calls one of
     vlGetNextValid or vlGetLatestValid	, and to free that frame calls
     vlPutFree.	 To send a frame, the writer calls vlGetNextFree, copies the
     data to be	sent into the acquired buffer, and then	vlPutValid to send
     that frame.

     Various controls affect buffer size. Setting controls which affect	frame
     size should be done prior to calling vlCreateBuffer.

     The following example demonstrates	the creation of	a buffer and
     registration of that buffer with a	path and node.

	VLBuffer buf;

	/* Create a ring buffer	for the	data transfers */
	buf = vlCreateBuffer(svr, path,	src, 1);

	/* Associate the ring buffer with the path */
	vlRegisterBuffer(svr, path, src, buf);

     When errors occur,	a global variable, vlErrno is set to reflect the
     cause. The	call vlGetErrno	should be used to report it's value.

     /usr/include/dmedia/vl.h			     C/C++ header file
     /usr/people/4Dgifts/examples/dmedia/video/vl/*  Example programs
     /usr/lib/libvl.so				     VL	DSO

     vlOpenVideo(3dm), vlCreatePath(3dm), vlGetNode(3dm), vlSetupPaths(3dm),
     vlSetControl(3dm),	vlCreateBuffer(3dm), vlBeginTransfer(3dm),

									PPPPaaaaggggeeee 3333


VVVVIIIINNNNOOOO((((7777))))								       VVVVIIIINNNNOOOO((((7777))))

     vino - on-board video input system	for Indy

     Vino is the builtin video on the Indy System.  It supports	three
     different types of	inputs:	digital, composite, and	S-Video	(Y/C).	The
     digital input is for use with the IndyCam camera and the analog inputs
     are for use with standard video equipment.	 Vino supports input on	the
     digital and one of	the two	analog ports simultaneously.  The analog
     inputs may	be in either PAL or NTSC formats and a variety of controls are
     available that allow the user or programmer to set	various	parameters
     used for the analog to digital conversion.

     Using Vino, it is possible	to read	live video into	the computer's memory
     which can then be displayed in a graphics window on the screen or further
     processed by the application.  Using the VL programming library (see
     _v_l_i_n_t_r_o(3)), a program can	request	video in either	monochrome, low
     resolution	color, or two forms of high resolution color.  The video image
     can be captured in	either full or reduced size formats.

     The video control program,	_v_c_p(1) allows the user to control the default
     inputs and	their timing.  Additionally, it	allows the user	to set certain
     device parameters which are described below.  The defaults	for all	of
     these controls are	in the file /usr/etc/video/ videod.defaults.vino which
     is	the file restored when the "File>Restore Factory Settings" is

   IIIInnnnddddyyyyCCCCaaaammmm SSSSiiiiggggnnnnaaaallll CCCCoooonnnnttttrrrroooollllssss
     The following controls affect the IndyCam.	 All but the first, which is
     on	the main panel,	may be adjusted	by bringing up the IndyCam panel under
     the ``Pro'' menu option in	the main vcp window.

     White Balance  The	white balance button causes the	camera to
		    automatically configure the	red and	blue balances to
		    achieve an overall even toned image.  For best results,
		    hold up a well lit piece of	white paper in front of	the
		    camera and click on	white balance, the camera will then
		    calibrate itself.

     Freeze	    This button	toggles	the video stream from the camera on
		    and	off.  When the video is	frozen,	no video data is sent
		    by the system.

     AGC Enable	    This toggle	button turns on	or off the automatic gain
		    control in the IndyCam.  When automatic gain control is
		    on,	the camera continually adjusts itself to changing
		    lighting conditions	in order to produce an even level of
		    brightness.	 When automatic	gain control is	off, it	is up
		    to the user	or program to set the proper gain level.  If
		    the	gain is	too low, then the picture will appear dark;
		    when the gain is too high it will appear white or washed

									PPPPaaaaggggeeee 1111

VVVVIIIINNNNOOOO((((7777))))								       VVVVIIIINNNNOOOO((((7777))))


     Shutter Speed  This multiple choice control lets you control the shutter
		    speed of the camera.  A faster shutter speed lets in less
		    light and may be used when the amount of light is too high
		    to be compensated for by the gain control.

     Gain	    This control is used when the automatic gain has been
		    turned off.	 It allows manual adjustment of	the camera

     Red Balance    The	red balance controls the proportion of red in the

     Blue Balance   The	red balance controls the proportion of blue in the

     Saturation	    The	saturation value affects the overall color intensity
		    of the image.  When	saturation is set to zero, the image
		    will have no color.

   AAAAnnnnaaaalllloooogggg VVVViiiiddddeeeeoooo	IIIInnnnppppuuuutttt CCCCoooonnnnttttrrrroooollllssss
     The analog	video input controls are used to configure the two standard
     video input ports on the Indy.  The main panel has	three controls on it:
     lock to VTR, input	source,	and input timing.  The rest of the controls
     are located on the	analog video input panel under the ``Pro'' menu.

     Lock to VTR    This toggle	controls the synchronization of	the input
		    video signal.  When	enabled, the Vino analog port attempts
		    to track the input signal continuously.  When disabled,
		    the	Vino analog port matches the input signal but does not
		    make continual adjustments.	 With video sources that
		    fluctuate, the VTR lock usually generates a	clearer

     Input Source   This selects the default input source when the input is
		    analog video.  The two choices correspond to the two
		    connectors on the back of the machine.  The	composite
		    input is an	RCA-type two wire connector that is commonly
		    found on VCRs and cameras.	The S-Video input uses a
		    mini-DIN connector that has	separate signals for luminance
		    and	chrominance (sometimes referred	to as Y/C).  Better
		    VCRs and cameras support S-Video which generally results
		    in a superior picture.

     Freeze	    This button	toggles	the video stream from the camera on
		    and	off.  When the video is	frozen,	no video data is sent
		    by the system.

     Prefilter	    This toggle	enables	an analog signal filter	that usually
		    results in a cleaner picture with less ``sparkles''.

									PPPPaaaaggggeeee 2222

VVVVIIIINNNNOOOO((((7777))))								       VVVVIIIINNNNOOOO((((7777))))

     Color Mode	    This toggle	controls the interpretation of color
		    information	in the signal.	If set to ``Auto'', then Vino
		    attempts to	detect the presence of color in	the signal and
		    enables color signal processing if it finds	it.  If	set to
		    ``Color'' then Vino	assumes	the signal is color all	the
		    time.  If set to ``Mono'' then Vino	disables and color
		    signal processing.	When using a monochrome	source,
		    somewhat better picture quality may	be obtained if the
		    color mode is set to mono.	A very poor color signal may
		    be mistaken	for black and white in which case the
		    ``Color'' setting may used to force	recognition of color.
		    See	the description	for ``Color Kill Threshold'' below for
		    more information.

		    When Color Mode is set to color and	you have a Composite
		    input, then	the chroma trap	is on by default.  If you
		    select an S-Video input then the chroma trap is off.  When
		    the	chroma-trap is on and you have a color composite
		    picture, you may want to turn on the Pre-Filter to allow
		    more of the	luma signal to survive the chroma trap.

     Aperture	    This adjustment affects the	sharpness of the picture.
		    There are 4	settings on this button	as shown below.	 Each
		    affect the gain at various frequencies in the incoming
		    signal.  There are curves published	for the	settings of
		    this parameter in the "1993	Desktop	Video Data Handbook"
		    on page 3-220 in figures 22	and 23.	 Each curve is labeled
		    with a setting of the 7191 sub- address 06.	 These match
		    the	settings in our	software as follows:

			 7191 "06"	 Video Control Panel
			 Setting	 Aperture Setting
			 --------	 -------------------
			   80h			0
			   81h			0.25
			   82h			0.5
			   83h			1.0

		    If the reader does not have	access to the curves below is
		    a quick table showing the rough gain/frequency pair	for
		    each setting.  The flatest response	appears	to be the 0.25

									PPPPaaaaggggeeee 3333

VVVVIIIINNNNOOOO((((7777))))								       VVVVIIIINNNNOOOO((((7777))))


			 Vy(dB)	Gain Depending on Aperture Setting
			 fy (MHz)   0	  0.25	  0.5	 1.0
			 --------  ---	  ----	  ---	 ---
			   0	    3	    3	   3	  3
			   1	    3	    3	   3	  3
			   2	    3	    3	   3	  3.5
			   3	    2.5	    3	   3.5	  4
			   4	    2	    3	   4	  5
			   5	    1.5	    3	   4.5	  6
			   6	    1	    3	   4	  6
			   7	    0	    2	   4	  6
			   8	   -1	    1	   2.5	  5

     Coring	    This adjustment also affects the sharpness of the picture.
		    Coring is a	form of	noise reduction. The coring settings
		    impact the bandpass	filters	output signal which is working
		    with a 13 bit word precision.  The coring settings decide
		    what thresholds of these lsbs in the 13 bit	word affect
		    the	least significant bits of the 8	bit luma word.	The
		    luma word has 8 bits Y7-Y0.	 Coring	says only Y0 bit will
		    be affected	for the	setting	of +/- 1LSB, Y0	and Y1 will be
		    affected for the setting of	+/- 2LSB  and Y0-Y2 will be
		    affected for the setting of	+/- 3LSB.  If you boost	the
		    gain of high frequency components in the bandpass or with
		    the	pre-filter then	you should have	some noise reduction
		    which would	be to turn coring off or set it	to +/- 1LSB
		    which would	restrict the rounding after the	bandpass to
		    the	least significant bit of the final 8 bit monochrome

     Bandpass	    This adjustment also affects the sharpness of the picture.
		    The	bandpass filter	can be programmed to different
		    frequencies	even when the chroma trap is bypassed.	The
		    figures in the databook do not show	the frequency response
		    for	this bandpass filter independently.

     Vertical Noise The	vertical noise setting controls	the analog video
		    recognition	of frame boundaries.  Different	types of video
		    sources may	need different settings	to obtain a stable

     Hue	    The	hue adjusts the	balance	between	colors in the signal.

     Color Kill	Threshold
		    The	color kill threshold sets the minimum level at which a
		    color signal will be recognized.  A	poor color input
		    signal may cause the automatic color detection logic to
		    oscillate between monochrome and color.  This adjustment
		    allows the user to control the minimum signal needed to

									PPPPaaaaggggeeee 4444

VVVVIIIINNNNOOOO((((7777))))								       VVVVIIIINNNNOOOO((((7777))))

		    enable color signal	processing.

     The video daemon software automatically probes for	the active video
     inputs when it is first started.  The order or precedence in selecting
     the default input is:

	 Input signal(s) active:

	    svideo  composite  indycam	default_input
	    ------  ---------  -------	-------------
	   yes	    x	      x	       svideo
	   no	    yes	      x	       composite
	   no	    no	      yes      indycam
	   no	    no	      no       composite

     This allows you, for example, to use the VCR's power button to change the
     default input between it and the IndyCam when first starting up the video


     Whether the video daemon starts at	systems	start up time is controlled by
     the videod	"chkconfig" option.  If	it's on, then the video	then the video
     daemon is started when the	system first boots.  If	it's off, then the
     video daemon is not started until the first video application is started;

     Input timing and source may be changed while any video application	is
     running but also might cause loss of sync and undesired effects.  This is
     also applies to restoring the factory settings.

     Some VCR's	don't produce stable NTSC or PAL signals when some tape
     transport functions are employed.	For example, switching from PLAY to
     FAST FOWARD often results in a disruption of the video sync and may cause
     VINO to become confused.  The system software attempts to restart the
     video capture but it may not be able to and will then return a error to
     the application.

     The default control values	have no	effect until a video path is created.
     They are used as suggestions for applications such	as videoin to specify
     the desired input source.

     The video tools supplied  in /usr/sbin are:  videoin, videopanel,
     vidtomen and vlinfo.

     VINO supports frame(field)	capture	that is	decimated in both the X	and Y
     directions. Decimation of sizes 1/2th, 1/3rd, 1/4th, 1/5th, 1/6th,	1/7th
     and 1/8th are supported, though the color quality suffers at the smaller
     ranges.  To compensate for	this limitation, the system software initiates
     a decimation conversion for values	1/4th, 1/6th and 1/8th by doing	the

									PPPPaaaaggggeeee 5555

VVVVIIIINNNNOOOO((((7777))))								       VVVVIIIINNNNOOOO((((7777))))

     first half	of the decimation in hardware and the second half of the
     decimation	in software.  This affects the software	overhead required for
     capturing video.

     The user can also clip the	frame in the X and Y direction but VINO	cannot
     clip inward from the right	hand edge.  If an attempt to set the VL_SIZE
     and/or VL_OFFSET to values	that would result in the right hand edge to
     not be the	end of the active video	line, a	VLBadValue error is returned
     and the value is adjusted to be correct.

     Vino cannot capture a video line whose size is exactly divisable into
     4096.  For	example, if a video line is to be packed into 32 bit RGBA
     pixels and	the VL_SIZE set	to 512,	then the resultant line	size would be
     2048 which	is exactly divisable into 4096.	 If an attempt to set a
     VL_SIZE value creates this	condition, the system software will adjust the
     VL_SIZE value to be a the next higher allowable size.

     As	with all VL devices, a vlGetControl should always follow a
     vlSetControl to get the actual value that was accepted.

     The following VL packing formats are supported by vino.


     /var/arch/libvl/vino.so /usr/etc/video/videod.defaults.vino

     vcp(1), videoin(1), vlinfo(1), vlintro(3)

									PPPPaaaaggggeeee 6666