mirror of
https://github.com/AuxXxilium/linux_dsm_epyc7002.git
synced 2024-11-30 09:56:40 +07:00
dc8b1c0e89
Make sure that the documentation clearly states who is zeroing reserved fields: drivers and/or applications. This patch syncs the documentation with the checks that v4l2-compliance and valgrind do. Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
1546 lines
62 KiB
XML
1546 lines
62 KiB
XML
<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.</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.</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>
|
|
|
|
<note>
|
|
<title>Experimental</title>
|
|
<para>This is an <link linkend="experimental">experimental</link>
|
|
interface and may change in the future.</para>
|
|
</note>
|
|
|
|
<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 an input 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 an input 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 input 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 an input 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 an input 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), 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>
|