api.html

Linux support for Philips USB webcams halted Latest version: pwc-9.0.2.tar.gz (including documents

<h3><a name="vidiocpwcprobe">VIDIOCPWCPROBE</a></h3>

<p><b>Brief:</b> Prove existance of Philips (compatible) cam.</p>

<p><b>Argument:</b>
<pre>
struct pwc_probe
{
	char name[32];
	int type;
};
</pre>
</p>


<p>This function can be used to prove the presence of a Philips OEM cam
beyond reasonable doubt. The OEM models carry their own name in the
<b>video_capability</b> field, thus making it a bit harder to determine if a
camera has all the extra features. When this <span
class="code">ioctl()</span> call returns 0, compare the <b>name</b> field
from <b>pwc_probe</b> to the <b>name</b> field of <b>video_capability</b>;
if they match, the probe was succesful.</p>

<p>The <b>type</b> parameters returns the closest Philips compatible type
(645, 680, 730, etc). It's purely informational.</p>



<h3><a name="vidiocpwcsuser">VIDIOCPWCSUSER</a></h3>

<p><b>Brief:</b> Saves user settings.</p>

<p><b>Argument:</b> none.

<p>This function will write the current brightness, contrast, colour and
whiteness (gamma) settings into the camera's internal EEPROM, where they can
be restored by the following call.</p>

<p>Do not over-use this call; EEPROMs can only be written a limited
number of times (usually around 10,000 times). After that, the EEPROM
gets damaged and may not work at all.</p>

<h3><a name="vidiocpwcruser">VIDIOCPWCRUSER</a></h3>

<p><b>Brief:</b> Restore user settings.</p>

<p><b>Argument:</b> none.

<p>With this function, the values a user previously stored in the internal
EEPROM will be recalled. This function only reads from the EEPROM and
is thus safe.</p>


<h3><a name="vidiocpwcfactory">VIDIOCPWCFACTORY</a></h3>

<p><b>Brief:</b> Restore factory defaults.</p>

<p><b>Argument:</b> none.


<p>This function will restore all internal settings to a reasonable factory
default, including the values set by the user with VIDIOCPWCSUSER. This
function will also write to the camera's interal EEPROM, so don't overdo
it.</p>


<h3><a name="vidiocpwcscqual">VIDIOCPWCSCQUAL</a></h3>

<p><b>Brief:</b> Set compression preference.</p>
<p><b>Argument:</b> integer.</p>


<p>The Philips webcams use compression techniques to get the images across
the (narrow) USB bus. With this <span class="function">ioctl()</span> call you can specify if you like
no compression, low, medium or high compression. Higher compression means
less bandwidth is used, but could introduce artefacts into the image.</p>

<p>The function takes an integer in the range 0 - 3. 0 Means that you prefer
no compression, 3 = high compression. This setting is per camera, in
contrast to the 'compression' module parameter you supply when loading the
webcam module (which is only a default). This setting is also retained
between <span class="function">close()</span> and <span
class="function">open()</span> (but not between plug/unplug).

<p>This setting does take effect immediately.

<h3><a name="vidiocpwcgcqual">VIDIOCPWCGCQUAL</a></h3>

<p><b>Brief:</b> Get compression preference.</p>

<p><b>Argument:</b> integer.</p>



<p>See <a href="#vidiocpwcscqual">above</a>


<h3><a name="vidiocpwcsagc">VIDIOCPWCSAGC</a></h3>

<p><b>Brief:</b> Set AGC (Automatic Gain Control)</p>

<p><b>Argument:</b> integer.</p>


<p>The webcams have features like auto-exposure and some additional
circuitry to accomodate for changing light conditions. One of these features
is an AGC circuit that amplifies or attenuates the signal that comes from
the CCD/CMOS sensor.

<p>Normally this circuit is in auto mode, but you can set it to a fixed
value if you like. The VIDIOCPWCSAGC call takes an integer argument, in the
range 0..65535 (0x0..0xFFFF). 0 is low gain, and 65535 sets it to highest
gain possible. If you supply a negative number, the AGC is set to automatic
mode.</p>

<p>Example code:</p>

<p>
<pre>
	int agc;

	/* Select a high gain. Note the use of the &amp; with the 3rd parameter */
	agc = 40000;
	ioctl(fd, VIDIOCSAGC, &amp;agc);
</pre>
</p>

<h3><a name="vidiocpwcgagc">VIDIOCPWCGAGC</a></h3>

<p><b>Brief:</b> Get AGC (Automatic Gain Control) value.</p>

<p><b>Argument:</b> integer.</p>

<p>This function has a double meaning. If the returned value is negative, it
means the camera is in auto-AGC mode and the absolute value is the current
gain (range: -65535..-1). A positive value indicates the camera has been set
to fixed AGC mode and the selected gain is returned.</p>



<h3><a name="vidiocpwcsshutter">VIDIOCPWCSSHUTTER</a></h3>

<p><b>Brief:</b> Set shutter speed</p>

<p><b>Argument:</b> integer.</p>

<p>With this call you can manipulate the shutter speed of the camera, or the
rate at which it takes images from the CCD/CMOS sensor. The higher the
value, the longer it will take. Together with the AGC settings you can
manipulate the light-sensitivity of the camera quite a lot. Do not expect
any miracles though; it will not turn your $70 webcam into the Hubble
Space Telescope with an
<a href="http://antwrp.gsfc.nasa.gov/apod/ap000709.html">exposure time of 10 days (!)</a>.

<p>A negative value sets the shutter speed to automatic (controlled by the
camera's firmware). A value of 0..65535 will set manual mode, where the
values have been calibrated such that 65535 is the longest possible exposure
time that I could find on any camera model. It is not a linear scale, where
a value of '1' is 1/65536th of a second, etc.</p>

<p>Despite claims by some people who hacked at the Windows driver, I have
not been able to verify that the shutter speed can be set to anything large,
like 1 second or so. The longest exposure time is limited by the framerate
(at least 5 frames per second, so 1/5th of a second).</p>



<h3><a name="vidiocpwcsawb">VIDIOCPWCSAWB</a></h3>

<p><b>Brief:</b> Set Automatic White Balance</p>

<p><b>Argument:</b>
<pre>
struct pwc_whitebalance
{
	int mode;
	int manual_red, manual_blue;    /* read/write */
	int read_red, read_blue;        /* read/only */
};
</pre>
</p>

<p>The camera has built-in White Balance compensation; that is, it has the
ability to correct for different lighting conditions (outdoor, indoor,
artificial lighting, etc), by adjusting the gains for the red en blue pixels
(green is never affected). Normally you leave it in automatic mode, but in
certain circumstances you might want a fixed setting, or query the current
values. This is what VIDIOCPWCSAWB and VIDIOCPWCGAWB are for.</p>

<p><b>mode</b> can be one of these defined values:
<ul>
  <li>PWC_WB_AUTO
  <li>PWC_WB_MANUAL
  <li>PWC_WB_INDOOR
  <li>PWC_WB_OUTDOOR
  <li>PWC_WB_FL
</ul>

<p>I suppose these names speak for themselves, with the exception of
PWC_WB_FL: FL stands for fluorescent lighting, or tubes.</p>

<p>Only when mode = PWC_WB_MANUAL, the <b>manual_red</b> and
<b>manual_blue</b> parameters are valid; they are used to program the camera
with your own red and blue gain values; their range is 0..65535
(0x0..0xffff). In all other modes these parameters are ignored. The
<b>read_red</b> and <b>read_blue</b> parameters are never used with
VIDIOCPWCSAWB.</p>

<h3><a name="vidiocpwcgawb">VIDIOCPWCGAWB</a></h3>

<p><b>Brief:</b> Get Automatic White Balance</p>

<p><b>Argument:</b> See <a href="#vidiocpwcsawb">Set Automatic White Balance</a></p>

<p>This function is used to query the current Auto White Balance mode and
optionally the red and blue gain values of the camera. It takes a
<b>pwc_whitebalance</b> struct, which is filled with the <b>mode</b> (see
above). If mode == PWC_WB_MANUAL, the <b>manual_red</b> and
<b>manual_blue</b> parameters are set; if mode == PWC_WB_AUTO the
<b>read_red</b> and <b>read_blue</b> parameters are set. In any other mode
the *red and *blue parameters are not filled at all.</p>


<h3><a name="vidiocpwcgawbspeed">VIDIOCPWCGAWBSPEED</a> / <a name="vidiocpwcsawbspeed">VIDIOCSAWBSPEED</a></h3>

<p><b>Brief:</b> Control speed of Automatic White Balance</p>

<p><b>Argument:</b>
<pre>
struct pwc_wb_speed
{
	int control_speed;
	int control_delay;
};
</pre>
</p>

<p><b>Supported:</b> PWC 8.6 and above.</p>


<p>These two functions are also part of the Auto White Balance mode of the
cameras, but are separated from the SAWB/GAWB calls since they are probably
not used much and this way I don't break the pwc_whitebalance struct. </p>

<p><b>control_speed</b> and <b>control_delay</b> parameters determine how
fast the camera reacts to changes in lighting when it is in automatic mode,
and how long it waits before it starts adjusting the red/blue gains. There
are no absolute times (it seems to be related to the number of frames
processed). The range of both numbers is 1..65535 (0x1..0xffff); a setting
of 0 leaves the settings untouched.</p>

<p>NB: the term 'speed' is a bit misleading; in fact, the higher the number,
the slower it reacts.</p>




<h3><a name="vidiocpwcsled">VIDIOCPWCSLED</a> / <a name="vidiocpwcgled">VIDIOCPWCGLED</a></h3>

<p><b>Brief:</b> Control and query the LED on the camera.</p>

<p><b>Argument:</b>
<pre>
struct pwc_leds
{
	int led_on;                     /* Led on-time; range = 0..25000 */
	int led_off;                    /* Led off-time; idem. */
};
</pre>
</p>

<p><b>Supported:</b> Only by ToUCam series (730 to 750).
Not every OEM cam based on this chipset supports this feature!</p>

<p>These 2 functions may sound less functional, but they can be useful. With
the VIDIOCPWCSLED function you can determine if the LED on the camera should
be on while it is in use (the default), off (handy for survaillance cams),
or blink (draws extra attention). VIDIOCPWCGLED returns the current
settings.</p>

<p>The time is specified in milliseconds, with a resolution of 100 ms; the
maximum is 25500 (about 25 seconds; a <u>very</u> long blinking time :-)). If
you want a LED that is always on, specify a <b>led_on</b> time &gt;= 100, and a
<b>led_off</b> time of 0. To get a a dark LED, specify a <b>led_on</b> time
of 0, and <b>time_off</b> may be &gt;= 100. For a blinking LED, set both
<b>led_on</b> and <b>led_off</b> to a value larger than 100.</p>

<p>Example code:</p>

<p><pre>
	#include &quot;pwc-ioctl.h&quot;

	.....

	struct pwc_leds LED;

	/* Turn LED off */
	LED.led_on = 0;
	LED.led_off = 0;
	ioctl(fd, VIDIOCPWCSLED, &amp;LED);

	/* Turn LED on solid */
	LED.led_on = 100;
	LED.led_off = 0;
	ioctl(fd, VIDIOCPWCSLED, &amp;LED);

	/* Blinking LED, 1 second interval, 20% duty cycle */
	LED.led_on = 200;
	LED.led_off = 800;
	ioctl(fd, VIDIOCPWCSLED, &amp;LED);
</pre></p>



<p><b>Note 1:</b> There is a parameter that can be specified when loading
the pwc module that also controls the LED time; this is the default
timing.</p>

<p><b>Note 2:</b> When the video device is closed, the LED is always turned
off. This is done by the driver.</p>



<h3><a name="vidiocpwcscontour">VIDIOCPWCSCONTOUR</a> / <a name="vidiocpwcgcontour">VIDIOCPWCGCONTOUR</a></h3>

<p><b>Brief:</b> Control and query electronic sharpness</a>

<p><b>Argument:</b> integer</p>

<p><b>Supported:</b> PWC 8.6 and up</p>

<p>This is an interesting functions: it can blur or sharpen the image from
the cam. This is done electronically, not by actually focussing the camera
(you have to do this manually by rotating the canule, thus screwing the lens
in or out). But it produces some interesting results: you can blur the image
a bit to get a soft-focus effect, or sharpen it to enhance the edges in the
image.</p>

<p>Don't overdo it, though. Sharpening the image also introduces more noise,