api.html

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

makes it harder to compress the image for videoconferencing and makes the
image look unnatural. And of course it can't correct for a camera that is
out of focus. If you blur too much, people who are watching the images will
tend to clean their glasses a lot or advise you to get a better webcam
:-)</p>

<p>A negative argument indicates the webcam determines the contour value
automatically (this value cannot be queried); a positive value in the range
0..65535 is will set the contour value manually. Low values will give a
blurred image, a high value sharpens it.</p>




<h3><a name="vidiocpwcsbacklight">VIDIOCPWCSBACKLIGHT</a> / <a name="vidiocpwcgbacklight">VIDIOCPWCGBACKLIGHT</a></h3>

<p><b>Brief:</b> Backlight compensation mode</a>

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

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


<p>In case the object you are viewing with the camera is in front of a bright
background (for example, a window or some bright lights), the automatic
exposure unit may make the image too dark. In that case you can turn the
backlight compensation mode off; setting a value if 0 will just do that. Any
other value means the backlight compensation mode is (turned) on.</p>




<h3><a name="vidiocpwcsflicker">VIDIOCPWCSFLICKER</a> / <a name="vidiocpwcgflicker">VIDIOCPWCGFLICKER</a></h3>

<p><b>Brief:</b> Anti-flicker mode</a>

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

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


