This is Info file cxdrv.info, produced by Makeinfo-1.55 from the input
file cxdrv.texinfo.

   This file is the user's and programmer's manual for cxdrv 0.85.

   Copyright (C) 1995 Alessandro Rubini

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

   This file documents the 0.85 release of the `cxdrv' module for
Linux-1.2 and later (October 1995).


File: cxdrv.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

cxdrv
*****

* Menu:

* Overview::
* Compiling and Installing::
* The driver::
* The Library::
* The Dos-Compatible Library::
* The Sample Programs::
* Function Index::


File: cxdrv.info,  Node: Overview,  Next: Compiling and Installing,  Prev: Top,  Up: Top

Overview
********

   The device driver for the cx100 frame grabber is designed as a
dynamically loadable module for the Linux kernel. The distribution
encloses the device proper, a library of useful functions and a few
sample programs using the grabber.

   The device driver implements open, close, read, write, ioctl and
select. The current design allows for up to 8 cx100 boards, however,
I've only one, and couldn't test with more of them.

   The library is meant to be a slight help to the programmer. It offers
access to ioctl() calls at a higher level of abstraction.

   The dos-compatible library is a deprecated entity. It offers the
same unstructured function calls offered by the dos library distributed
by ImageNation. Existing dos programs should compile and with little or
no problems by linking with "-l libcxgdos.

   The sample programs, then, are what I used to test the device
driver, and are enclosed in the distribution to ease your own testing
and to be copied by the programmers.


File: cxdrv.info,  Node: Compiling and Installing,  Next: The driver,  Prev: Overview,  Up: Top

Compiling and Installing
************************

   A simple  "make" invocation will compile the  module, the  libraries
and the test programs. A "make install" will install  things in the
proper places.

   The default "prefix" is `/usr/local', so installed files will go
