api.html

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

  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
</tr>
<tr>
  <th>QSIF<br>160x120</th>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
</tr>
<tr>
  <th>QCIF<br>176x144</th>
  <td>&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
</tr>
<tr>
  <th>SIF<br>320x240</th>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
</tr>
<tr>
  <th>CIF<br>352x288</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
</tr>
<tr>
  <th>VGA<br>640x480</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td bgcolor="#00cc00">&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
  <td>&nbsp;</td>
</tr>
</table>

<p>You may notice that most sizes are derived from two main image sizes:
all SIF formats are subformats of 640x480, and all CIF sizes (except
subQCIF) are derived from 352x288 (which is a standard size for video
conferencing).

<p>The VIDIOCSWIN call is also used to set the frame rate. A TV grabber card
doesn't have this of course, since its 'framerate' is dictated by the video
signal (50 Hz for PAL/SECAM, and 59.94 Hz for NTSC <sup>1</sup>). The frame
rate is defined in the higher 16 bits of the 'flags' field, since some of
the lower 16 bits are already used by Video4Linux:

<p>
<table border=1 width=500>
<tr>
  <th>bits</th>
  <td align=center>31..23</td>
  <td align=center>21..16</td>
  <td align=center>15..0</td>
</tr>
<tr>
  <th>function</th>
  <td align=center>None; set to 0.</td>
  <td align=center>framerate</td>
  <td align=center>reserved for V4L</td>
</tr>
</table>

<p>So there are 6 bits for the framerate, giving a maximum framerate of 63.
The highest 10 bits are undefined and should be 0.

<p>Normally the framerate is a number between 4 and 30, but if you set the
framerate bits to 0, the current framerate is unaffected. This way the
VIDIOCSWIN call is backwards compatible with current applications who
normally set this field to 0, or use the previous value from a VIDIOCGWIN
call. However, do not set a framerate in a device that doesn't support it
and hope the driver will just ignore it. It won't, and you'll get barfed
upon.

<p>To set a framerate of 3.75 or 7.5 Hz, use a framerate of 4 resp. 8. You
can use any value between 5 (4) and 30, The driver will choose the nearest
framerate. For critical applications, use a VIDIOCGWIN call to query what
the real framerate is!

<p>Use these defines from <code>pwc-ioctl.h</code> to filter out or set the
framerate settings:

<p>
<dl>
<dt>PWC_FPS_SHIFT
  <dd>Bit shift for the framerate bits.

<dt>PWC_FPS_MASK
  <dd>Bit mask for both the framerate and snapshot setting. If flags &
      PWC_FPS_FRMASK != 0, and you detected a Philips cam, then you can
      safely use the framerate setting.

<dt>PWC_FPS_FRMASK
  <dd>Bit mask for for the framerate setting.

</dl>

<p>Example code:

<p>
<pre>
   struct video_window vwin;

   ioctl(cam_fd, VIDIOCGWIN, &vwin);
   if (vwin.flags & PWC_FPS_FRMASK)
     printf("Camera has framerate setting; current framerate: %d fps\n", (vwin.flags & PWC_FPS_FRMASK) >> PWC_FPS_SHIFT);
   else
     return;

   /* Set new framerate */
   vwin.flags &= ~PWC_FPS_FRMASK;
   vwin.flags |= (new_frame_rate << PWC_FPS_SHIFT);

   ioctl(cam_fd, VIDIOCSWIN, &vwin);
</pre>

<p>You may wonder why I stashed the framerate setting in the VIDIOCSWIN
call, and not made it a <a href="#private">private</a> <span
class="function">ioctl()</span> call. Well, the reason is that some
combinations of size and framerate are not allowed, and if size and
framerate were set in 2 separate calls, this would make it difficult to
'reach' some of these combinations. Now, you immediately know the setting
was not valid because <span class="function">ioctl()</span> returned
-EINVAL.


<h2><a name="palette">Palettes</a></h2>

<p>One of the greatest sources of confusion (and irritation for programmers,
I might add), is the palette of colour images returned by a V4L device. A
palette basicly tells the driver in which format you would like the image
returned. There are 3 main formats in use these days:

<ul>
  <li>RGB, which has 3 channels for Red, Green and Blue.
  <li>YUV, which has one luminance (brightness) channel and 2 colour
      channels.
  <li>YIQ, which also has one luminance channel, but differently defined
      colour channels.
</ul>

<p>All formats can be converted to another without loss (in other words,
none is 'better' than the others). I won't go into details as to why these
formats exist and what their properties are, but it suffices to say that RGB
is best for viewing on a monitor, and YUV/YIQ is better suited for
compression and video transmission.

