diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/io.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 1545 |
1 files changed, 0 insertions, 1545 deletions
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml deleted file mode 100644 index 21a3dde8f95d..000000000000 --- a/Documentation/DocBook/media/v4l/io.xml +++ /dev/null @@ -1,1545 +0,0 @@ - <title>Input/Output</title> - - <para>The V4L2 API defines several different methods to read from or -write to a device. All drivers exchanging data with applications must -support at least one of them.</para> - - <para>The classic I/O method using the <function>read()</function> -and <function>write()</function> function is automatically selected -after opening a V4L2 device. When the driver does not support this -method attempts to read or write will fail at any time.</para> - - <para>Other methods must be negotiated. To select the streaming I/O -method with memory mapped or user buffers applications call the -&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined -yet.</para> - - <para>Video overlay can be considered another I/O method, although -the application does not directly receive the image data. It is -selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. -For more information see <xref linkend="overlay" />.</para> - - <para>Generally exactly one I/O method, including overlay, is -associated with each file descriptor. The only exceptions are -applications not exchanging data with a driver ("panel applications", -see <xref linkend="open" />) and drivers permitting simultaneous video capturing -and overlay using the same file descriptor, for compatibility with V4L -and earlier versions of V4L2.</para> - - <para><constant>VIDIOC_S_FMT</constant> and -<constant>VIDIOC_REQBUFS</constant> would permit this to some degree, -but for simplicity drivers need not support switching the I/O method -(after first switching away from read/write) other than by closing -and reopening the device.</para> - - <para>The following sections describe the various I/O methods in -more detail.</para> - - <section id="rw"> - <title>Read/Write</title> - - <para>Input and output devices support the -<function>read()</function> and <function>write()</function> function, -respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in -the <structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> - - <para>Drivers may need the CPU to copy the data, but they may also -support DMA to or from user memory, so this I/O method is not -necessarily less efficient than other methods merely exchanging buffer -pointers. It is considered inferior though because no meta-information -like frame counters or timestamps are passed. This information is -necessary to recognize frame dropping and to synchronize with other -data streams. However this is also the simplest I/O method, requiring -little or no setup to exchange data. It permits command line stunts -like this (the <application>vidctrl</application> tool is -fictitious):</para> - - <informalexample> - <screen> -> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 -> dd if=/dev/video of=myimage.422 bs=202752 count=1 -</screen> - </informalexample> - - <para>To read from the device applications use the -&func-read; function, to write the &func-write; function. -Drivers must implement one I/O method if they -exchange data with applications, but it need not be this.<footnote> - <para>It would be desirable if applications could depend on -drivers supporting all I/O interfaces, but as much as the complex -memory mapping I/O can be inadequate for some devices we have no -reason to require this interface, which is most useful for simple -applications capturing still images.</para> - </footnote> When reading or writing is supported, the driver -must also support the &func-select; and &func-poll; -function.<footnote> - <para>At the driver level <function>select()</function> and -<function>poll()</function> are the same, and -<function>select()</function> is too important to be optional.</para> - </footnote></para> - </section> - - <section id="mmap"> - <title>Streaming I/O (Memory Mapping)</title> - - <para>Input and output devices support this I/O method when the -<constant>V4L2_CAP_STREAMING</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two -streaming methods, to determine if the memory mapping flavor is -supported applications must call the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_MMAP</constant>.</para> - - <para>Streaming is an I/O method where only pointers to buffers -are exchanged between application and driver, the data itself is not -copied. Memory mapping is primarily intended to map buffers in device -memory into the application's address space. Device memory can be for -example the video memory on a graphics card with a video capture -add-on. However, being the most efficient I/O method available for a -long time, many other drivers support streaming as well, allocating -buffers in DMA-able main memory.</para> - - <para>A driver can support many sets of buffers. Each set is -identified by a unique buffer type value. The sets are independent and -each set can hold a different type of data. To access different sets -at the same time different file descriptors must be used.<footnote> - <para>One could use one file descriptor and set the buffer -type field accordingly when calling &VIDIOC-QBUF; etc., but it makes -the <function>select()</function> function ambiguous. We also like the -clean approach of one file descriptor per logical stream. Video -overlay for example is also a logical stream, although the CPU is not -needed for continuous operation.</para> - </footnote></para> - - <para>To allocate device buffers applications call the -&VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer -type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. -This ioctl can also be used to change the number of buffers or to free -the allocated memory, provided none of the buffers are still -mapped.</para> - - <para>Before applications can access the buffers they must map -them into their address space with the &func-mmap; function. The -location of the buffers in device memory can be determined with the -&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the -<structfield>m.offset</structfield> and <structfield>length</structfield> -returned in a &v4l2-buffer; are passed as sixth and second parameter to the -<function>mmap()</function> function. When using the multi-planar API, -&v4l2-buffer; contains an array of &v4l2-plane; structures, each -containing its own <structfield>m.offset</structfield> and -<structfield>length</structfield>. When using the multi-planar API, every -plane of every buffer has to be mapped separately, so the number of -calls to &func-mmap; should be equal to number of buffers times number of -planes in each buffer. The offset and length values must not be modified. -Remember, the buffers are allocated in physical memory, as opposed to virtual -memory, which can be swapped out to disk. Applications should free the buffers -as soon as possible with the &func-munmap; function.</para> - - <example> - <title>Mapping buffers in the single-planar API</title> - <programlisting> -&v4l2-requestbuffers; reqbuf; -struct { - void *start; - size_t length; -} *buffers; -unsigned int i; - -memset(&reqbuf, 0, sizeof(reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; -reqbuf.memory = V4L2_MEMORY_MMAP; -reqbuf.count = 20; - -if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { - if (errno == EINVAL) - printf("Video capturing or mmap-streaming is not supported\n"); - else - perror("VIDIOC_REQBUFS"); - - exit(EXIT_FAILURE); -} - -/* We want at least five buffers. */ - -if (reqbuf.count < 5) { - /* You may need to free the buffers here. */ - printf("Not enough buffer memory\n"); - exit(EXIT_FAILURE); -} - -buffers = calloc(reqbuf.count, sizeof(*buffers)); -assert(buffers != NULL); - -for (i = 0; i < reqbuf.count; i++) { - &v4l2-buffer; buffer; - - memset(&buffer, 0, sizeof(buffer)); - buffer.type = reqbuf.type; - buffer.memory = V4L2_MEMORY_MMAP; - buffer.index = i; - - if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) { - perror("VIDIOC_QUERYBUF"); - exit(EXIT_FAILURE); - } - - buffers[i].length = buffer.length; /* remember for munmap() */ - - buffers[i].start = mmap(NULL, buffer.length, - PROT_READ | PROT_WRITE, /* recommended */ - MAP_SHARED, /* recommended */ - fd, buffer.m.offset); - - if (MAP_FAILED == buffers[i].start) { - /* If you do not exit here you should unmap() and free() - the buffers mapped so far. */ - perror("mmap"); - exit(EXIT_FAILURE); - } -} - -/* Cleanup. */ - -for (i = 0; i < reqbuf.count; i++) - munmap(buffers[i].start, buffers[i].length); - </programlisting> - </example> - - <example> - <title>Mapping buffers in the multi-planar API</title> - <programlisting> -&v4l2-requestbuffers; reqbuf; -/* Our current format uses 3 planes per buffer */ -#define FMT_NUM_PLANES = 3 - -struct { - void *start[FMT_NUM_PLANES]; - size_t length[FMT_NUM_PLANES]; -} *buffers; -unsigned int i, j; - -memset(&reqbuf, 0, sizeof(reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; -reqbuf.memory = V4L2_MEMORY_MMAP; -reqbuf.count = 20; - -if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) { - if (errno == EINVAL) - printf("Video capturing or mmap-streaming is not supported\n"); - else - perror("VIDIOC_REQBUFS"); - - exit(EXIT_FAILURE); -} - -/* We want at least five buffers. */ - -if (reqbuf.count < 5) { - /* You may need to free the buffers here. */ - printf("Not enough buffer memory\n"); - exit(EXIT_FAILURE); -} - -buffers = calloc(reqbuf.count, sizeof(*buffers)); -assert(buffers != NULL); - -for (i = 0; i < reqbuf.count; i++) { - &v4l2-buffer; buffer; - &v4l2-plane; planes[FMT_NUM_PLANES]; - - memset(&buffer, 0, sizeof(buffer)); - buffer.type = reqbuf.type; - buffer.memory = V4L2_MEMORY_MMAP; - buffer.index = i; - /* length in struct v4l2_buffer in multi-planar API stores the size - * of planes array. */ - buffer.length = FMT_NUM_PLANES; - buffer.m.planes = planes; - - if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) { - perror("VIDIOC_QUERYBUF"); - exit(EXIT_FAILURE); - } - - /* Every plane has to be mapped separately */ - for (j = 0; j < FMT_NUM_PLANES; j++) { - buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ - - buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, - PROT_READ | PROT_WRITE, /* recommended */ - MAP_SHARED, /* recommended */ - fd, buffer.m.planes[j].m.offset); - - if (MAP_FAILED == buffers[i].start[j]) { - /* If you do not exit here you should unmap() and free() - the buffers and planes mapped so far. */ - perror("mmap"); - exit(EXIT_FAILURE); - } - } -} - -/* Cleanup. */ - -for (i = 0; i < reqbuf.count; i++) - for (j = 0; j < FMT_NUM_PLANES; j++) - munmap(buffers[i].start[j], buffers[i].length[j]); - </programlisting> - </example> - - <para>Conceptually streaming drivers maintain two buffer queues, an incoming -and an outgoing queue. They separate the synchronous capture or output -operation locked to a video clock from the application which is -subject to random disk or network delays and preemption by -other processes, thereby reducing the probability of data loss. -The queues are organized as FIFOs, buffers will be -output in the order enqueued in the incoming FIFO, and were -captured in the order dequeued from the outgoing FIFO.</para> - - <para>The driver may require a minimum number of buffers enqueued -at all times to function, apart of this no limit exists on the number -of buffers applications can enqueue in advance, or dequeue and -process. They can also enqueue in a different order than buffers have -been dequeued, and the driver can <emphasis>fill</emphasis> enqueued -<emphasis>empty</emphasis> buffers in any order. <footnote> - <para>Random enqueue order permits applications processing -images out of order (such as video codecs) to return buffers earlier, -reducing the probability of data loss. Random fill order allows -drivers to reuse buffers on a LIFO-basis, taking advantage of caches -holding scatter-gather lists and the like.</para> - </footnote> The index number of a buffer (&v4l2-buffer; -<structfield>index</structfield>) plays no role here, it only -identifies the buffer.</para> - - <para>Initially all mapped buffers are in dequeued state, -inaccessible by the driver. For capturing applications it is customary -to first enqueue all mapped buffers, then to start capturing and enter -the read loop. Here the application waits until a filled buffer can be -dequeued, and re-enqueues the buffer when the data is no longer -needed. Output applications fill and enqueue buffers, when enough -buffers are stacked up the output is started with -<constant>VIDIOC_STREAMON</constant>. In the write loop, when -the application runs out of free buffers, it must wait until an empty -buffer can be dequeued and reused.</para> - - <para>To enqueue and dequeue a buffer applications use the -&VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being -mapped, enqueued, full or empty can be determined at any time using the -&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the -application until one or more buffers can be dequeued. By default -<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the -outgoing queue. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> -returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; functions are always available.</para> - - <para>To start and stop capturing or output applications call the -&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note -<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both -queues as a side effect. Since there is no notion of doing anything -"now" on a multitasking system, if an application needs to synchronize -with another event it should examine the &v4l2-buffer; -<structfield>timestamp</structfield> of captured or outputted buffers. -</para> - - <para>Drivers implementing memory mapping I/O must -support the <constant>VIDIOC_REQBUFS</constant>, -<constant>VIDIOC_QUERYBUF</constant>, -<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, -<constant>VIDIOC_STREAMON</constant> and -<constant>VIDIOC_STREAMOFF</constant> ioctl, the -<function>mmap()</function>, <function>munmap()</function>, -<function>select()</function> and <function>poll()</function> -function.<footnote> - <para>At the driver level <function>select()</function> and -<function>poll()</function> are the same, and -<function>select()</function> is too important to be optional. The -rest should be evident.</para> - </footnote></para> - - <para>[capture example]</para> - - </section> - - <section id="userp"> - <title>Streaming I/O (User Pointers)</title> - - <para>Input and output devices support this I/O method when the -<constant>V4L2_CAP_STREAMING</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; -returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user -pointer method (not only memory mapping) is supported must be -determined by calling the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_USERPTR</constant>.</para> - - <para>This I/O method combines advantages of the read/write and -memory mapping methods. Buffers (planes) are allocated by the application -itself, and can reside for example in virtual or shared memory. Only -pointers to data are exchanged, these pointers and meta-information -are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). -The driver must be switched into user pointer I/O mode by calling the -&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated -beforehand, consequently they are not indexed and cannot be queried like mapped -buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> - - <example> - <title>Initiating streaming I/O with user pointers</title> - - <programlisting> -&v4l2-requestbuffers; reqbuf; - -memset (&reqbuf, 0, sizeof (reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; -reqbuf.memory = V4L2_MEMORY_USERPTR; - -if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { - if (errno == EINVAL) - printf ("Video capturing or user pointer streaming is not supported\n"); - else - perror ("VIDIOC_REQBUFS"); - - exit (EXIT_FAILURE); -} - </programlisting> - </example> - - <para>Buffer (plane) addresses and sizes are passed on the fly with the -&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, -applications can pass different addresses and sizes at each -<constant>VIDIOC_QBUF</constant> call. If required by the hardware the -driver swaps memory pages within physical memory to create a -continuous area of memory. This happens transparently to the -application in the virtual memory subsystem of the kernel. When buffer -pages have been swapped out to disk they are brought back and finally -locked in physical memory for DMA.<footnote> - <para>We expect that frequently used buffers are typically not -swapped out. Anyway, the process of swapping, locking or generating -scatter-gather lists may be time consuming. The delay can be masked by -the depth of the incoming buffer queue, and perhaps by maintaining -caches assuming a buffer will be soon enqueued again. On the other -hand, to optimize memory usage drivers can limit the number of buffers -locked in advance and recycle the most recently used buffers first. Of -course, the pages of empty buffers in the incoming queue need not be -saved to disk. Output buffers must be saved on the incoming and -outgoing queue because an application may share them with other -processes.</para> - </footnote></para> - - <para>Filled or displayed buffers are dequeued with the -&VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any -time between the completion of the DMA and this ioctl. The memory is -also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or -when the device is closed. Applications must take care not to free -buffers without dequeuing. For once, the buffers remain locked until -further, wasting physical memory. Second the driver will not be -notified when the memory is returned to the application's free list -and subsequently reused for other purposes, possibly completing the -requested DMA and overwriting valuable data.</para> - - <para>For capturing applications it is customary to enqueue a -number of empty buffers, to start capturing and enter the read loop. -Here the application waits until a filled buffer can be dequeued, and -re-enqueues the buffer when the data is no longer needed. Output -applications fill and enqueue buffers, when enough buffers are stacked -up output is started. In the write loop, when the application -runs out of free buffers it must wait until an empty buffer can be -dequeued and reused. Two methods exist to suspend execution of the -application until one or more buffers can be dequeued. By default -<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the -outgoing queue. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> -returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; function are always available.</para> - - <para>To start and stop capturing or output applications call the -&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note -<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both -queues and unlocks all buffers as a side effect. Since there is no -notion of doing anything "now" on a multitasking system, if an -application needs to synchronize with another event it should examine -the &v4l2-buffer; <structfield>timestamp</structfield> of captured -or outputted buffers.</para> - - <para>Drivers implementing user pointer I/O must -support the <constant>VIDIOC_REQBUFS</constant>, -<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, -<constant>VIDIOC_STREAMON</constant> and -<constant>VIDIOC_STREAMOFF</constant> ioctl, the -<function>select()</function> and <function>poll()</function> function.<footnote> - <para>At the driver level <function>select()</function> and -<function>poll()</function> are the same, and -<function>select()</function> is too important to be optional. The -rest should be evident.</para> - </footnote></para> - </section> - - <section id="dmabuf"> - <title>Streaming I/O (DMA buffer importing)</title> - -<para>The DMABUF framework provides a generic method for sharing buffers -between multiple devices. Device drivers that support DMABUF can export a DMA -buffer to userspace as a file descriptor (known as the exporter role), import a -DMA buffer from userspace using a file descriptor previously exported for a -different or the same device (known as the importer role), or both. This -section describes the DMABUF importer role API in V4L2.</para> - - <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for -details about exporting V4L2 buffers as DMABUF file descriptors.</para> - -<para>Input and output devices support the streaming I/O method when the -<constant>V4L2_CAP_STREAMING</constant> flag in the -<structfield>capabilities</structfield> field of &v4l2-capability; returned by -the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through -DMABUF file descriptors is supported is determined by calling the -&VIDIOC-REQBUFS; ioctl with the memory type set to -<constant>V4L2_MEMORY_DMABUF</constant>.</para> - - <para>This I/O method is dedicated to sharing DMA buffers between different -devices, which may be V4L devices or other video-related devices (e.g. DRM). -Buffers (planes) are allocated by a driver on behalf of an application. Next, -these buffers are exported to the application as file descriptors using an API -which is specific for an allocator driver. Only such file descriptor are -exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or -in &v4l2-plane; in the multi-planar API case). The driver must be switched -into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer -type.</para> - - <example> - <title>Initiating streaming I/O with DMABUF file descriptors</title> - - <programlisting> -&v4l2-requestbuffers; reqbuf; - -memset(&reqbuf, 0, sizeof (reqbuf)); -reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; -reqbuf.memory = V4L2_MEMORY_DMABUF; -reqbuf.count = 1; - -if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { - if (errno == EINVAL) - printf("Video capturing or DMABUF streaming is not supported\n"); - else - perror("VIDIOC_REQBUFS"); - - exit(EXIT_FAILURE); -} - </programlisting> - </example> - - <para>The buffer (plane) file descriptor is passed on the fly with the -&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be -associated with a different DMABUF descriptor. Although buffers are commonly -cycled, applications can pass a different DMABUF descriptor at each -<constant>VIDIOC_QBUF</constant> call.</para> - - <example> - <title>Queueing DMABUF using single plane API</title> - - <programlisting> -int buffer_queue(int v4lfd, int index, int dmafd) -{ - &v4l2-buffer; buf; - - memset(&buf, 0, sizeof buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_DMABUF; - buf.index = index; - buf.m.fd = dmafd; - - if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { - perror("VIDIOC_QBUF"); - return -1; - } - - return 0; -} - </programlisting> - </example> - - <example> - <title>Queueing DMABUF using multi plane API</title> - - <programlisting> -int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) -{ - &v4l2-buffer; buf; - &v4l2-plane; planes[VIDEO_MAX_PLANES]; - int i; - - memset(&buf, 0, sizeof buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; - buf.memory = V4L2_MEMORY_DMABUF; - buf.index = index; - buf.m.planes = planes; - buf.length = n_planes; - - memset(&planes, 0, sizeof planes); - - for (i = 0; i < n_planes; ++i) - buf.m.planes[i].m.fd = dmafd[i]; - - if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { - perror("VIDIOC_QBUF"); - return -1; - } - - return 0; -} - </programlisting> - </example> - - <para>Captured or displayed buffers are dequeued with the -&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any -time between the completion of the DMA and this ioctl. The memory is -also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or -when the device is closed.</para> - - <para>For capturing applications it is customary to enqueue a -number of empty buffers, to start capturing and enter the read loop. -Here the application waits until a filled buffer can be dequeued, and -re-enqueues the buffer when the data is no longer needed. Output -applications fill and enqueue buffers, when enough buffers are stacked -up output is started. In the write loop, when the application -runs out of free buffers it must wait until an empty buffer can be -dequeued and reused. Two methods exist to suspend execution of the -application until one or more buffers can be dequeued. By default -<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the -outgoing queue. When the <constant>O_NONBLOCK</constant> flag was -given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> -returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; and &func-poll; functions are always available.</para> - - <para>To start and stop capturing or displaying applications call the -&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that -<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and -unlocks all buffers as a side effect. Since there is no notion of doing -anything "now" on a multitasking system, if an application needs to synchronize -with another event it should examine the &v4l2-buffer; -<structfield>timestamp</structfield> of captured or outputted buffers.</para> - - <para>Drivers implementing DMABUF importing I/O must support the -<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>, -<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and -<constant>VIDIOC_STREAMOFF</constant> ioctls, and the -<function>select()</function> and <function>poll()</function> functions.</para> - - </section> - - <section id="async"> - <title>Asynchronous I/O</title> - - <para>This method is not defined yet.</para> - </section> - - <section id="buffer"> - <title>Buffers</title> - - <para>A buffer contains data exchanged by application and -driver using one of the Streaming I/O methods. In the multi-planar API, the -data is held in planes, while the buffer structure acts as a container -for the planes. Only pointers to buffers (planes) are exchanged, the data -itself is not copied. These pointers, together with meta-information like -timestamps or field parity, are stored in a struct -<structname>v4l2_buffer</structname>, argument to -the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. -In the multi-planar API, some plane-specific members of struct -<structname>v4l2_buffer</structname>, such as pointers and sizes for each -plane, are stored in struct <structname>v4l2_plane</structname> instead. -In that case, struct <structname>v4l2_buffer</structname> contains an array of -plane structures.</para> - - <para>Dequeued video buffers come with timestamps. The driver - decides at which part of the frame and with which clock the - timestamp is taken. Please see flags in the masks - <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and - <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref - linkend="buffer-flags" />. These flags are always valid and constant - across all buffers during the whole video stream. Changes in these - flags may take place as a side effect of &VIDIOC-S-INPUT; or - &VIDIOC-S-OUTPUT; however. The - <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type - which is used by e.g. on mem-to-mem devices is an exception to the - rule: the timestamp source flags are copied from the OUTPUT video - buffer to the CAPTURE video buffer.</para> - - <table frame="none" pgwide="1" id="v4l2-buffer"> - <title>struct <structname>v4l2_buffer</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>index</structfield></entry> - <entry></entry> - <entry>Number of the buffer, set by the application except -when calling &VIDIOC-DQBUF;, then it is set by the driver. -This field can range from zero to the number of buffers allocated -with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>), -plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry></entry> - <entry>Type of the buffer, same as &v4l2-format; -<structfield>type</structfield> or &v4l2-requestbuffers; -<structfield>type</structfield>, set by the application. See <xref -linkend="v4l2-buf-type" /></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>bytesused</structfield></entry> - <entry></entry> - <entry>The number of bytes occupied by the data in the -buffer. It depends on the negotiated data format and may change with -each buffer for compressed variable size data like JPEG images. -Drivers must set this field when <structfield>type</structfield> -refers to a capture stream, applications when it refers to an output stream. -If the application sets this to 0 for an output stream, then -<structfield>bytesused</structfield> will be set to the size of the -buffer (see the <structfield>length</structfield> field of this struct) by -the driver. For multiplanar formats this field is ignored and the -<structfield>planes</structfield> pointer is used instead.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry></entry> - <entry>Flags set by the application or driver, see <xref -linkend="buffer-flags" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>field</structfield></entry> - <entry></entry> - <entry>Indicates the field order of the image in the -buffer, see <xref linkend="v4l2-field" />. This field is not used when -the buffer contains VBI data. Drivers must set it when -<structfield>type</structfield> refers to a capture stream, -applications when it refers to an output stream.</entry> - </row> - <row> - <entry>struct timeval</entry> - <entry><structfield>timestamp</structfield></entry> - <entry></entry> - <entry><para>For capture streams this is time when the first data - byte was captured, as returned by the - <function>clock_gettime()</function> function for the relevant - clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in - <xref linkend="buffer-flags" />. For output streams the driver - stores the time at which the last data byte was actually sent out - in the <structfield>timestamp</structfield> field. This permits - applications to monitor the drift between the video and system - clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> - the application has to fill in the timestamp which will be copied - by the driver to the capture stream.</para></entry> - </row> - <row> - <entry>&v4l2-timecode;</entry> - <entry><structfield>timecode</structfield></entry> - <entry></entry> - <entry>When <structfield>type</structfield> is -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the -<constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in -<structfield>flags</structfield>, this structure contains a frame -timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> -mode the top and bottom field contain the same timecode. -Timecodes are intended to help video editing and are typically recorded on -video tapes, but also embedded in compressed formats like MPEG. This -field is independent of the <structfield>timestamp</structfield> and -<structfield>sequence</structfield> fields.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>sequence</structfield></entry> - <entry></entry> - <entry>Set by the driver, counting the frames (not fields!) in -sequence. This field is set for both input and output devices.</entry> - </row> - <row> - <entry spanname="hspan"><para>In <link -linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and -bottom field have the same sequence number. The count starts at zero -and includes dropped or repeated frames. A dropped frame was received -by an input device but could not be stored due to lack of free buffer -space. A repeated frame was displayed again by an output device -because the application did not pass new data in -time.</para><para>Note this may count the frames received -e.g. over USB, without taking into account the frames dropped by the -remote hardware due to limited compression throughput or bus -bandwidth. These devices identify by not enumerating any video -standards, see <xref linkend="standard" />.</para></entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>memory</structfield></entry> - <entry></entry> - <entry>This field must be set by applications and/or drivers -in accordance with the selected I/O method. See <xref linkend="v4l2-memory" - /></entry> - </row> - <row> - <entry>union</entry> - <entry><structfield>m</structfield></entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>offset</structfield></entry> - <entry>For the single-planar API and when -<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this -is the offset of the buffer from the start of the device memory. The value is -returned by the driver and apart of serving as parameter to the &func-mmap; -function not useful for applications. See <xref linkend="mmap" /> for details - </entry> - </row> - <row> - <entry></entry> - <entry>unsigned long</entry> - <entry><structfield>userptr</structfield></entry> - <entry>For the single-planar API and when -<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant> -this is a pointer to the buffer (casted to unsigned long type) in virtual -memory, set by the application. See <xref linkend="userp" /> for details. - </entry> - </row> - <row> - <entry></entry> - <entry>struct v4l2_plane</entry> - <entry><structfield>*planes</structfield></entry> - <entry>When using the multi-planar API, contains a userspace pointer - to an array of &v4l2-plane;. The size of the array should be put - in the <structfield>length</structfield> field of this - <structname>v4l2_buffer</structname> structure.</entry> - </row> - <row> - <entry></entry> - <entry>int</entry> - <entry><structfield>fd</structfield></entry> - <entry>For the single-plane API and when -<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this -is the file descriptor associated with a DMABUF buffer.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>length</structfield></entry> - <entry></entry> - <entry>Size of the buffer (not the payload) in bytes for the - single-planar API. This is set by the driver based on the calls to - &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets - this to the number of elements in the <structfield>planes</structfield> - array. The driver will fill in the actual number of valid elements in - that array. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved2</structfield></entry> - <entry></entry> - <entry>A place holder for future extensions. Drivers and applications -must set this to 0.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved</structfield></entry> - <entry></entry> - <entry>A place holder for future extensions. Drivers and applications -must set this to 0.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-plane"> - <title>struct <structname>v4l2_plane</structname></title> - <tgroup cols="4"> - &cs-ustr; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>bytesused</structfield></entry> - <entry></entry> - <entry>The number of bytes occupied by data in the plane - (its payload). Drivers must set this field when <structfield>type</structfield> - refers to a capture stream, applications when it refers to an output stream. - If the application sets this to 0 for an output stream, then - <structfield>bytesused</structfield> will be set to the size of the - plane (see the <structfield>length</structfield> field of this struct) - by the driver. Note that the actual image data starts at - <structfield>data_offset</structfield> which may not be 0.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>length</structfield></entry> - <entry></entry> - <entry>Size in bytes of the plane (not its payload). This is set by the driver - based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry> - </row> - <row> - <entry>union</entry> - <entry><structfield>m</structfield></entry> - <entry></entry> - <entry></entry> - </row> - <row> - <entry></entry> - <entry>__u32</entry> - <entry><structfield>mem_offset</structfield></entry> - <entry>When the memory type in the containing &v4l2-buffer; is - <constant>V4L2_MEMORY_MMAP</constant>, this is the value that - should be passed to &func-mmap;, similar to the - <structfield>offset</structfield> field in &v4l2-buffer;.</entry> - </row> - <row> - <entry></entry> - <entry>unsigned long</entry> - <entry><structfield>userptr</structfield></entry> - <entry>When the memory type in the containing &v4l2-buffer; is - <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace - pointer to the memory allocated for this plane by an application. - </entry> - </row> - <row> - <entry></entry> - <entry>int</entry> - <entry><structfield>fd</structfield></entry> - <entry>When the memory type in the containing &v4l2-buffer; is - <constant>V4L2_MEMORY_DMABUF</constant>, this is a file - descriptor associated with a DMABUF buffer, similar to the - <structfield>fd</structfield> field in &v4l2-buffer;.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>data_offset</structfield></entry> - <entry></entry> - <entry>Offset in bytes to video data in the plane. - Drivers must set this field when <structfield>type</structfield> - refers to a capture stream, applications when it refers to an output stream. - Note that data_offset is included in <structfield>bytesused</structfield>. - So the size of the image in the plane is - <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at - offset <structfield>data_offset</structfield> from the start of the plane. - </entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>reserved[11]</structfield></entry> - <entry></entry> - <entry>Reserved for future use. Should be zeroed by drivers and - applications.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="v4l2-buf-type"> - <title>enum v4l2_buf_type</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> - <entry>1</entry> - <entry>Buffer of a single-planar video capture stream, see <xref - linkend="capture" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> - </entry> - <entry>9</entry> - <entry>Buffer of a multi-planar video capture stream, see <xref - linkend="capture" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> - <entry>2</entry> - <entry>Buffer of a single-planar video output stream, see <xref - linkend="output" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> - </entry> - <entry>10</entry> - <entry>Buffer of a multi-planar video output stream, see <xref - linkend="output" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> - <entry>3</entry> - <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> - <entry>4</entry> - <entry>Buffer of a raw VBI capture stream, see <xref - linkend="raw-vbi" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> - <entry>5</entry> - <entry>Buffer of a raw VBI output stream, see <xref - linkend="raw-vbi" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> - <entry>6</entry> - <entry>Buffer of a sliced VBI capture stream, see <xref - linkend="sliced" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> - <entry>7</entry> - <entry>Buffer of a sliced VBI output stream, see <xref - linkend="sliced" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> - <entry>8</entry> - <entry>Buffer for video output overlay (OSD), see <xref - linkend="osd" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry> - <entry>11</entry> - <entry>Buffer for Software Defined Radio (SDR) capture stream, see - <xref linkend="sdr" />.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant></entry> - <entry>12</entry> - <entry>Buffer for Software Defined Radio (SDR) output stream, see - <xref linkend="sdr" />.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="buffer-flags"> - <title>Buffer Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> - <entry>0x00000001</entry> - <entry>The buffer resides in device memory and has been mapped -into the application's address space, see <xref linkend="mmap" /> for details. -Drivers set or clear this flag when the -<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link - linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link - linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> - <entry>0x00000002</entry> - <entry>Internally drivers maintain two buffer queues, an -incoming and outgoing queue. When this flag is set, the buffer is -currently on the incoming queue. It automatically moves to the -outgoing queue after the buffer has been filled (capture devices) or -displayed (output devices). Drivers set or clear this flag when the -<constant>VIDIOC_QUERYBUF</constant> ioctl is called. After -(successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is -always set and after <constant>VIDIOC_DQBUF</constant> always -cleared.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> - <entry>0x00000004</entry> - <entry>When this flag is set, the buffer is currently on -the outgoing queue, ready to be dequeued from the driver. Drivers set -or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl -is called. After calling the <constant>VIDIOC_QBUF</constant> or -<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a -buffer cannot be on both queues at the same time, the -<constant>V4L2_BUF_FLAG_QUEUED</constant> and -<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. -They can be both cleared however, then the buffer is in "dequeued" -state, in the application domain so to say.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry> - <entry>0x00000040</entry> - <entry>When this flag is set, the buffer has been dequeued - successfully, although the data might have been corrupted. - This is recoverable, streaming may continue as normal and - the buffer may be reused normally. - Drivers set this flag when the <constant>VIDIOC_DQBUF</constant> - ioctl is called.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> - <entry>0x00000008</entry> - <entry>Drivers set or clear this flag when calling the -<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video -capture devices when the buffer contains a compressed image which is a -key frame (or field), &ie; can be decompressed on its own. Also known as -an I-frame. Applications can set this bit when <structfield>type</structfield> -refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> - <entry>0x00000010</entry> - <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> -this flags predicted frames or fields which contain only differences to a -previous key frame. Applications can set this bit when <structfield>type</structfield> -refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> - <entry>0x00000020</entry> - <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> -this flags a bi-directional predicted frame or field which contains only -the differences between the current frame and both the preceding and following -key frames to specify its content. Applications can set this bit when -<structfield>type</structfield> refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> - <entry>0x00000100</entry> - <entry>The <structfield>timecode</structfield> field is valid. -Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> -ioctl is called. Applications can set this bit and the corresponding -<structfield>timecode</structfield> structure when <structfield>type</structfield> -refers to an output stream.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> - <entry>0x00000400</entry> - <entry>The buffer has been prepared for I/O and can be queued by the -application. Drivers set or clear this flag when the -<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link - linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link - linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link - linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> - <entry>0x00000800</entry> - <entry>Caches do not have to be invalidated for this buffer. -Typically applications shall use this flag if the data captured in the buffer -is not going to be touched by the CPU, instead the buffer will, probably, be -passed on to a DMA-capable hardware unit for further processing or output. -</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> - <entry>0x00001000</entry> - <entry>Caches do not have to be cleaned for this buffer. -Typically applications shall use this flag for output buffers if the data -in this buffer has not been created by the CPU but by some DMA-capable unit, -in which case caches have not been used.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_LAST</constant></entry> - <entry>0x00100000</entry> - <entry>Last buffer produced by the hardware. mem2mem codec drivers -set this flag on the capture queue for the last buffer when the -<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link> or -<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Due to hardware -limitations, the last buffer may be empty. In this case the driver will set the -<structfield>bytesused</structfield> field to 0, regardless of the format. Any -Any subsequent call to the <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl -will not block anymore, but return an &EPIPE;.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry> - <entry>0x0000e000</entry> - <entry>Mask for timestamp types below. To test the - timestamp type, mask out bits not belonging to timestamp - type by performing a logical and operation with buffer - flags and timestamp mask.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry> - <entry>0x00000000</entry> - <entry>Unknown timestamp type. This type is used by - drivers before Linux 3.9 and may be either monotonic (see - below) or realtime (wall clock). Monotonic clock has been - favoured in embedded systems whereas most of the drivers - use the realtime clock. Either kinds of timestamps are - available in user space via - <function>clock_gettime(2)</function> using clock IDs - <constant>CLOCK_MONOTONIC</constant> and - <constant>CLOCK_REALTIME</constant>, respectively.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry> - <entry>0x00002000</entry> - <entry>The buffer timestamp has been taken from the - <constant>CLOCK_MONOTONIC</constant> clock. To access the - same clock outside V4L2, use - <function>clock_gettime(2)</function>.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry> - <entry>0x00004000</entry> - <entry>The CAPTURE buffer timestamp has been taken from the - corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry> - <entry>0x00070000</entry> - <entry>Mask for timestamp sources below. The timestamp source - defines the point of time the timestamp is taken in relation to - the frame. Logical 'and' operation between the - <structfield>flags</structfield> field and - <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the - value of the timestamp source. Applications must set the timestamp - source when <structfield>type</structfield> refers to an output stream - and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry> - <entry>0x00000000</entry> - <entry>End Of Frame. The buffer timestamp has been taken - when the last pixel of the frame has been received or the - last pixel of the frame has been transmitted. In practice, - software generated timestamps will typically be read from - the clock a small amount of time after the last pixel has - been received or transmitten, depending on the system and - other activity in it.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry> - <entry>0x00010000</entry> - <entry>Start Of Exposure. The buffer timestamp has been - taken when the exposure of the frame has begun. This is - only valid for the - <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer - type.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table pgwide="1" frame="none" id="v4l2-memory"> - <title>enum v4l2_memory</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_MEMORY_MMAP</constant></entry> - <entry>1</entry> - <entry>The buffer is used for <link linkend="mmap">memory -mapping</link> I/O.</entry> - </row> - <row> - <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> - <entry>2</entry> - <entry>The buffer is used for <link linkend="userp">user -pointer</link> I/O.</entry> - </row> - <row> - <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> - <entry>3</entry> - <entry>[to do]</entry> - </row> - <row> - <entry><constant>V4L2_MEMORY_DMABUF</constant></entry> - <entry>4</entry> - <entry>The buffer is used for <link linkend="dmabuf">DMA shared -buffer</link> I/O.</entry> - </row> - </tbody> - </tgroup> - </table> - - <section> - <title>Timecodes</title> - - <para>The <structname>v4l2_timecode</structname> structure is -designed to hold a <xref linkend="smpte12m" /> or similar timecode. -(struct <structname>timeval</structname> timestamps are stored in -&v4l2-buffer; field <structfield>timestamp</structfield>.)</para> - - <table frame="none" pgwide="1" id="v4l2-timecode"> - <title>struct <structname>v4l2_timecode</structname></title> - <tgroup cols="3"> - &cs-str; - <tbody valign="top"> - <row> - <entry>__u32</entry> - <entry><structfield>type</structfield></entry> - <entry>Frame rate the timecodes are based on, see <xref - linkend="timecode-type" />.</entry> - </row> - <row> - <entry>__u32</entry> - <entry><structfield>flags</structfield></entry> - <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>frames</structfield></entry> - <entry>Frame count, 0 ... 23/24/29/49/59, depending on the - type of timecode.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>seconds</structfield></entry> - <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>minutes</structfield></entry> - <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>hours</structfield></entry> - <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> - </row> - <row> - <entry>__u8</entry> - <entry><structfield>userbits</structfield>[4]</entry> - <entry>The "user group" bits from the timecode.</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="timecode-type"> - <title>Timecode Types</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> - <entry>1</entry> - <entry>24 frames per second, i. e. film.</entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> - <entry>2</entry> - <entry>25 frames per second, &ie; PAL or SECAM video.</entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> - <entry>3</entry> - <entry>30 frames per second, &ie; NTSC video.</entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> - <entry>4</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> - <entry>5</entry> - <entry></entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="timecode-flags"> - <title>Timecode Flags</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> - <entry>0x0001</entry> - <entry>Indicates "drop frame" semantics for counting frames -in 29.97 fps material. When set, frame numbers 0 and 1 at the start of -each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the -count.</entry> - </row> - <row> - <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> - <entry>0x0002</entry> - <entry>The "color frame" flag.</entry> - </row> - <row> - <entry><constant>V4L2_TC_USERBITS_field</constant></entry> - <entry>0x000C</entry> - <entry>Field mask for the "binary group flags".</entry> - </row> - <row> - <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> - <entry>0x0000</entry> - <entry>Unspecified format.</entry> - </row> - <row> - <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> - <entry>0x0008</entry> - <entry>8-bit ISO characters.</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - </section> - - <section id="field-order"> - <title>Field Order</title> - - <para>We have to distinguish between progressive and interlaced -video. Progressive video transmits all lines of a video image -sequentially. Interlaced video divides an image into two fields, -containing only the odd and even lines of the image, respectively. -Alternating the so called odd and even field are transmitted, and due -to a small delay between fields a cathode ray TV displays the lines -interleaved, yielding the original frame. This curious technique was -invented because at refresh rates similar to film the image would -fade out too quickly. Transmitting fields reduces the flicker without -the necessity of doubling the frame rate and with it the bandwidth -required for each channel.</para> - - <para>It is important to understand a video camera does not expose -one frame at a time, merely transmitting the frames separated into -fields. The fields are in fact captured at two different instances in -time. An object on screen may well move between one field and the -next. For applications analysing motion it is of paramount importance -to recognize which field of a frame is older, the <emphasis>temporal -order</emphasis>.</para> - - <para>When the driver provides or accepts images field by field -rather than interleaved, it is also important applications understand -how the fields combine to frames. We distinguish between top (aka odd) and -bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line -of the top field is the first line of an interlaced frame, the first -line of the bottom field is the second line of that frame.</para> - - <para>However because fields were captured one after the other, -arguing whether a frame commences with the top or bottom field is -pointless. Any two successive top and bottom, or bottom and top fields -yield a valid frame. Only when the source was progressive to begin -with, ⪚ when transferring film to video, two fields may come from -the same frame, creating a natural order.</para> - - <para>Counter to intuition the top field is not necessarily the -older field. Whether the older field contains the top or bottom lines -is a convention determined by the video standard. Hence the -distinction between temporal and spatial order of fields. The diagrams -below should make this clearer.</para> - - <para>All video capture and output devices must report the current -field order. Some drivers may permit the selection of a different -order, to this end applications initialize the -<structfield>field</structfield> field of &v4l2-pix-format; before -calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should -have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> - - <table frame="none" pgwide="1" id="v4l2-field"> - <title>enum v4l2_field</title> - <tgroup cols="3"> - &cs-def; - <tbody valign="top"> - <row> - <entry><constant>V4L2_FIELD_ANY</constant></entry> - <entry>0</entry> - <entry>Applications request this field order when any -one of the <constant>V4L2_FIELD_NONE</constant>, -<constant>V4L2_FIELD_TOP</constant>, -<constant>V4L2_FIELD_BOTTOM</constant>, or -<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. -Drivers choose depending on hardware capabilities or e. g. the -requested image size, and return the actual field order. Drivers must -never return <constant>V4L2_FIELD_ANY</constant>. If multiple -field orders are possible the driver must choose one of the possible -field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; -<structfield>field</structfield> can never be -<constant>V4L2_FIELD_ANY</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_NONE</constant></entry> - <entry>1</entry> - <entry>Images are in progressive format, not interlaced. -The driver may also indicate this order when it cannot distinguish -between <constant>V4L2_FIELD_TOP</constant> and -<constant>V4L2_FIELD_BOTTOM</constant>.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_TOP</constant></entry> - <entry>2</entry> - <entry>Images consist of the top (aka odd) field only.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> - <entry>3</entry> - <entry>Images consist of the bottom (aka even) field only. -Applications may wish to prevent a device from capturing interlaced -images because they will have "comb" or "feathering" artefacts around -moving objects.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> - <entry>4</entry> - <entry>Images contain both fields, interleaved line by -line. The temporal order of the fields (whether the top or bottom -field is first transmitted) depends on the current video standard. -M/NTSC transmits the bottom field first, all other standards the top -field first.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> - <entry>5</entry> - <entry>Images contain both fields, the top field lines -are stored first in memory, immediately followed by the bottom field -lines. Fields are always stored in temporal order, the older one first -in memory. Image sizes refer to the frame, not fields.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> - <entry>6</entry> - <entry>Images contain both fields, the bottom field -lines are stored first in memory, immediately followed by the top -field lines. Fields are always stored in temporal order, the older one -first in memory. Image sizes refer to the frame, not fields.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> - <entry>7</entry> - <entry>The two fields of a frame are passed in separate -buffers, in temporal order, &ie; the older one first. To indicate the field -parity (whether the current field is a top or bottom field) the driver -or application, depending on data direction, must set &v4l2-buffer; -<structfield>field</structfield> to -<constant>V4L2_FIELD_TOP</constant> or -<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair -to build a frame. If fields are successive, without any dropped fields -between them (fields can drop individually), can be determined from -the &v4l2-buffer; <structfield>sequence</structfield> field. This format -cannot be selected when using the read/write I/O method since there -is no way to communicate if a field was a top or bottom field.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> - <entry>8</entry> - <entry>Images contain both fields, interleaved line by -line, top field first. The top field is transmitted first.</entry> - </row> - <row> - <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> - <entry>9</entry> - <entry>Images contain both fields, interleaved line by -line, top field first. The bottom field is transmitted first.</entry> - </row> - </tbody> - </tgroup> - </table> - - <figure id="fieldseq-tb"> - <title>Field Order, Top Field First Transmitted</title> - <mediaobject> - <imageobject> - <imagedata fileref="fieldseq_tb.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="fieldseq_tb.gif" format="GIF" /> - </imageobject> - </mediaobject> - </figure> - - <figure id="fieldseq-bt"> - <title>Field Order, Bottom Field First Transmitted</title> - <mediaobject> - <imageobject> - <imagedata fileref="fieldseq_bt.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="fieldseq_bt.gif" format="GIF" /> - </imageobject> - </mediaobject> - </figure> - </section> |