into `/usr/local/bin', `/usr/local/lib' and so on. To change the prefix
(and use, for example, `/usr'), you should specify "PREFIX=/usr" on the
make command line, both when compiling and when installing.

   The module is installed in `/lib/modules/version/misc', where
version is your current Linux version.

* Menu:

* Loading and Unloading::


File: cxdrv.info,  Node: Loading and Unloading,  Prev: Compiling and Installing,  Up: Compiling and Installing

Loading and Unloading the Module
================================

   To load the module the user should issue "./cxg_load" in the
distribution directory. The script  is a  simple wrapper around
"insmod", which  creates the  /dev  nodes after   loading  the module.
Execution of the script needs superuser privileges.

   To unload the module, "./cxg_unload" is provided. The script is a
wrapper around "rmmod" which additionally removes the `/dev' nodes.

   There are a few public variables in the module which can be modified
at load time. Integer values may be assigned to them on the command
line of cxg_load, because the whole commandline is passed along to
insmod.

`cxg_base'
     Setting this variable (0 by default) disables autodetection of the
     board and forces an I/O base address. Since only one base address
     can be specified, multiple boards can only be reached via
     autodetection (the preferred way anyways).

`cxg_major'
     This variable (0 by default) assigns a major device number to the
     driver, disabling dynamic assignment. You can use this variable if
     you don't want to create and destroy device nodes when
     loading/unloading the module. You should remember that major number
     in the range 1-31 are already assigned, and dynamic numbers start
     from 63 and grow downwards.

`cxg_fake'
     Enables loading the driver even when no board is there.  If one
     board is there and you set cxg_fake to 1 you'll see two boards:
     one working and one not. for performance issues, a fake board can
     be used only if the package is compiled with DEBUG_CX100 turned
     on; otherwise any open() call issued on a fake board will fail.

`cxg_ram'
     Only for the first board, choose the ram page to be used for the
     grabber memory. Be careful about this, since no check is performed
     about actual segment availability. For additional boards, the ram
     page can only be set using Cxg_RamPage. *Note Setting Modes::.
     The function is the preferred way anyways, since it can autodetect
     a free memory segment.

`cxg_irq'
     Only for the first board, choose the irq line to be requested.
     For additional boards, the irq line can only be requested using
     Cxg_SetIrq. *Note Setting Modes::.

   As an exmaple, the following command line could work (

             ./cxg_load   cxg_ram=10 cxg_fake=1


File: cxdrv.info,  Node: The driver,  Next: The Library,  Prev: Compiling and Installing,  Up: Top

The Driver Proper
*****************

   The driver is able to manage up to eight frame grabber boards
(though it has only been tested with one board). The implemented
functions are open(), close(), read(), write(), seek(), ioctl() and
select(). mmap() is not implemented due to laziness on my side.

   Each board can be opened multiple times. Multiple opens share some
board features, which are hardware-related (for example being low/high
resolution), while other features are private to each open file.

   In particular, the user can specify a set of "Regions of Interes"
(ROI's) private to each file. When reading the file, then, only the
specified regions are returned, either as raw data or as a pgm image.
*Note ROIs::.

   Each open file can also specify how frequently data must be
gathered, in order to achieve blocking read. This option however is
currently only supported for the raw (whole frame at a time) device.

   Different /dev nodes are created for each recognized board, to
accomplish different tasks

* Menu:

* The /dev Nodes::
* Open and Close::
* Read::
* Write::
* Ioctl::
* Select::
* ROIs::


File: cxdrv.info,  Node: The /dev Nodes,  Next: Open and Close,  Prev: The driver,  Up: The driver

The /dev Nodes
==============

   Each frame-grabber board existing in the system is accessed by means
of three different file-system nodes.

`/dev/cxg0'
     `Cx100 grabber' 0. This is the raw device. It can always be opened
     when a board exists in the computer. Diagnostics can be performed
     on the board, but any "real work" that requires memory mapping or
     interrupt reporting needs ioctl() invocation to ebable either
     feature. Blocking read is allowed on this device if the board
     generates interrupts.

`/dev/cxg0ol'
     The overlay device. If your board supports overlays, this device
     can be read-from or written-to just like /dev/cxg0. R/w operations
     will affect overlay memory instead of frame memory.  Not tested as
     of 0.85

`/dev/cxg0f'
     Full-featured device. open() will succeed only if both
     memory-mapping and the interrupt can be detected. The first open()
     invocation may take up to 1 seconds to succeed (or fail), due to
     interrupt probing. Successive open()s will be faster because the
     probed irq number is retained. This device allows blocking read
     and selecting.

`/dev/cxg0pgm'
     Simple pgm device. Its opening enables memory mapping and
     continuous grabbing. This means that the device can be used as a
     simple live video. A pgm header is added to each frame. Use of
     this node can't coexist with use of other nodes, because there is
     one video memory for each board. Writing to this file changes the
     size and position of the pgm image being returned. Blocking read
     is not allowed here, not select(), due to my lazyness.

   Note however that board features like memory mapping and irq
reporting are global. Thus, enabling/disabling them on one device will
enable/disable for all of them.

   The second board is accessed through nodes /dev/cxg1xx, and so on,
up to /dev/cxg7xx.

   Please note that boards older than at least October 1995 are not
able to generate interrupts when driven by a PAL (european) camera.
This is a very infortunate bug in the board (interrupts *are* useful
under a real operating system), and ImageNation promised to fix the
board microcode as soon as possible.


File: cxdrv.info,  Node: Open and Close,  Next: Read,  Prev: The /dev Nodes,  Up: The driver

Open and Close
==============

   The minor device number of the device node is used to identify which
device is being accessed and in what way. A single board has multiple
personality.  *Note The /dev Nodes::.

   On open, a structure to hold file-specific information is allocated,
and it exists up to file closing. No check regarding hardware features
is ever performed. Thus, when the device is opened multiple times, you
must be careful to run cooperating processes.

   Correct file permissions on the nodes should be used to enforce
authorized use.

   On the first open(), the board is powered up, and a small delay is
performed to ensure everything is setup for correct workings. On the
last close() the board is powered down, and any existing irq or memory
mapping is released. If you want to keep a persistent board state across
program execution, you need to keep the device open at least once.  A
stopped cat /dev/cxg0 > /dev/null or anything else will work fine.  I
use ./test P t1 L ("print the board ports, timeout one second and loop
over").


File: cxdrv.info,  Node: Read,  Next: Write,  Prev: Open and Close,  Up: The driver

Read
====

   When the device is read, data is returned according to the current
configuration of the file being read. The configuration mode can be set
using Cxg_SetRoi() and Cxg_PgmMode. *Note Setting Modes::.  Note that
before reading the device, you have to specify which segment in the
computer memory is to be mapped by the device (through Cxg_RamPage. If
no memory segment is being used, then read() will return 0 (to signal
no data was there). The ram page is automatically allocated for `full'
devices.

   The read() invocation may be blocking, if a grabbing interval was
specified through Cxg_SetStep(). read() will block only in raw mode.
Guess why: lazyness.

* Menu:

* Raw Mode::
* RoI Mode::
* Pgm Mode::


File: cxdrv.info,  Node: Raw Mode,  Next: RoI Mode,  Prev: Read,  Up: Read

Raw Mode
--------

   Right after opening, the file is in "raw" mode, and data being
returned is the whole video memory. If the physical device is in high
resolution, then read() Will return the same pixel after 256kb. If the
device is in low resolution, the same pixel will be returned after 64kb.

   "Raw" mode used to be the worst of all modes - data is returned
without performing any control on the current video page.

   If you have interrupts and blocking-read, however, raw mode may be
useful to read whole frames on a timely basis.  *Note Scheduling
Acquisition::.


File: cxdrv.info,  Node: RoI Mode,  Next: Pgm Mode,  Prev: Raw Mode,  Up: Read

RoI Mode
--------

   After  you invoke Cxg_SetRoi() with a non-null argument, the drivers
goes in roi mode. Data returned from read() will only be the content of
the selected regions of interest.

   This allows for fast grabbing of sequences in case you're only
interested in a small part of the whole frame. The program can run in a
tight loop of read(), without the need to care for regions after setup.
Using rois is faster than selecting parts after transferring to memory
the whole frame, because the transfer through the PC bus is the slowest
part of all the process.

   Region xfer is another way to transfer subareas of a frame. However,
region transfer is not blocking.


File: cxdrv.info,  Node: Pgm Mode,  Prev: RoI Mode,  Up: Read

Pgm Mode
--------

   Sometimes it's useful to directly read pgm's from the device,
instead of unstructured raw data. The pgm mode of the driver is only
available when RoI's are enabled. *Note RoI Mode::.

   To enable/dibable pgm mode you need to Cxg_PgmMode(). Subsequent
read()s from the device will return the pgm header before the pixel data
of each RoIs. Raw mode doesn't allow putting a pgm header in from of the
frame.

   Reading the /dev/cxg0pgm (or equivalent), instead, returns a single
pgm image on each open. This operation is not blocking, as of 0.85.


File: cxdrv.info,  Node: Write,  Next: Ioctl,  Prev: Read,  Up: The driver

Write
=====

   Write is not available as of 0.85 (But it will be soon).


File: cxdrv.info,  Node: Ioctl,  Next: Select,  Prev: Write,  Up: The driver

Ioctl
=====

   The ioctl() call is implemented to perform all the non-read and
non-write operations.

   Several ioctl commands are available, but rather than documenting
them here, I'd better talk about library funcitions (macros) to access
such functionality on an higher level. *Note The Library::.

   Note that cx100 command numbers and bit numbers are available as
symbolic entities, defined in `"cxdrv.h"'.


File: cxdrv.info,  Node: Select,  Next: ROIs,  Prev: Ioctl,  Up: The driver

Select
======

   The select call is only meaningful if you have enabled interrupts on
your board (if you use the `full' device, interrupts are enabled at
open() time). If no interrupts are there, the read() call will not
block, and select() will always report the file as readable.

   The `overlay' device (if any) is always readable.

   Select for writing, on the other hand, will always tell that the
device is writable, because you are always allowed to overwrite video or
overlay memory.

   The other esotheric file interface, mmap(), is not implemented.
Mainly because I don't need it, and I'm not paid to write it ;-)


File: cxdrv.info,  Node: ROIs,  Prev: Select,  Up: The driver

Regions of Interest
===================

   .SH USING REGIONS OF INTEREST

   A "Region of Interest" is a rectangle in the video memory. Using
regions of interest instead of transferring the whole frame in
conventional RAM can reduce bus overhead (being an ISA card is the weak
point of the cx100 grabber).

   You can exploit regions of interest by either read()ing only the
interesting part of video memory or by transferring a single region or
regions on specific ioctl() requests. The read() approach is preferred,
because you can instruct the driver to read image data every so-many
frames.

   To configure read(), you should invoke Cxg_SetRoi before tha actual
read() calls. Successive reads will cycle through the Regions
specified. To transfer specific regions you should invoke
Cxg_XferRegion. Details about Cxg_Roi are under the library docs.
*Note Setting Modes::.


File: cxdrv.info,  Node: The Library,  Next: The Dos-Compatible Library,  Prev: The driver,  Up: Top

The Support Library
*******************

   The main role of the support library is to provide well-named
functions to access ioctl functionality. In the following description,
the FD argument must always be the file descriptor associated to the
frame grabber.

   The library functions are often implemented as macros, but this is
not documented. It doesn't make difference to you, unless you try to
take the function's address (unlikely).

   The functions never modify their arguments, even when they are
macros.

   All the functions return -1 in case of error (setting errno to a
meaningful value), and 0 or the requested value ( >= 0 ) in case of
success.

   When the macro implementation evaluates its arguemnts more than once,
this misfeature is documented.

   Symbols for bit values and commands are defined in cxdrv.h, which
must be included in your source. The symbols are different from those
released bt ImageNation, because I try to keep a clean namespace.
Symbols are not described here, because I'm lazy (keep a copy of
cxdrv.h handy to cut and paste what you need).

* Menu:

* Bit Manipulation::
* Command::
* Information Retrivial::
* Grab Control::
* Setting Modes::
* Field Counter::
* Delays::
* Region Transfer::
* Scheduling Acquisition::


File: cxdrv.info,  Node: Bit Manipulation,  Next: Command,  Prev: The Library,  Up: The Library

Bit Manipulation
================

 - Function: int Cxg_GetPorts (int FD, char *WHERE);
     Returns the status ports.  WHERE is a pointer to an array of four
     characters. On return, these characters will embed the current
     value of the four status ports (ports 0, 1, 2, 6) of the frame
     grabber.

 - Function: int Cxg_SetBit (int *FD, int BIT);
 - Function: int Cxg_ClrBit (int *FD, int BIT);
     Turn on/off a single bit. The bit number is checked for overflow.

 - Function: int Cxg_SetBitV (int *FD, int BIT, int V);
     Sets one bit to a particular value. The V value must be zero or
     not-zero. The bit number is checked for overflow.

 - Function: int Cxg_GetBit (int *FD, int BIT);
     Return the current value of the bit (zero or not-zero).  Turn
     on/off a single bit. Note that Cxg_GetPorts is faster if you need
     to look to more than one bit.  The bit number is checked for
     overflow.

 - Function: int Cxg_SetPage (int *FD, int PAGE);
     Sets the current memory page of the grabber. This call is not
     needed (it's dangerous) unless you're grabbing in low resolution.
     In this case it sets the current image. This macro evaluates twice
     the PAGE argument (of which only the lowest two bits are used).


File: cxdrv.info,  Node: Command,  Next: Information Retrivial,  Prev: Bit Manipulation,  Up: The Library

Command
=======

 - Function: int Cxg_Command (int FD, int CMD);
     Invoke a cx100 command.  This specified  hardware command CMD is
     invoked on the board. The result is an 8-bit value. The command
     number is not checked for ranges.


File: cxdrv.info,  Node: Information Retrivial,  Next: Grab Control,  Prev: Command,  Up: The Library

Information Retrivial
=====================

 - Function: int Cxg_GetHwInfo (int FD, Cxg_Board *PTR);
     This call fills a structure in user space. The structure is
     defined in <cxdrv.h>. Fields in the structure are the same for
     different file descriptors referring to the same board.

 - Function: int Cxg_GetSwInfo (int FD, Cxg_Clientdata *PTR);
     This call fills a structure in user space. The structure is
     defined in <cxdrv.h>. Fields in the structure are different for
     different file descriptors. This call is only interesting for
     debugging the driver itself.

 - Function: int Cxg_GetRamInfo (int FD, char *PTR);
     Fills a 16 byte wide array with values telling if the ram segment
     contains ram, rom, another cx100 board or if it is empty. Symbolic
     names for the values are defined in <cxdrv.h>.

 - Function: int Cxg_LibVersion (void);
     This macro returns a string describing the version of the library.
     Actually, this is a constant value taken from the header.
     Obviously you must keep the header and the library in sync.


File: cxdrv.info,  Node: Grab Control,  Next: Setting Modes,  Prev: Information Retrivial,  Up: The Library

Grab Control
============

   These functions are used to control grabbing. The WFLAG argument
tells if the call must wait for acquisition to complete (not-zero) ore
return right after requesting acquisition (zero). If no video is there
the functions set errno to ENODATA.

 - Function: int Cxg_GrabFrame (int FD, int WFLAG);
     Requests grabbing of one frame at the beginning of the next
     vertical blank. If the board is in low resolution, only one field
     will be grabbed.

 - Function: int Cxg_GrabField (int FD, int WFLAG);
     Requests grabbing of one field at the beginning of the next
     vertical blank.

 - Function: int Cxg_GrabFieldN (int FD, int N, int WFLAG);
     Requests grabbing of a specific field (wait for one or two
     blankings.

 - Function: int Cxg_GrabLive (int FD);
     Turns on continuous acquisition.

 - Function: int Cxg_GrabOff (int FD);
     Turns off continuous acquisition.


File: cxdrv.info,  Node: Setting Modes,  Next: Field Counter,  Prev: Grab Control,  Up: The Library

Setting Modes
=============

 - Function: int Cxg_SetIrq (int FD, int IRQ);
     Enable the frame grabber to use interrupts.  The extra argument is
     the interrupt number to request. If an irq line is already active,
     it is released beforehand.  The special values CXG_AUTODETECT and
     CXG_IRQ_NONE are used to try to autodetect the irq line and to
     release any active line. Autodetection is really tentative,
     because the board is not equipped for autodetection.  This doesn't
     work at time of writing.

 - Function: int Cxg_RamPage (int FD, int ARG);
     Tell the device to use a particular ram page to map the video
     memory. The ARG argument should be a number in the range 0xA-0xF.
     Zero means "no change", -1 means "disable mapping".
     CXG_AUTODETECT works well. Any another value will cause EINVAL to
     be issued.  The return value is the page number where the video
     memory gets actually mapped.

 - Function: int Cxg_SetRoi (int FD, Cxg_Roi *ROI);
     Configures the driver to return only the selected regions on
     interest at the following read() calls. *Note Read::.  If ROI is
     NULL normal raw reading will be performed.  The ROI pointer must
     point to an array of Cxg_Roi structure, and the field count of the
     first region in the array tells how many regions are there. the
     fields x, y, wid, and hei are used to identify the rectangular
     region.

 - Function: int Cxg_LowRes (int FD, int FLAG);
     Puts the board in low or high resolution according to the argument
     (0 or not 0).  This is more than setting the low-resolution bit on
     the board ports. Note that when the board is in low resolution you
     are free to choose which page to use, through Cxg_SetPage.

 - Function: int Cxg_PgmMode (int FD, int FLAG)
     Enables or disables the generation of pgm (Portable GrayMap) output
     when in Roi mode. *Note ROIs::. The extra argument is 0 or 1 to
     disable/enable pgm generation. Pgm generation is disabled by
     default.  If you need pgm frames as standalone foles, use
     /dev/cxg0pgm instead of the raw device.


File: cxdrv.info,  Node: Field Counter,  Next: Delays,  Prev: Setting Modes,  Up: The Library

Field Counter
=============

   Note that the field counter in this driver is a 32 bits value, even
if the board only has a 16 bits counter. This is needed when
long-running application must schedule time-delayed acquisitions (a 16
bit value makes one complete round in more or less 20 minutes).

 - Function: int Cxg_ClearFC (int FD)
     Clears the field counter.

 - Function: unsigned Cxg_GetFC (int FD);
     Returns the current field counter. The -1 value is quite unlikely
     to happen because it would happen after 1 thousand days continuous
     acquisition.


File: cxdrv.info,  Node: Delays,  Next: Region Transfer,  Prev: Field Counter,  Up: The Library

Delays
======

 - Function: int Cxg_WaitVb (int FD);
     Wait till the next vertical blank.

 - Function: int Cxg_WaitVbField (int FD, int FIELD);
     Wait till the next vertical blank corresponding to a specific
     field.

 - Function: unsigned Cxg_WaitTillCount (int FD, int COUNT);
     Wait till the field counter reaches the specified COUNT.  If that
     current count is already over, return straight ahead.  The return
     value is the current value of the field counter (this means that
     if all is ok, it should be equal to COUNT).  This time delay is
     not a busy loop: normal CPU scheduling can go on during latency.
     If I could get interrupts, however, it could be much easier to
     implement and even less requiring for the CPU.


File: cxdrv.info,  Node: Region Transfer,  Next: Scheduling Acquisition,  Prev: Delays,  Up: The Library

Region Transfer
===============

 - Function: int Cxg_GetRegion (int FD, Cxg_Roi *PTR);
 - Function: int Cxg_PutRegion (int FD, Cxg_Roi *PTR);
     These two functions perform atomic region transfer from the
     grabber memory to computer ram, and vice-versa.  The Roi argument
     pointed to by PTR must feature valid wid, hei, x, y, and count
     fields.  count should be set to 1, in case future releases of the
     driver will support transferring an array of regions.  The field
     xtra.data must point to a valid memory region, where data to be
     transferred is found/put.

     The transfer will either succeed or fail - half transfers will
     never happen. Note that this call works with either conventional
     memory or overlay memory, according to the device node being used.



File: cxdrv.info,  Node: Scheduling Acquisition,  Prev: Region Transfer,  Up: The Library

Scheduling Acquisition
======================

 - Function: int Cxg_Interval (int FD, int STEP, int NEXT);
 - Function: int Cxg_SetStep (int FD, int STEP);
 - Function: int Cxg_SetNext (int FD, int NEXT);
     Each open file related to the driver can set its own scheduling
     policy. The scheduling policy is made up of an interval (number of
     frames between successive grabbings) and a next-frame (which frame
     is to be grabbed next time). Usually setting the step is
     sufficient, because the next frame is automatically set to the
     very-next frame returned from the camera. Please be careful as
     only SetStep() has been actually used, and it only works if your
     hardware is capable of generating interrupts. Enhancements on
     blocking-read issues are expected quite soon.

   Note that these calls don't return any video data. They only tell the
driver to act in blocking mode. Any subsequent read will block till the
field counter reaches the right value and then grab one frame/field
before returning data. Support for O_NONBLOCK is  provided.


File: cxdrv.info,  Node: The Dos-Compatible Library,  Next: The Sample Programs,  Prev: The Library,  Up: Top

The Dos-Compatible Library
**************************

   The dos compatibility library is meant to ease porting of programs
written for dos to the Linux operating system. Note however that most
of the features described below are untested. Moreover, work in this
direction is very slow, because I write my own programs using the Cxg_
functions. Feel free to report any problem to me.

   To use the compatibility library, you should link your program with
"-lcxdrvdos", and include <cx100.h> from your source file.

* Menu:

* Dos-compatible Variables::
* Dos-compatible Functions::


File: cxdrv.info,  Node: Dos-compatible Variables,  Next: Dos-compatible Functions,  Prev: The Dos-Compatible Library,  Up: The Dos-Compatible Library

Dos-compatible Variables
========================

   The following table lists all the global variables documented in the
Software Manual from ImageNation (in the same order), and reports their
status in the compatibility library.

`fg'
     The variable is not supported, by now.

`FGDATA Fd[MAX_PORTS]'
     The array is filled by init_library(), though it is a fictious
     entity: not all fields in the structure make sense.
    `cx'
          TRUE ot FALSE

    `fgp'
          Not set nor useable

    `addr'
          Not set not useable

    `video'
          TRUE or FALSE

    `ccir'
          NTSC or CCIR

    `rev'
          Revision number

    `off'
          Power-off

`SEGDATA Sd[MAX_SEGS]'
`int pc_display'
`BYTE far *videoram'
`WORD video_seg'
     These variables/arrays aren't  supported, and won't ever be.
     Memory management in performed in the driver, and users don't need
     such information. The structure SEGDATA is not defined, either.

`int lastrow'
     This works are documented.

`int x_char'
`int y_char'
     No text drawing capability is there, by now.

`int port_bits[31][2]'
     Not existent. You shouldn't use it anyways.


File: cxdrv.info,  Node: Dos-compatible Functions,  Prev: Dos-compatible Variables,  Up: The Dos-Compatible Library

Dos-compatible Functions
========================

   The following table lists all the functions (or statements)
documented in the Software Manual from ImageNation (in the same order),
and reports their status in the compatibility library.  Most of the
functions which should return void, do actually return int. This should
not be a problem.

`void acquire(void);'
`void acquiref(void);'
     Supported.

`blank'
     Supported.

`void board_off(void);'
`void board_on(void);'
     Supported (not fully functional yet).

`int clear_field_counter(void);'
`int clear_field_counter_high(void);'
     Supported.

`CLEAR_PORTS'
     Not yet.

`void clr(int bit);'
     Supported.

`void copy_line(BYTE *buf, WORD row, BYTE dir, BYTE orient);'
     Not yet.

`void cx_command(int command);'
     Supported.

`void dec_page;'
     Supported.

`void display'
     Supported.

`void erase_ram(void);'
     Not yet.

`void exit_library(void);'
     This only closes the currently open device.

`void fill_column(WORD column, int color);'
`void fill_ram(int color);'
`void fill_row(WORD row, int color);'
     Not suppored, yet.

`int get_address(void);'
     Not supported. It shouldn't be invoke by the user, anyways.

`long get_clock(void);'
     Not supported. I have to think about it...

`void get_column(BYTE *buf, WORD column);'
     Not yet.

`int get_page;'
     Supported.

`int get_pixel(WORD x, WORD y);'
`void get_rectangle(BYTE huge *buf, WORD x1, WORD y1, WORD dx, WORD dy);'
`void get_row(BYTE *buf, WORD row);'
     Not yet.

`int grab(void);'
`int grab_field(void);'
`int grab_specific(int field);'
`int grab_specific_field(int field);'
     Supported. But the return value is always zero. grab_specific() is
     the same as grab(), because I don't care about these details.  The
     same net effect can be achieved by grabbing one specific field
     without waiting for the next blanking, and then grabbing

`WORD grab_triggered(WORD delay, WORD timeout);'
     Not supported, yet.

`void gray_scale_fill(void);'
     Not supported.

`int have_egavga(void);'
     Not supported. It doesn't make sense.

`void high_res;'
`void inc_page;'
     Supported.

`char *init_library(void);'
     Supported: it opens /dev/cxg0 and returns NULL or strerror(errno)

`int internal_sync(void);'
     Supported.

`void load_input_lut(int address, int data);'
`void load_input_lut_buf(int *buf);'
`void load_output_lut(int address, int data);'
`void load_output_lut_buf(int *buf);'
`void load_overlay_lut(int address, int red, int green, int blue);'
`void load_rgb_lut(int address, int red, int green, int blue);'
`void load_rgb_lut_buf(RGB buf[]);'
     Lut management is not available in this release.

`void low_res;'
     Supported.

`void put_column(BYTE *buf,WORD column);'
`int put_pixel(WORD x, WORD y, int color);'
`void put_rectangle(BYTE *buf, WORD x1, WORD y1, WORD dx, WORD dy);'
`void put_row(BYTE *buf,WORD row);'
     Not supported, yet.

`void ram_off(void);'
`void ram_on(void);'
     Supported.

`int read_dips(void);'
`int read_field_counter_high(void);'
`int read_field_counter_low(void);'
     Supported

`int read_file_to_buf(char *fname, BYTE huge *buf, DWORD buflen);'
`int read_file_to_ram(char *fname);'
     Block transfer is not implemented, by now.

`int read_key(void);'
`int read_revision(void);'
`int read_status2(void);'
     Supported.

`void RELOAD_PORTS(int *tmp);'
     Not yet.

`void reset_cx(void);'
     Supported, not fully functional.

`void SAVE_PORTS(int *tmp);'
     Not yet.

`int segment_vacant(int addr);'
     Not yet.

`char *select_fg(int index);'
     Not supported. Maybe, in the future...

`void set(int bit);'
`int set_address(int addr);'
`int set_ccir(void);'
     Supported.

`void set_display_mask(int mask);'
`void set_gain(int gain);'
`void set_gross_gain(int ggain);'
     Not yet.

`int set_half_page(int row);'
`int set_interrupt_polarity(int pos);'
     Not supported. Since the user shouldn't touch hardware, they won't
     ever be.

`int set_ntsc(void);'
     Supported.

`void set_offset(int offset);'
`void set_overlay_mask(int mask);'
     Not supported, by now.

`int set_trig_edge_sensitive(void);'
`int set_trig_level_sensitive(void);'
`int set_trig_polarity(int pol);'
`int show_both_fields(void);'
`int show_field(int field);'
`int status(int bit);'
`int sync_to_video(void);'
`int toggle(int bit);'
`void unblank;'
     Supported

`void vga_off(void);'
`void vga_on(void);'
     Not supported, and don't make sense under Linux.

`int waitvb(void);'
`int waitvb_field(int field);'
     Supported.

`WORD wait_for_trigger(WORD timeout);'
     Not yet.

`int write_buf_to_file(char *fname, int erase, BYTE *buf, DWORD buflen);'
`int write_ram_to_file(char *fname, int erase);'
     Not yet

`void zip_dn(void);'
`void zip_up(void);'
     Not supported. I didn't understand them, either.

   Averaging, text-drawing and graphic drawing functions are not
available. I plan to do drawing under Linux, but I don't know if I'll
ever make dos compatibility.


File: cxdrv.info,  Node: The Sample Programs,  Next: Function Index,  Prev: The Dos-Compatible Library,  Up: Top

The Sample Programs
*******************

* Menu:

* Minors::
* cxg_check::
* cxg_show::
* cxg_grab::
* cxg_xgrab::
* Pacco Stuff::


File: cxdrv.info,  Node: Minors,  Next: cxg_check,  Prev: The Sample Programs,  Up: The Sample Programs

Minor samples
=============

   There are a few minor sources within the distribution: they are not
documented nor installed. They're tools I used to help my development,
and are part of the distribution just for my convenience.  You can look
at them if you're interested.

   test is is a simple program to issue low-level commands. You can
invoke ./test without arguments to get a short help.

   roitest gets a list of regions of interest on command line (using
the X-geometry representation and prints them continuously on stdout.

   seltest gets an optional device name and two numbers and uses read()
and select() to check workings of blocking read.


File: cxdrv.info,  Node: cxg_check,  Next: cxg_show,  Prev: Minors,  Up: The Sample Programs

The cxg_check Program
=====================

   cxg_check is a tool to report all available information about the
board(s) you have in your computer. It can also be used to monitor the
board(s) while an application is running.

   Without cmdline options, it will print system-wide and software
information, and will look for any available device to return
informationa bout them.  If commandline arguments are specified, only
the specified devices will be tested.

   I usually invoke "./cxg_check /dev/cxg0f" to force autodetection of
the irq line. *Note The /dev Nodes::.


File: cxdrv.info,  Node: cxg_show,  Next: cxg_grab,  Prev: cxg_check,  Up: The Sample Programs

The cxg_show Program
====================

   cxg_show displays live video on an ascii terminal. The program reads
argv[1] (or standard input) as a raw device, puts it to the desired
resolution and draws data as an 8-level gray scale using ascii
characters. It is installed along with the driver, as it may be useful
to test the camera without firing up X.

   The program is a small utility, and not too polished. It adapts the
output size to its stderr, and defaults to 80x50 if stderr is not a tty.

   A little more functionality is available on the command line, but I
haven't found the time to document it here.


File: cxdrv.info,  Node: cxg_grab,  Next: cxg_xgrab,  Prev: cxg_show,  Up: The Sample Programs

The cxg_grab Program
====================

   This is a cmdline-driven program to grab sequences of regions of
interest, saving them directly to disk without need to fire up X.
Unfortunately, it isn't eworking, yet.


File: cxdrv.info,  Node: cxg_xgrab,  Next: Pacco Stuff,  Prev: cxg_grab,  Up: The Sample Programs

The cxg_xgrab Program
=====================

   This program is a small Tk script, which displays grabbed images. If
has buttons to resize and move the region of the frame being grabbed,
and can save the image to a file.


File: cxdrv.info,  Node: Pacco Stuff,  Prev: cxg_xgrab,  Up: The Sample Programs

The pacco/* Files
=================

   The pacco directory contains partial source for a tool I used, which
uses the Pacco tool (iride.unipv.it:/pub/Pacco).

   The files are one C source and one Tcl source. They are in the
distribution to show how easy it is to grab and have live display (with
the right tools handy). Nothing is installed here.

   The "cinema" script in the pacco directory is a simple live-video
application.


File: cxdrv.info,  Node: Function Index,  Prev: The Sample Programs,  Up: Top

API Index
*********

* Menu:

* Cxg_ClearFC:                          Field Counter.
* Cxg_ClrBit:                           Bit Manipulation.
* Cxg_Command:                          Command.
* Cxg_GetBit:                           Bit Manipulation.
* Cxg_GetFC:                            Field Counter.
* Cxg_GetHwInfo:                        Information Retrivial.
* Cxg_GetPorts:                         Bit Manipulation.
* Cxg_GetRamInfo:                       Information Retrivial.
* Cxg_GetRegion:                        Region Transfer.
* Cxg_GetSwInfo:                        Information Retrivial.
* Cxg_GrabField:                        Grab Control.
* Cxg_GrabFieldN:                       Grab Control.
* Cxg_GrabFrame:                        Grab Control.
* Cxg_GrabLive:                         Grab Control.
* Cxg_GrabOff:                          Grab Control.
* Cxg_Interval:                         Scheduling Acquisition.
* Cxg_LibVersion:                       Information Retrivial.
* Cxg_LowRes:                           Setting Modes.
* Cxg_PgmMode:                          Setting Modes.
* Cxg_PutRegion:                        Region Transfer.
* Cxg_RamPage:                          Setting Modes.
* Cxg_SetBit:                           Bit Manipulation.
* Cxg_SetBitV:                          Bit Manipulation.
* Cxg_SetIrq:                           Setting Modes.
* Cxg_SetNext:                          Scheduling Acquisition.
* Cxg_SetPage:                          Bit Manipulation.
* Cxg_SetRoi:                           Setting Modes.
* Cxg_SetStep:                          Scheduling Acquisition.
* Cxg_WaitTillCount:                    Delays.
* Cxg_WaitVb:                           Delays.
* Cxg_WaitVbField:                      Delays.



Tag Table:
Node: Top978
Node: Overview1223
Node: Compiling and Installing2322
Node: Loading and Unloading3042
Node: The driver5535
Node: The /dev Nodes6758
Node: Open and Close9065
Node: Read10221
Node: Raw Mode11030
Node: RoI Mode11685
Node: Pgm Mode12450
Node: Write13083
Node: Ioctl13235
Node: Select13731
Node: ROIs14439
Node: The Library15382
Node: Bit Manipulation16752
Node: Command18108
Node: Information Retrivial18461
Node: Grab Control19651
Node: Setting Modes20685
Node: Field Counter22908
Node: Delays23576
Node: Region Transfer24436
Node: Scheduling Acquisition25345
Node: The Dos-Compatible Library26517
Node: Dos-compatible Variables27215
Node: Dos-compatible Functions28540
Node: The Sample Programs33685
Node: Minors33933
Node: cxg_check34698
Node: cxg_show35370
Node: cxg_grab36087
Node: cxg_xgrab36402
Node: Pacco Stuff36725
Node: Function Index37241

End Tag Table