<p>The biggest problem format so far is the RGB format, since nobody seems
to agree in which order it should be delivered: RGB suggests Red first, then
Green, and finally Blue. But of course, some had to do it differently and
put Blue first, then Green and finally Red (mind you, Green stays where it
is). The endresult is that you look like a Smurf if you get the RGB/BGR
order wrong :-)

<p>The consensus among webcam driver programmers these days is to use the
BGR format, esp. since this matches better with what TV grabber cards can
deliver. Also, the YUV format is used by virtually all grabber cards and
most webcam drivers, though with some small variations.

<p>The Philips webcam driver (as of version 7.0) <b>only</b> delivers the
YUV420P palette, or in techno speak YUV 4:2:0 planar. However, for
completeness I list the other palettes in use among webcams as well.

<br>The first byte is at offset 0, the second byte at offset 1, etc... The
last column lists the number of bytes per pixel (with this, you can
calculate how large your image buffer must be).</p>

<p>
<table border=1 width=500>
<tr>
  <th align=left>VIDEO_PALETTE_RGB24</th>
  <td>BGRB GRBG RBGR ....</td>
  <td>3</td>
</tr>
<tr>
  <th align=left>VIDEO_PALETTE_RGB24 | 0x80</th>
  <td>RGBR GBRG BRGB ....</td>
  <td>3</td>
</tr>
<tr>
  <th align=left>VIDEO_PALETTE_RGB32</th>
  <td>BGR0 BGR0 BGR0 ....</td>
  <td>4</td>
</tr>
<tr>
  <th align=left>VIDEO_PALETTE_RGB32 | 0x80</th>
  <td>RGB0 RGB0 RGB0 ...</td>
  <td>4</td>
</tr>
<tr>
  <th align=left>VIDEO_PALETTE_YUYV<br>
    VIDEO_PALETTE_YUV422</th>
  <td>YUYV YUYV YUYV ...</td>
  <td>2</td>
</tr>
<tr>
  <th align=left>VIDEO_PALETTE_YUV420</th>
  <td>Even lines: YYYY UU YYYY UU ....<br>
      Odd lines: YYYY VV YYYY VV ....</td>
  <td>1.5</td>
</tr>
<tr>
  <th align=left>VIDEO_PALETTE_YUV420P</th>
  <td>YYYY .... YYYY<br>
      YYYY .... YYYY<br>
      UU .. UU<br>
      VV .. VV<br>
      Planar format: First all Y (luminance) values are written, exactly
      width * height bytes. This is followed by the U values, 1/4th of the
      number of Y pixels, followed by the same amount of V values. The U and
      V values are decimated by 2 in both horizontal and vertical direction.
      In other words: for every 4 Y values there is one U and one V value.
      Conversely, each U and V value apply to a block of 2x2 Y values.
  </td>
  <td>1.5</td>
</table>

<p>Note: each channel takes up one byte; the Philips driver does not support
the 'packed' formats or the grayscale format.
<br>The fourth byte of the 32 bit palettes is a '0', and does not change
places in the RGB format!
<br>The YUV420 palette is the camera's native palette; the U and V values
are interleaved between the Y values on alternating even and odd lines. So
you should always process 2 lines simultaneously.

<p>Oh yes: the only way to find out which palettes are supported is to try
them all out one bye one with a VIDIOCSPICT call. Another glaring omission
from the V4L API....


<h2><a name="private">Private calls</a></h2>

<p>Apart from the (backwards compatible) calls defined in the Video4Linux
API, the driver has a number of extra <span class="function">ioctl()</span>
calls for Philips specific stuff. They are called 'private' because they use
the number range marked 'private' in videodev.h. Be careful to check if you
<a href="#detect">are really talking</a> to a Philips webcam, because other
drivers have their own set of private calls and you never know what may
happen! These <span class="function">ioctl()</span> calls are defined in the
pwc-ioctl.h file.

<p>All <span class="function">ioctl()</span> calls below describe the
argument they take; some take no argument at all, others take an integer or
a structure. Note that the 3rd argument to an <span
class="function">ioctl()</span> call is virtually always the address of a variable,
so use the <b>&amp;</b> operator (this also means you cannot pass constants
to ioctl() directly: you must place them in a variable first).

<p>Of course, functions get added and removed; however, this is easy to
detect. If the private function is not implemented, the <span
class="function">ioctl()</span> call will return -ENOIOCTLCMD. Any other
value is an indication the function is available but failed at some other
point (not supported by the camera, for example; -EFAULT probably means you
forgot the <b>&amp;</b> with your argument).