> > Nonsense. The description of VIDIOCMCAPTURE and VIDIOCSYNC in API.html is
> > unclear, unexact, doubtful.
>
> I'm talking about the API itself, not the text on the API.html page.
> Maybe I should update my Programming-FAQ (in the xawtv tarball), put
> it into API.html and mail Alan a diff ...
Ok, here we go. Comments?
Gerd
==============================[ cut here ]==============================
--- linux-2.4.18-rc2/Documentation/video4linux/API.html Thu Feb 21 14:21:58 2002
+++ linux/Documentation/video4linux/API.html Thu Feb 21 15:01:55 2002
@@ -329,16 +329,35 @@
<TR><TD><b>offsets</b><TD>The offset of each frame</TD>
</TABLE>
<P>
-Once the mmap has been made the VIDIOCMCAPTURE ioctl sets the image size
-you wish to use (which should match or be below the initial query size).
-Having done so it will begin capturing to the memory mapped buffer. Whenever
-a buffer is "used" by the program it should called VIDIOCSYNC to free this
-frame up and continue. <em>to add:</em>VIDIOCSYNC takes the frame number
-you are freeing as its argument. When the buffer is unmapped or all the
-buffers are full capture ceases. While capturing to memory the driver will
-make a "best effort" attempt to capture to screen as well if requested. This
-normally means all frames that "miss" memory mapped capture will go to the
-display.
+Once the mmap has been made the VIDIOCMCAPTURE ioctl starts the
+capture to a frame using the format and image size specified in the
+video_mmap (which should match or be below the initial query size).
+When the VIDIOCMCAPTURE ioctl returns the frame is <em>not</em>
+captured yet, the driver just instructed the hardware to start the
+capture. The application has to use the VIDIOCSYNC ioctl to wait
+until the capture of a frame is finished. VIDIOCSYNC takes the frame
+number you want to wait for as argument.
+<p>
+It is allowed to call VIDIOCMCAPTURE multiple times (with different
+frame numbers in video_mmap->frame of course) and thus have multiple
+outstanding capture requests. A simple way do to double-buffering
+using this feature looks like this:
+<pre>
+/* setup everything */
+VIDIOCMCAPTURE(0)
+while (whatever) {
+ VIDIOCMCAPTURE(1)
+ VIDIOCSYNC(0)
+ /* process frame 0 while the hardware captures frame 1 */
+ VIDIOCMCAPTURE(0)
+ VIDIOCSYNC(1)
+ /* process frame 1 while the hardware captures frame 0 */
+}
+</pre>
+<p>
+While capturing to memory the driver will make a "best effort" attempt
+to capture to screen as well if requested. This normally means all
+frames that "miss" memory mapped capture will go to the display.
<P>
A final ioctl exists to allow a device to obtain related devices if a
driver has multiple components (for example video0 may not be associated