<p>Due to the different frequencies of the webcam, monitor refresh rate and
the electrical power supply, the intensity of the image may 'pulsate' which
is quite annoying to watch. The Philips cams have a way to suppress this
(don't ask me how...) This function turns that feature on or off. A value of
0 turns if off, any other value means its on; simple as that.</p>




<h3><a name="vidiocpwcsdynnoise">VIDIOCPWCSDYNNOISE</a> / <a name="vidiocpwcgdynnoise">VIDIOCPWCGDYNNOISE</a></h3>

<p><b>Brief:</b> Control the dynamic noise reduction mode</a>

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

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


<p>One of the more advanced features of the camera. It has an internal noise
reduction algorithm (probably some temporal filtering), and works quite well
to smooth out noise in the images. It can be set from None (value = 0) to
High (value = 3).</p>

<h3><a name="vidiocpwcgrealsize">VIDIOCPWCGREALSIZE</a></h3>

<p><b>Brief:</b> Get the image size as produced by the camera</a>

<p><b>Argument:</b>
<pre>
struct pwc_imagesize
{
	int width;
	int height;
};
</pre></p>

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

<p>Sometimes it's handy to know the real size of the image that is delivered
by the camera (see this <a href="faq.html#Q3">chart</a>), because PWC
pads any image size that is not directly supported with a gray border (doing
interpolation in the kernel is a no-no). This function will tell what the
'real' current image size is, in pixels.</p>




<h3><a name="vidiocpwcmpt">VIDIOCPWCMPT....</a></h3>

<p>Before you delve into the VIDIOCPWCMPT functions below, there's some general information
you should know.</p>

<p>The Logitech QuickCam Orbit or Sphere (they are the same cam, just named differently)
has two built-in motors with which you can rotate the camera. One motor rotates
the camera horizontally (called panning), the other vertically (called tilting). This
is currently the only camera supported by PWC which has this feature. In addition, the
cam has an extension rod which raises the bulb with the actual cam about 30 cm above your
desk, earning it the nickname &quot;cam-on-a-stick&quot; (in a bun).</p>

<p>The cam can swivel about 70 degrees left and right from its home position, and 30 degrees
up and down, giving you a total view of about 180 degrees horizontally and 120 degrees
vertically. It's perfect for remote (security) operation without requiring additional
hardware.</p>

<p>Below, the ioctl() commands are described which allow you to rotate the camera.
When the camera does not have motorized pan &amp; tilt, the ioctl() will
return an errno of -ENXIO (no such device or address). The safest way to probe for this
feature is by using VIDIOCPWCMPTGRANGE (get range), as this does not affect the cams position
or operation, plus you get some useful information in case the cam does have the feature.</p>

<p>All angles described below are in degrees * 100, even though the cam cannot be set
this accurate (it's best positioning accuracy is about 0.08 degrees; far more than you'll
ever need). Also, there's mention of a zoom factor; this cam does not have hardware zoom,
but I'd like to be prepared in case any future model cam will have this.</p>

<p>For panning, positive angles are clockwise from the home position, and
for tilting positive angles are up.</p>

<p>You need PWC 8.12 or higher in order to call these functions; previous versions
will return an ENOIOCTLCMD error (in which case you know the PWC driver you're talking
to is too old).

<h3><a name="vidiocpwcmptreset">VIDIOCPWCMPTRESET</a></h3>

<p><b>Brief:</b> Reset motorized pan/tilt position</p>

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

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

<p>This will reset the webcam to it's home position, which is horizontally halfway
between its outermost left and right position and looking ahead level. The cam
will perform a reset by first going to its topleft position, and then moving forward
to its home position.</p>

<p>
<table border=1 width=500>
<tr>
  <th>bits</th>
  <td align=center>31..2</td>
  <td align=center>1</td>
  <td align=center>0</td>
</tr>
<tr>
  <th>function</th>
  <td align=center>Unused; set to 0.</td>
  <td align=center>reset tilt position</td>
  <td align=center>reset pan position</td>
</tr>
</table>
</p>

<p>After this call, the driver will set its internal angle position to 0,0.</p>


<h3><a name="vidiocpwcmptgrange">VIDIOCPWCMPTGRANGE</a></h3>

<p><b>Brief:</b> Get pan/tilt range</p>

<p><b>Argument:</b>
<pre>
struct pwc_mpt_range
{
	int pan_min, pan_max;
	int tilt_min, tilt_max;
	int zoom_min, zoom_max;
}
</pre></p>

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

<p>This function will query the driver for the minimum and maximum angles by
which the cam can be rotated. All angles are expressed in degrees * 100.</p>

<p>These angles have been derived from the documentation and some experimentation.
Trying to set an angle beyond these bounds will return in an -ERANGE error code.</p>

<p>The (hardware) zoom function is currently not available on any camera, so -1,-1
is returned in the zoom_min and zoom_max fields.</p>




<h3><a name="vidiocpwcmptsangle">VIDIOCPWCMPTSANGLE</a></h3>

<p><b>Brief:</b> Set pan/tilt position</p>

<p><b>Argument:</b><pre>
struct pwc_mpt_angles
{
	int absolute;	/* write-only */
	int pan;	/* degrees * 100 */
	int tilt	/* degrees * 100 */
}
</pre></p>

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

<p>With this command you order the Orbit/Sphere to rotate. You can rotate to an
absolute position or relative to the current one. In all cases, trying to rotate
beyond the allowed angles will return an -ERANGE error.</p>

<p>Note: do not send another VIDIOCPWCMPGSANGLE command until the last one has
finished (either succesfully or with an error). Use the VIDIOCPWCMPTGSTATUS call
to determine when the camera is ready (see below).</p>



<h3><a name="vidiocpwcmptgangle">VIDIOCPWCMPTGANGLE</a></h3>

<p><b>Brief:</b> Get pan/tilt position</p>

<p><b>Argument:</b> struct pwc_mpt_angles</p>

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

<p>Query the current angle of the camera. The angle is not really queried
from the camera, as it does not have position sensors. Rather, the last position
set with VIDIOCPWCMPTSANGLE or VIDIOCPWCMPTRESET is remembered. It is therefor
entirely possible that after several movements the camera is not quite looking
at where you think it is. But there's always VIDIOCPWCMPTRESET, of course :-)</p>



<h3><a name="vidiocpwcmptstatus">VIDIOCPWCMPTSTATUS</a></h3>

<p><b>Brief:</b> Query pan/tilt status</p>

<p><b>Argument:</b> <pre>
struct pwc_mpt_status
{
	int status;
	int time_pan;
	int time_tilt;
}
</pre></p>

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

<p>With this function you request the MPG status of the camera; while the camera
is moving these status bits will change.<br/>

<table border=1 width=500>
<tr>
  <th>Bits of 'status'</th>
  <td align=center>31...3</td>
  <td align=center>2</td>
  <td align=center>1</td>
  <td align=center>0</td>
</tr>
<tr>
  <th>Function</th>
  <td align=center>Unused</td>
  <td align=center>General status bit</td>
  <td align=center>Tilt status</td>
  <td align=center>Pan status</td>
</tr>
</table>

The General status bit is 1 when the command was processed successfully internally; a 0 signals
a time out. For the Pan and Tilt status, a 1 means the command completed succesfully; a 0 means busy, or hard stop
error (i.e. hitting one of the end borders).<br/>
When setting the angle or doing a reset, you have to poll the status regularely
until the command completes or returns an error. The following table clarifies the various bit
combinations.</p>

<P>
<table border="1">
<tr>
  <th>0x00</th>
  <td>Command running</td>
</tr>
<tr>
  <th>0x01</th>
  <td>Timeout</td>
</tr>
<tr>
  <th>0x02</th>
  <td>Timeout</td>
</tr>
<tr>
  <th>0x03</th>
  <td>Timeout</td>
</tr>
<tr>
  <th>0x04</th>
  <td>Both axis hit hard stop</td>
</tr>
<tr>
  <th>0x05</th>
  <td>Tilt hit hard stop</td>
</tr>
<tr>
  <th>0x06</th>
  <td>Pan hit hard stop</td>
</tr>
<tr>
  <th>0x07</th>
  <td>Command completed succesfully</td>
</tr>
</table>
</p>

<p>Do not poll too quickly; an interval of 250 to 500 ms should be fine. The camera usually completes
rotating within 2 seconds.</p>

<p>I'm not 100% sure what the <b>time_pan</b> and <b>time_tilt</b> parameters contain;
I think they hold the time in milliseconds that the motor for that particular axis is
running/has been running.</p>









<h3>There's more to come...</h3>

<p>As I implement more features, I will describe them here.





<p><a href="index.html">Back to main page</a>

<hr/>

<p>[1]: Yes, 59.94 Hz, not 60 Hz, but for all practical purposes 60 Hz will
do.


<p><i>2004-06-17 - Nemosoft Unv</i></p>

</body>
</html>