1<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Buffers</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="io.html" title="Chapter 3. Input/Output"><link rel="prev" href="async.html" title="Asynchronous I/O"><link rel="next" href="field-order.html" title="Field Order"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Buffers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="async.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Input/Output</th><td width="20%" align="right"> <a accesskey="n" href="field-order.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="buffer"></a>Buffers</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="buffer.html#id-1.4.6.14.9">Timecodes</a></span></dt></dl></div><p>A buffer contains data exchanged by application and 2driver using one of the Streaming I/O methods. In the multi-planar API, the 3data is held in planes, while the buffer structure acts as a container 4for the planes. Only pointers to buffers (planes) are exchanged, the data 5itself is not copied. These pointers, together with meta-information like 6timestamps or field parity, are stored in a struct 7<span class="structname">v4l2_buffer</span>, argument to 8the <a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a>, <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_QBUF</code></a> and <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_DQBUF</code></a> ioctl. 9In the multi-planar API, some plane-specific members of struct 10<span class="structname">v4l2_buffer</span>, such as pointers and sizes for each 11plane, are stored in struct <span class="structname">v4l2_plane</span> instead. 12In that case, struct <span class="structname">v4l2_buffer</span> contains an array of 13plane structures.</p><p>Dequeued video buffers come with timestamps. The driver 14 decides at which part of the frame and with which clock the 15 timestamp is taken. Please see flags in the masks 16 <code class="constant">V4L2_BUF_FLAG_TIMESTAMP_MASK</code> and 17 <code class="constant">V4L2_BUF_FLAG_TSTAMP_SRC_MASK</code> in <a class="xref" href="buffer.html#buffer-flags" title="Table 3.4. Buffer Flags">Table 3.4, “Buffer Flags”</a>. These flags are always valid and constant 18 across all buffers during the whole video stream. Changes in these 19 flags may take place as a side effect of <a class="link" href="vidioc-g-input.html" title="ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT"><code class="constant">VIDIOC_S_INPUT</code></a> or 20 <a class="link" href="vidioc-g-output.html" title="ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT"><code class="constant">VIDIOC_S_OUTPUT</code></a> however. The 21 <code class="constant">V4L2_BUF_FLAG_TIMESTAMP_COPY</code> timestamp type 22 which is used by e.g. on mem-to-mem devices is an exception to the 23 rule: the timestamp source flags are copied from the OUTPUT video 24 buffer to the CAPTURE video buffer.</p><div class="table"><a name="v4l2-buffer"></a><p class="title"><b>Table 3.1. struct <span class="structname">v4l2_buffer</span></b></p><div class="table-contents"><table summary="struct v4l2_buffer" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="c4"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>index</code></em></td><td valign="top"> </td><td valign="top">Number of the buffer, set by the application except 25when calling <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_DQBUF</code></a>, then it is set by the driver. 26This field can range from zero to the number of buffers allocated 27with the <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl (struct <a class="link" href="vidioc-reqbufs.html#v4l2-requestbuffers" title="Table A.100. struct v4l2_requestbuffers">v4l2_requestbuffers</a> <em class="structfield"><code>count</code></em>), 28plus any buffers allocated with <a class="link" href="vidioc-create-bufs.html" title="ioctl VIDIOC_CREATE_BUFS"><code class="constant">VIDIOC_CREATE_BUFS</code></a> minus one.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>type</code></em></td><td valign="top"> </td><td valign="top">Type of the buffer, same as struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> 29<em class="structfield"><code>type</code></em> or struct <a class="link" href="vidioc-reqbufs.html#v4l2-requestbuffers" title="Table A.100. struct v4l2_requestbuffers">v4l2_requestbuffers</a> 30<em class="structfield"><code>type</code></em>, set by the application. See <a class="xref" href="buffer.html#v4l2-buf-type" title="Table 3.3. enum v4l2_buf_type">Table 3.3, “enum v4l2_buf_type”</a></td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>bytesused</code></em></td><td valign="top"> </td><td valign="top">The number of bytes occupied by the data in the 31buffer. It depends on the negotiated data format and may change with 32each buffer for compressed variable size data like JPEG images. 33Drivers must set this field when <em class="structfield"><code>type</code></em> 34refers to an input stream, applications when it refers to an output stream. 35If the application sets this to 0 for an output stream, then 36<em class="structfield"><code>bytesused</code></em> will be set to the size of the 37buffer (see the <em class="structfield"><code>length</code></em> field of this struct) by 38the driver. For multiplanar formats this field is ignored and the 39<em class="structfield"><code>planes</code></em> pointer is used instead.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>flags</code></em></td><td valign="top"> </td><td valign="top">Flags set by the application or driver, see <a class="xref" href="buffer.html#buffer-flags" title="Table 3.4. Buffer Flags">Table 3.4, “Buffer Flags”</a>.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>field</code></em></td><td valign="top"> </td><td valign="top">Indicates the field order of the image in the 40buffer, see <a class="xref" href="field-order.html#v4l2-field" title="Table 3.9. enum v4l2_field">Table 3.9, “enum v4l2_field”</a>. This field is not used when 41the buffer contains VBI data. Drivers must set it when 42<em class="structfield"><code>type</code></em> refers to an input stream, 43applications when it refers to an output stream.</td></tr><tr><td valign="top">struct timeval</td><td valign="top"><em class="structfield"><code>timestamp</code></em></td><td valign="top"> </td><td valign="top"><p>For input streams this is time when the first data 44 byte was captured, as returned by the 45 <code class="function">clock_gettime()</code> function for the relevant 46 clock id; see <code class="constant">V4L2_BUF_FLAG_TIMESTAMP_*</code> in 47 <a class="xref" href="buffer.html#buffer-flags" title="Table 3.4. Buffer Flags">Table 3.4, “Buffer Flags”</a>. For output streams the driver 48 stores the time at which the last data byte was actually sent out 49 in the <em class="structfield"><code>timestamp</code></em> field. This permits 50 applications to monitor the drift between the video and system 51 clock. For output streams that use <code class="constant">V4L2_BUF_FLAG_TIMESTAMP_COPY</code> 52 the application has to fill in the timestamp which will be copied 53 by the driver to the capture stream.</p></td></tr><tr><td valign="top">struct <a class="link" href="buffer.html#v4l2-timecode" title="Table 3.6. struct v4l2_timecode">v4l2_timecode</a></td><td valign="top"><em class="structfield"><code>timecode</code></em></td><td valign="top"> </td><td valign="top">When <em class="structfield"><code>type</code></em> is 54<code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE</code> and the 55<code class="constant">V4L2_BUF_FLAG_TIMECODE</code> flag is set in 56<em class="structfield"><code>flags</code></em>, this structure contains a frame 57timecode. In <a class="link" href="field-order.html#v4l2-field" title="Table 3.9. enum v4l2_field">V4L2_FIELD_ALTERNATE</a> 58mode the top and bottom field contain the same timecode. 59Timecodes are intended to help video editing and are typically recorded on 60video tapes, but also embedded in compressed formats like MPEG. This 61field is independent of the <em class="structfield"><code>timestamp</code></em> and 62<em class="structfield"><code>sequence</code></em> fields.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>sequence</code></em></td><td valign="top"> </td><td valign="top">Set by the driver, counting the frames (not fields!) in 63sequence. This field is set for both input and output devices.</td></tr><tr><td colspan="4" valign="top"><p>In <a class="link" href="field-order.html#v4l2-field" title="Table 3.9. enum v4l2_field">V4L2_FIELD_ALTERNATE</a> mode the top and 64bottom field have the same sequence number. The count starts at zero 65and includes dropped or repeated frames. A dropped frame was received 66by an input device but could not be stored due to lack of free buffer 67space. A repeated frame was displayed again by an output device 68because the application did not pass new data in 69time.</p><p>Note this may count the frames received 70e.g. over USB, without taking into account the frames dropped by the 71remote hardware due to limited compression throughput or bus 72bandwidth. These devices identify by not enumerating any video 73standards, see <a class="xref" href="standard.html" title="Video Standards">the section called “Video Standards”</a>.</p></td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>memory</code></em></td><td valign="top"> </td><td valign="top">This field must be set by applications and/or drivers 74in accordance with the selected I/O method. See <a class="xref" href="buffer.html#v4l2-memory" title="Table 3.5. enum v4l2_memory">Table 3.5, “enum v4l2_memory”</a></td></tr><tr><td valign="top">union</td><td valign="top"><em class="structfield"><code>m</code></em></td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td valign="top"> </td><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>offset</code></em></td><td valign="top">For the single-planar API and when 75<em class="structfield"><code>memory</code></em> is <code class="constant">V4L2_MEMORY_MMAP</code> this 76is the offset of the buffer from the start of the device memory. The value is 77returned by the driver and apart of serving as parameter to the <a class="link" href="func-mmap.html" title="V4L2 mmap()"><code class="function">mmap()</code></a> 78function not useful for applications. See <a class="xref" href="mmap.html" title="Streaming I/O (Memory Mapping)">the section called “Streaming I/O (Memory Mapping)”</a> for details 79 </td></tr><tr><td valign="top"> </td><td valign="top">unsigned long</td><td valign="top"><em class="structfield"><code>userptr</code></em></td><td valign="top">For the single-planar API and when 80<em class="structfield"><code>memory</code></em> is <code class="constant">V4L2_MEMORY_USERPTR</code> 81this is a pointer to the buffer (casted to unsigned long type) in virtual 82memory, set by the application. See <a class="xref" href="userp.html" title="Streaming I/O (User Pointers)">the section called “Streaming I/O (User Pointers)”</a> for details. 83 </td></tr><tr><td valign="top"> </td><td valign="top">struct v4l2_plane</td><td valign="top"><em class="structfield"><code>*planes</code></em></td><td valign="top">When using the multi-planar API, contains a userspace pointer 84 to an array of struct <a class="link" href="buffer.html#v4l2-plane" title="Table 3.2. struct v4l2_plane">v4l2_plane</a>. The size of the array should be put 85 in the <em class="structfield"><code>length</code></em> field of this 86 <span class="structname">v4l2_buffer</span> structure.</td></tr><tr><td valign="top"> </td><td valign="top">int</td><td valign="top"><em class="structfield"><code>fd</code></em></td><td valign="top">For the single-plane API and when 87<em class="structfield"><code>memory</code></em> is <code class="constant">V4L2_MEMORY_DMABUF</code> this 88is the file descriptor associated with a DMABUF buffer.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>length</code></em></td><td valign="top"> </td><td valign="top">Size of the buffer (not the payload) in bytes for the 89 single-planar API. This is set by the driver based on the calls to 90 <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> and/or <a class="link" href="vidioc-create-bufs.html" title="ioctl VIDIOC_CREATE_BUFS"><code class="constant">VIDIOC_CREATE_BUFS</code></a>. For the multi-planar API the application sets 91 this to the number of elements in the <em class="structfield"><code>planes</code></em> 92 array. The driver will fill in the actual number of valid elements in 93 that array. 94 </td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>reserved2</code></em></td><td valign="top"> </td><td valign="top">A place holder for future extensions. Drivers and applications 95must set this to 0.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>reserved</code></em></td><td valign="top"> </td><td valign="top">A place holder for future extensions. Drivers and applications 96must set this to 0.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-plane"></a><p class="title"><b>Table 3.2. struct <span class="structname">v4l2_plane</span></b></p><div class="table-contents"><table summary="struct v4l2_plane" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="c4"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>bytesused</code></em></td><td valign="top"> </td><td valign="top">The number of bytes occupied by data in the plane 97 (its payload). Drivers must set this field when <em class="structfield"><code>type</code></em> 98 refers to an input stream, applications when it refers to an output stream. 99 If the application sets this to 0 for an output stream, then 100 <em class="structfield"><code>bytesused</code></em> will be set to the size of the 101 plane (see the <em class="structfield"><code>length</code></em> field of this struct) 102 by the driver. Note that the actual image data starts at 103 <em class="structfield"><code>data_offset</code></em> which may not be 0.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>length</code></em></td><td valign="top"> </td><td valign="top">Size in bytes of the plane (not its payload). This is set by the driver 104 based on the calls to <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> and/or <a class="link" href="vidioc-create-bufs.html" title="ioctl VIDIOC_CREATE_BUFS"><code class="constant">VIDIOC_CREATE_BUFS</code></a>.</td></tr><tr><td valign="top">union</td><td valign="top"><em class="structfield"><code>m</code></em></td><td valign="top"> </td><td valign="top"> </td></tr><tr><td valign="top"> </td><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>mem_offset</code></em></td><td valign="top">When the memory type in the containing struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> is 105 <code class="constant">V4L2_MEMORY_MMAP</code>, this is the value that 106 should be passed to <a class="link" href="func-mmap.html" title="V4L2 mmap()"><code class="function">mmap()</code></a>, similar to the 107 <em class="structfield"><code>offset</code></em> field in struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a>.</td></tr><tr><td valign="top"> </td><td valign="top">unsigned long</td><td valign="top"><em class="structfield"><code>userptr</code></em></td><td valign="top">When the memory type in the containing struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> is 108 <code class="constant">V4L2_MEMORY_USERPTR</code>, this is a userspace 109 pointer to the memory allocated for this plane by an application. 110 </td></tr><tr><td valign="top"> </td><td valign="top">int</td><td valign="top"><em class="structfield"><code>fd</code></em></td><td valign="top">When the memory type in the containing struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> is 111 <code class="constant">V4L2_MEMORY_DMABUF</code>, this is a file 112 descriptor associated with a DMABUF buffer, similar to the 113 <em class="structfield"><code>fd</code></em> field in struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a>.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>data_offset</code></em></td><td valign="top"> </td><td valign="top">Offset in bytes to video data in the plane. 114 Drivers must set this field when <em class="structfield"><code>type</code></em> 115 refers to an input stream, applications when it refers to an output stream. 116 Note that data_offset is included in <em class="structfield"><code>bytesused</code></em>. 117 So the size of the image in the plane is 118 <em class="structfield"><code>bytesused</code></em>-<em class="structfield"><code>data_offset</code></em> at 119 offset <em class="structfield"><code>data_offset</code></em> from the start of the plane. 120 </td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>reserved[11]</code></em></td><td valign="top"> </td><td valign="top">Reserved for future use. Should be zeroed by drivers and 121 applications.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-buf-type"></a><p class="title"><b>Table 3.3. enum v4l2_buf_type</b></p><div class="table-contents"><table summary="enum v4l2_buf_type" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE</code></td><td valign="top">1</td><td valign="top">Buffer of a single-planar video capture stream, see <a class="xref" href="devices.html#capture" title="Video Capture Interface">the section called “Video Capture Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</code> 122 </td><td valign="top">9</td><td valign="top">Buffer of a multi-planar video capture stream, see <a class="xref" href="devices.html#capture" title="Video Capture Interface">the section called “Video Capture Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT</code></td><td valign="top">2</td><td valign="top">Buffer of a single-planar video output stream, see <a class="xref" href="output.html" title="Video Output Interface">the section called “Video Output Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</code> 123 </td><td valign="top">10</td><td valign="top">Buffer of a multi-planar video output stream, see <a class="xref" href="output.html" title="Video Output Interface">the section called “Video Output Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VIDEO_OVERLAY</code></td><td valign="top">3</td><td valign="top">Buffer for video overlay, see <a class="xref" href="overlay.html" title="Video Overlay Interface">the section called “Video Overlay Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VBI_CAPTURE</code></td><td valign="top">4</td><td valign="top">Buffer of a raw VBI capture stream, see <a class="xref" href="raw-vbi.html" title="Raw VBI Data Interface">the section called “Raw VBI Data Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VBI_OUTPUT</code></td><td valign="top">5</td><td valign="top">Buffer of a raw VBI output stream, see <a class="xref" href="raw-vbi.html" title="Raw VBI Data Interface">the section called “Raw VBI Data Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</code></td><td valign="top">6</td><td valign="top">Buffer of a sliced VBI capture stream, see <a class="xref" href="sliced.html" title="Sliced VBI Data Interface">the section called “Sliced VBI Data Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</code></td><td valign="top">7</td><td valign="top">Buffer of a sliced VBI output stream, see <a class="xref" href="sliced.html" title="Sliced VBI Data Interface">the section called “Sliced VBI Data Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</code></td><td valign="top">8</td><td valign="top">Buffer for video output overlay (OSD), see <a class="xref" href="osd.html" title="Video Output Overlay Interface">the section called “Video Output Overlay Interface”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_SDR_CAPTURE</code></td><td valign="top">11</td><td valign="top">Buffer for Software Defined Radio (SDR) capture stream, see 124 <a class="xref" href="sdr.html" title="Software Defined Radio Interface (SDR)">the section called “Software Defined Radio Interface (SDR)”</a>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_TYPE_SDR_OUTPUT</code></td><td valign="top">12</td><td valign="top">Buffer for Software Defined Radio (SDR) output stream, see 125 <a class="xref" href="sdr.html" title="Software Defined Radio Interface (SDR)">the section called “Software Defined Radio Interface (SDR)”</a>.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="buffer-flags"></a><p class="title"><b>Table 3.4. Buffer Flags</b></p><div class="table-contents"><table summary="Buffer Flags" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_MAPPED</code></td><td valign="top">0x00000001</td><td valign="top">The buffer resides in device memory and has been mapped 126into the application's address space, see <a class="xref" href="mmap.html" title="Streaming I/O (Memory Mapping)">the section called “Streaming I/O (Memory Mapping)”</a> for details. 127Drivers set or clear this flag when the 128<a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF">VIDIOC_QUERYBUF</a>, <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_QBUF</a> or <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_DQBUF</a> ioctl is called. Set by the driver.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_QUEUED</code></td><td valign="top">0x00000002</td><td valign="top">Internally drivers maintain two buffer queues, an 129incoming and outgoing queue. When this flag is set, the buffer is 130currently on the incoming queue. It automatically moves to the 131outgoing queue after the buffer has been filled (capture devices) or 132displayed (output devices). Drivers set or clear this flag when the 133<code class="constant">VIDIOC_QUERYBUF</code> ioctl is called. After 134(successful) calling the <code class="constant">VIDIOC_QBUF </code>ioctl it is 135always set and after <code class="constant">VIDIOC_DQBUF</code> always 136cleared.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_DONE</code></td><td valign="top">0x00000004</td><td valign="top">When this flag is set, the buffer is currently on 137the outgoing queue, ready to be dequeued from the driver. Drivers set 138or clear this flag when the <code class="constant">VIDIOC_QUERYBUF</code> ioctl 139is called. After calling the <code class="constant">VIDIOC_QBUF</code> or 140<code class="constant">VIDIOC_DQBUF</code> it is always cleared. Of course a 141buffer cannot be on both queues at the same time, the 142<code class="constant">V4L2_BUF_FLAG_QUEUED</code> and 143<code class="constant">V4L2_BUF_FLAG_DONE</code> flag are mutually exclusive. 144They can be both cleared however, then the buffer is in "dequeued" 145state, in the application domain so to say.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_ERROR</code></td><td valign="top">0x00000040</td><td valign="top">When this flag is set, the buffer has been dequeued 146 successfully, although the data might have been corrupted. 147 This is recoverable, streaming may continue as normal and 148 the buffer may be reused normally. 149 Drivers set this flag when the <code class="constant">VIDIOC_DQBUF</code> 150 ioctl is called.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_KEYFRAME</code></td><td valign="top">0x00000008</td><td valign="top">Drivers set or clear this flag when calling the 151<code class="constant">VIDIOC_DQBUF</code> ioctl. It may be set by video 152capture devices when the buffer contains a compressed image which is a 153key frame (or field), i. e. can be decompressed on its own. Also known as 154an I-frame. Applications can set this bit when <em class="structfield"><code>type</code></em> 155refers to an output stream.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_PFRAME</code></td><td valign="top">0x00000010</td><td valign="top">Similar to <code class="constant">V4L2_BUF_FLAG_KEYFRAME</code> 156this flags predicted frames or fields which contain only differences to a 157previous key frame. Applications can set this bit when <em class="structfield"><code>type</code></em> 158refers to an output stream.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_BFRAME</code></td><td valign="top">0x00000020</td><td valign="top">Similar to <code class="constant">V4L2_BUF_FLAG_KEYFRAME</code> 159this flags a bi-directional predicted frame or field which contains only 160the differences between the current frame and both the preceding and following 161key frames to specify its content. Applications can set this bit when 162<em class="structfield"><code>type</code></em> refers to an output stream.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TIMECODE</code></td><td valign="top">0x00000100</td><td valign="top">The <em class="structfield"><code>timecode</code></em> field is valid. 163Drivers set or clear this flag when the <code class="constant">VIDIOC_DQBUF</code> 164ioctl is called. Applications can set this bit and the corresponding 165<em class="structfield"><code>timecode</code></em> structure when <em class="structfield"><code>type</code></em> 166refers to an output stream.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_PREPARED</code></td><td valign="top">0x00000400</td><td valign="top">The buffer has been prepared for I/O and can be queued by the 167application. Drivers set or clear this flag when the 168<a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF">VIDIOC_QUERYBUF</a>, <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_PREPARE_BUF</a>, <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_QBUF</a> or <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_DQBUF</a> ioctl is called.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</code></td><td valign="top">0x00000800</td><td valign="top">Caches do not have to be invalidated for this buffer. 169Typically applications shall use this flag if the data captured in the buffer 170is not going to be touched by the CPU, instead the buffer will, probably, be 171passed on to a DMA-capable hardware unit for further processing or output. 172</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_NO_CACHE_CLEAN</code></td><td valign="top">0x00001000</td><td valign="top">Caches do not have to be cleaned for this buffer. 173Typically applications shall use this flag for output buffers if the data 174in this buffer has not been created by the CPU but by some DMA-capable unit, 175in which case caches have not been used.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_LAST</code></td><td valign="top">0x00100000</td><td valign="top">Last buffer produced by the hardware. mem2mem codec drivers 176set this flag on the capture queue for the last buffer when the 177<a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF">VIDIOC_QUERYBUF</a> or 178<a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_DQBUF</a> ioctl is called. Due to hardware 179limitations, the last buffer may be empty. In this case the driver will set the 180<em class="structfield"><code>bytesused</code></em> field to 0, regardless of the format. Any 181Any subsequent call to the <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF">VIDIOC_DQBUF</a> ioctl 182will not block anymore, but return an <span class="errorcode">EPIPE</span> error code.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TIMESTAMP_MASK</code></td><td valign="top">0x0000e000</td><td valign="top">Mask for timestamp types below. To test the 183 timestamp type, mask out bits not belonging to timestamp 184 type by performing a logical and operation with buffer 185 flags and timestamp mask.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</code></td><td valign="top">0x00000000</td><td valign="top">Unknown timestamp type. This type is used by 186 drivers before Linux 3.9 and may be either monotonic (see 187 below) or realtime (wall clock). Monotonic clock has been 188 favoured in embedded systems whereas most of the drivers 189 use the realtime clock. Either kinds of timestamps are 190 available in user space via 191 <code class="function">clock_gettime(2)</code> using clock IDs 192 <code class="constant">CLOCK_MONOTONIC</code> and 193 <code class="constant">CLOCK_REALTIME</code>, respectively.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</code></td><td valign="top">0x00002000</td><td valign="top">The buffer timestamp has been taken from the 194 <code class="constant">CLOCK_MONOTONIC</code> clock. To access the 195 same clock outside V4L2, use 196 <code class="function">clock_gettime(2)</code>.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TIMESTAMP_COPY</code></td><td valign="top">0x00004000</td><td valign="top">The CAPTURE buffer timestamp has been taken from the 197 corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TSTAMP_SRC_MASK</code></td><td valign="top">0x00070000</td><td valign="top">Mask for timestamp sources below. The timestamp source 198 defines the point of time the timestamp is taken in relation to 199 the frame. Logical 'and' operation between the 200 <em class="structfield"><code>flags</code></em> field and 201 <code class="constant">V4L2_BUF_FLAG_TSTAMP_SRC_MASK</code> produces the 202 value of the timestamp source. Applications must set the timestamp 203 source when <em class="structfield"><code>type</code></em> refers to an output stream 204 and <code class="constant">V4L2_BUF_FLAG_TIMESTAMP_COPY</code> is set.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TSTAMP_SRC_EOF</code></td><td valign="top">0x00000000</td><td valign="top">End Of Frame. The buffer timestamp has been taken 205 when the last pixel of the frame has been received or the 206 last pixel of the frame has been transmitted. In practice, 207 software generated timestamps will typically be read from 208 the clock a small amount of time after the last pixel has 209 been received or transmitten, depending on the system and 210 other activity in it.</td></tr><tr><td valign="top"><code class="constant">V4L2_BUF_FLAG_TSTAMP_SRC_SOE</code></td><td valign="top">0x00010000</td><td valign="top">Start Of Exposure. The buffer timestamp has been 211 taken when the exposure of the frame has begun. This is 212 only valid for the 213 <code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE</code> buffer 214 type.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-memory"></a><p class="title"><b>Table 3.5. enum v4l2_memory</b></p><div class="table-contents"><table summary="enum v4l2_memory" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_MEMORY_MMAP</code></td><td valign="top">1</td><td valign="top">The buffer is used for <a class="link" href="mmap.html" title="Streaming I/O (Memory Mapping)">memory 215mapping</a> I/O.</td></tr><tr><td valign="top"><code class="constant">V4L2_MEMORY_USERPTR</code></td><td valign="top">2</td><td valign="top">The buffer is used for <a class="link" href="userp.html" title="Streaming I/O (User Pointers)">user 216pointer</a> I/O.</td></tr><tr><td valign="top"><code class="constant">V4L2_MEMORY_OVERLAY</code></td><td valign="top">3</td><td valign="top">[to do]</td></tr><tr><td valign="top"><code class="constant">V4L2_MEMORY_DMABUF</code></td><td valign="top">4</td><td valign="top">The buffer is used for <a class="link" href="dmabuf.html" title="Streaming I/O (DMA buffer importing)">DMA shared 217buffer</a> I/O.</td></tr></tbody></table></div></div><br class="table-break"><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="id-1.4.6.14.9"></a>Timecodes</h3></div></div></div><p>The <span class="structname">v4l2_timecode</span> structure is 218designed to hold a <a class="xref" href="bi01.html#smpte12m" title='SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code"'>[<abbr class="abbrev">SMPTE 12M</abbr>]</a> or similar timecode. 219(struct <span class="structname">timeval</span> timestamps are stored in 220struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> field <em class="structfield"><code>timestamp</code></em>.)</p><div class="table"><a name="v4l2-timecode"></a><p class="title"><b>Table 3.6. struct <span class="structname">v4l2_timecode</span></b></p><div class="table-contents"><table summary="struct v4l2_timecode" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>type</code></em></td><td valign="top">Frame rate the timecodes are based on, see <a class="xref" href="buffer.html#timecode-type" title="Table 3.7. Timecode Types">Table 3.7, “Timecode Types”</a>.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>flags</code></em></td><td valign="top">Timecode flags, see <a class="xref" href="buffer.html#timecode-flags" title="Table 3.8. Timecode Flags">Table 3.8, “Timecode Flags”</a>.</td></tr><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>frames</code></em></td><td valign="top">Frame count, 0 ... 23/24/29/49/59, depending on the 221 type of timecode.</td></tr><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>seconds</code></em></td><td valign="top">Seconds count, 0 ... 59. This is a binary, not BCD number.</td></tr><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>minutes</code></em></td><td valign="top">Minutes count, 0 ... 59. This is a binary, not BCD number.</td></tr><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>hours</code></em></td><td valign="top">Hours count, 0 ... 29. This is a binary, not BCD number.</td></tr><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>userbits</code></em>[4]</td><td valign="top">The "user group" bits from the timecode.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="timecode-type"></a><p class="title"><b>Table 3.7. Timecode Types</b></p><div class="table-contents"><table summary="Timecode Types" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_TC_TYPE_24FPS</code></td><td valign="top">1</td><td valign="top">24 frames per second, i. e. film.</td></tr><tr><td valign="top"><code class="constant">V4L2_TC_TYPE_25FPS</code></td><td valign="top">2</td><td valign="top">25 frames per second, i. e. PAL or SECAM video.</td></tr><tr><td valign="top"><code class="constant">V4L2_TC_TYPE_30FPS</code></td><td valign="top">3</td><td valign="top">30 frames per second, i. e. NTSC video.</td></tr><tr><td valign="top"><code class="constant">V4L2_TC_TYPE_50FPS</code></td><td valign="top">4</td><td valign="top"> </td></tr><tr><td valign="top"><code class="constant">V4L2_TC_TYPE_60FPS</code></td><td valign="top">5</td><td valign="top"> </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="timecode-flags"></a><p class="title"><b>Table 3.8. Timecode Flags</b></p><div class="table-contents"><table summary="Timecode Flags" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_TC_FLAG_DROPFRAME</code></td><td valign="top">0x0001</td><td valign="top">Indicates "drop frame" semantics for counting frames 222in 29.97 fps material. When set, frame numbers 0 and 1 at the start of 223each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the 224count.</td></tr><tr><td valign="top"><code class="constant">V4L2_TC_FLAG_COLORFRAME</code></td><td valign="top">0x0002</td><td valign="top">The "color frame" flag.</td></tr><tr><td valign="top"><code class="constant">V4L2_TC_USERBITS_field</code></td><td valign="top">0x000C</td><td valign="top">Field mask for the "binary group flags".</td></tr><tr><td valign="top"><code class="constant">V4L2_TC_USERBITS_USERDEFINED</code></td><td valign="top">0x0000</td><td valign="top">Unspecified format.</td></tr><tr><td valign="top"><code class="constant">V4L2_TC_USERBITS_8BITCHARS</code></td><td valign="top">0x0008</td><td valign="top">8-bit ISO characters.</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="async.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="field-order.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Asynchronous I/O </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Field Order</td></tr></table></div></body></html> 225