📄 api.html
字号:
<html><head><title>Philips USB webcam API</title><LINK REL="STYLESHEET" HREF="webcam.css" TYPE="text/css"></head><body><h1>API</h1><p>This document describes how to properly detect and use the extendedfeatures of the Philps USB webcams, should you wish to write or enhance yourown program.<h3>Table of contents</h3><ol> <li><a href="#intro">Introduction</a> <li><a href="#req">Requirements</a> <li><a href="#detect">Detection</a> <li><a href="#select">Supported functions</a> <li><a href="#add">Additions to the 'standard' Video4Linux API</a> <ul> <li><a href="#vidiocchan">VIDIOCSCHAN</a> <li><a href="#vidiocpict">VIDIOCGPICT / VIDIOCSPICT</a> <li><a href="#vidiocwin">VIDIOCGWIN / VIDIOCSWIN</a> </ul> <li><a href="#palette">Palettes</a> <li><a href="#private">Private calls</a> <ul> <li><a href="#vidiocpwcprobe">VIDIOCPWCPROBE</a> (probe for Philips cam)</li> <li><a href="#vidiocpwcsuser">VIDIOCPWCSUSER</a> (save user settings)</li> <li><a href="#vidiocpwcruser">VIDIOCPWCRUSER</a> (restore user settings)</li> <li><a href="#vidiocpwcfactory">VIDIOCPWCFACTORY</a> (restory factory settings)</li> <li><a href="#vidiocpwcscqual">VIDIOCPWCSCQUAL</a> (set compression quality)</li> <li><a href="#vidiocpwcgcqual">VIDIOCPWCGCQUAL</a> (get compression quality)</li> <li><a href="#vidiocpwcsagc">VIDIOCPWCSAGC</a> (set Automatic Gain Control)</li> <li><a href="#vidiocpwcgagc">VIDIOCPWCGAGC</a> (get Automatic Gain Control)</li> <li><a href="#vidiocpwcsshutter">VIDIOCPWCSSHUTTER</a> (set Shutter speed)</li> <li><a href="#vidiocpwcsawb">VIDIOCPWCSAWB</a> (set Auto White Balance)</li> <li><a href="#vidiocpwcgawb">VIDIOCPWCGAWB</a> (get Auto White Balance)</li> <li><a href="#vidiocpwcsawbspeed">VIDIOCPWCSAWBSPEED</a> (set more Auto White Balance parameters)</li> <li><a href="#vidiocpwcgawbspeed">VIDIOCPWCGAWBSPEED</a> (get more Auto White Balance parameters)</li> <li><a href="#vidiocpwcsled">VIDIOCPWCSLED</a> (control LED on camera)</li> <li><a href="#vidiocpwcgled">VIDIOCPWCGLED</a> (query status LED)</li> <li><a href="#vidiocpwcscontour">VIDIOCPWCSCONTOUR</a> (control image sharpness electronically)</li> <li><a href="#vidiocpwcgcontour">VIDIOCPWCGCONTOUR</a> (query electronic image sharpness)</li> <li><a href="#vidiocpwcsbacklight">VIDIOCPWCSBACKLIGHT</a> (set background compensation mode)</li> <li><a href="#vidiocpwcgbacklight">VIDIOCPWCGBACKLIGHT</a> (get background compensation mode)</li> <li><a href="#vidiocpwcsflicker">VIDIOCPWCSFLICKER</a> (set flicker-less mode)</li> <li><a href="#vidiocpwcgflicker">VIDIOCPWCGFLICKER</a> (get flicker-less mode)</li> <li><a href="#vidiocpwcsdynnoise">VIDIOCPWCSDYNNOISE</a> (set dynamic noise reduction)</li> <li><a href="#vidiocpwcgdynnoise">VIDIOCPWCGDYNNOISE</a> (get dynamic noise reduction)</li> <li><a href="#vidiocpwcgrealsize">VIDIOCPWCGREALSIZE</a> (get image size as produced by the camera)</li> <li><a href="#vidiocpwcmpt">VIDIOCPWCMPT....</a> (some general info about motorized pan/tilt functions)</li> <li><a href="#vidiocpwcmptreset">VIDIOCPWCMPTRESET</a> (reset pan/tilt position)</li> <li><a href="#vidiocpwcmptgrange">VIDIOCPWCMPTGRANGE</a> (query pan/tilt range)</li> <li><a href="#vidiocpwcmptsangle">VIDIOCPWCMPTSANGLE</a> (set pan/tilt angle)</li> <li><a href="#vidiocpwcmptgangle">VIDIOCPWCMPTGANGLE</a> (get pan/tilt angle)</li> <li><a href="#vidiocpwcmptstatus">VIDIOCPWCMPTSTATUS</a> (get pan/tilt status)</li> </ul></ol><h2><a name="intro">Introduction</a></h2><p>You may wonder why there is a separate API (Application ProgrammingInterface) document for the Philips webcams. It uses the Video4Linux APIso that should be enough, right?</p><p>Well, not quite. The V4L document and interface is geared towards TVgrabber cards and not for webcams. Consequently it does not support somefeatures that webcams have, and vice versa. For example: the framerate ofthe Philips webcams can be set, while a TV card uses a fixed rate which isnot even controlled by the card, but by the video signal. And there are afew more differences.</p><p>Note that this document just describes the Philips cams; it could be thatother driver-developers will use the same kind of features in their webcamsand use this document as a reference. More likely, they will not :) Also, Itried to make sure my enhancements do not interfer with other programs andhow they 'talk' to a V4L device.</p><p>I assume you have the V4L document available, and know a bit of how toprogram with it. This documents also amends the V4L interface, since somethings have changed in the BTTV driver (you could consider this thereference upon which the V4L interface was designed), but not in thedocument.</p><h2><a name="req">Requirements</a></h2><p>If you want to program the Philips webcam you will need the file<b>pwc-ioctl.h</b> from your kernel source (somewhere around/usr/src/linux/drivers/usb); make sure you include an up-to-date versionin your program. This file lists a number of private <spanclass="function">ioctl()</span> calls and some useful #defines.</p><p>Second, you will have to program in a language that supports the <span class="function">ioctl()</span>call, like C, or has a C interface. Although it is possible to open thevideo device and simply start reading images from that, there's no way tomanipulate the device then.</p><p>You will need these includes at the top of your source file(s):</p><p><pre>#include <linux/videodev.h>#include <sys/ioctl.h>#include "pwc-ioctl.h"</pre></p><p>Note: all code fragments below are just snippets of code, and don'tcompile on their own. They are purely meant as an example.</p><h2><a name="detect">Detection</a></h2><p><b>Note:</b> as of PWC 8.6, the detection procedure will change slightly.The detection by name will be superseeded by a PROBE ioctl(). The mainreason is that so many different cameras are now supported by the driver, Idecided to include the "real" name in the device name. After all,it looks a bit weird if you buy a Logitech QuickCam 3000 Pro and it shows upon your system as a "Philips 730 webcam". So, together with thename change I've added an extra <a href="vidiocpwcprobe">VIDIOCPWCPROBE</a>call, which can be used to safely detect the presence of a Philips (compatible)webcam.</p><p>In order to remain backwards compatible, you should first check the namein the usual way; if that fails, use the PROBE ioctl(); if that succeeds,you are using a Philips cam. This change will make 'older' programs fail todetect the OEM models (the original Philips cams are still detected of coursesince they still follow the old naming scheme).</p><p>After you <span class="function">open()</span> the device, youuse the VIDIOCGCAP <span class="function">ioctl()</span> to get a <b>struct video_capability</b>which has a 'name' field. This name field is filled with eitther the followingpattern:<p><pre> Philips %d webcam</pre><p>where %d is the model number (645, 646, 675, 730, etc), or any of theother names (Samsung MPC-C10, Creative Labs Webcam 5, etc.). Now, ratherthan programming tons of names to match in your own tool (which would alwaysbe outdated), use the VIDIOCPWCPROBE call and see if it returns valid data.<p>Example (pseudo) code:<pre> struct video_capability vcap; struct pwc_probe probe; int type; bool IsPhilips; IsPhilips = FALSE; if (ioctl(cam_fd, VIDIOCGCAP, &vcap) < 0) return; if (sscanf(vcap.name, "Philips %d webcam", &type) == 1) IsPhilips = TRUE; else { /* No match yet; try the PROBE */ if (ioctl(cam_fd, VIDIOCPWCPROBE, &probe) == 0) { if (!strcmp(vcap.name, probe.name)) { IsPhilips = TRUE; type = probe.type; } } }</pre><p>Note: it is considered bad programming practice to write code specificfor one model; rather, try to make your program work for ALL Philipswebcams.</p><h2><a name="select">Supported functions</a></h2><p>The driver supports the following libc functions:<ul> <li><span class="function">select()</span> (and thus <span class="function">poll()</span> (or is it the other way around?))</li> <li><span class="function">read()</span> <li><span class="function">mmap()</span></ul><p>Although you can open the /dev/video device read-write, trying to <spanclass="function">write()</span> to the device will result in an error. Onlyone process can open the device at the same time.<p>You can do 'partial reads', that is, read the image in chunks. The lastchunk will be shorter if the image size isn't an exact multiple of the chunkbuffer. In other words: you will never read across an image border, readingthe first lines of the next image after the last lines of the current image.Of course you can also opt to read the image in one go.</p><p><span class="function">read()</span> will block until an image isavailable, unless you opened the device with O_NONBLOCK, in which case <spanclass="function">read()</span> will return -EAGAIN when no image isavailable. You are advised to use the <span class="function">select()</span>call (with only the bit in the 'readfs' set on).</p><p>In case you are using <span class="function">mmap()</span>, the <spanclass="function">select()</span> call will also return when an image isavailable.</p><h2><a name="add">Additions tot the 'standard' Video4Linux API</a></h2><p>In case you read the Video4Linux 1 standard, there are a few things youshould be aware of... First, as stated before, the Video4Linux API is heavilygeared towards TV grabber cards and assumes a few things which are simplynot true for webcams. But we can work around that.</p><p>Second, it's incomplete as it misses a few important <spanclass="function">ioctl()</span> calls, like querying the current inputsetting (most TV cards have multiple inputs, one for tuner, one for S-VHS,etc). But there is no way to ask which input has currently been selected.The same applies to the tuner.</p><p>Third, the API makes a distinction between input and tuners, which isokay. You can query which inputs there are, and which tuners there are, butnot which tuner is connected to which input. This is usally not a problem,since most cards will only have one tuner attached to one input, but it'sstill an oversight.</p><p>After this small rant, let's get started :-)</p><h3><a name="vidiocchan">VIDIOCSCHAN</a></h3><p>The spec says this ioctl call takes an integer argument, but the 'bttv'driver (which acts as a reference for all video devices, it seems) takesa <b>struct video_channel</b>, just like its counterpart VIDIOCGCHAN. Thisactually makes sense as the <b>struct video_channel</b> also has a field forthe TV norm.</p><p>Note that this change is not specific for the Philips webcams, but to all(most?) video devices.</p><h3><a name="vidiocpict">VIDIOCGPICT / VIDIOCSPICT</a></h3><p>The 'whiteness' field in <b>struct video_picture</b> is used for the gammasetting of the cameras. The spec says it is only for black & white cameras, but that makes very little sense. So I use it for the gamma correction. Theother three settings: brightness, contrast and colour (saturation) work asexpected, although some older models do not actually have colour saturation,so this settings does nothing for them.</p><p>When a setting is not supported, 0xFFFF is returned in the field with theVIDIOGPICT call. This value is not returned during normal operation.</p><p>Note that the <b>struct video_picture</b> also has a<a href="#palette">palette</a> field, which is described in aseparate chapter below. A value of 0 leaves the current palette intact.</p><h3><a name="vidiocwin">VIDIOCGWIN / VIDIOCSWIN</a></h3><p>Starting from Release 6.2, the Philips driver now supports any image sizebetween the minimum and maximum size. For image sizes that are not an'integral' image size directly supported by the camera, the image is nowpadded with a gray border.</p><p>Note: the driver only pads the image; it selects a format that is smalleror equal to the requested size; it does not crop an image that is only a bitlarger than the requested current image.</p><p>However, the best way to program (and not just with webcams!) is to do aVIDIOCGWIN call right after VIDIOCSWIN, so you know exactly what resolutionwill be used. For example, a TV card may still decide to use the nearestmultiple of 2, 4 or 8 pixels of the desired size, simply because thehardware is limited to such sizes. This is a programming strategy of minethat I call "the hardware knows best".</p><p>Here's a table which lists all supported resolutions on all cameramodels:<p><table border="1"><tr> <th rowspan="2" valign="bottom">Size</th> <th colspan="8">PCA 645/646 & VC010</th> <th rowspan="8" width="15"> </td> <th colspan="6">PCVC 675/680/690</th> <th rowspan="8" width="15"> </th> <th colspan="6">PCVC 730/740/750</th></tr><tr> <th width="30">3.75</th> <th width="30">5</th> <th width="30">7.5</th> <th width="30">10</th> <th width="30">12</th> <th width="30">15</th> <th width="30">20</th> <th width="30">24</th> <th width="30">5</th> <th width="30">10</th> <th width="30">15</th> <th width="30">20</th> <th width="30">25</th> <th width="30">30</th> <th width="30">5</th> <th width="30">10</th> <th width="30">15</th> <th width="30">20</th> <th width="30">25</th> <th width="30">30</th></tr><tr> <th>sQCIF<br>128x96</th> <td> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td bgcolor="#00cc00"> </td> <td> </td> <td> </td> <td> </td>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -