1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><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#idp1104802220">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. Applications 95should 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. Applications 96should 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 an 121 application.</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), see <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 124into 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. 125Drivers set or clear this flag when the 126<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 127incoming and outgoing queue. When this flag is set, the buffer is 128currently on the incoming queue. It automatically moves to the 129outgoing queue after the buffer has been filled (capture devices) or 130displayed (output devices). Drivers set or clear this flag when the 131<code class="constant">VIDIOC_QUERYBUF</code> ioctl is called. After 132(successful) calling the <code class="constant">VIDIOC_QBUF </code>ioctl it is 133always set and after <code class="constant">VIDIOC_DQBUF</code> always 134cleared.</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 135the outgoing queue, ready to be dequeued from the driver. Drivers set 136or clear this flag when the <code class="constant">VIDIOC_QUERYBUF</code> ioctl 137is called. After calling the <code class="constant">VIDIOC_QBUF</code> or 138<code class="constant">VIDIOC_DQBUF</code> it is always cleared. Of course a 139buffer cannot be on both queues at the same time, the 140<code class="constant">V4L2_BUF_FLAG_QUEUED</code> and 141<code class="constant">V4L2_BUF_FLAG_DONE</code> flag are mutually exclusive. 142They can be both cleared however, then the buffer is in "dequeued" 143state, 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 144 successfully, although the data might have been corrupted. 145 This is recoverable, streaming may continue as normal and 146 the buffer may be reused normally. 147 Drivers set this flag when the <code class="constant">VIDIOC_DQBUF</code> 148 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 149<code class="constant">VIDIOC_DQBUF</code> ioctl. It may be set by video 150capture devices when the buffer contains a compressed image which is a 151key frame (or field), i. e. can be decompressed on its own. Also known as 152an I-frame. Applications can set this bit when <em class="structfield"><code>type</code></em> 153refers 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> 154this flags predicted frames or fields which contain only differences to a 155previous key frame. Applications can set this bit when <em class="structfield"><code>type</code></em> 156refers 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> 157this flags a bi-directional predicted frame or field which contains only 158the differences between the current frame and both the preceding and following 159key frames to specify its content. Applications can set this bit when 160<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. 161Drivers set or clear this flag when the <code class="constant">VIDIOC_DQBUF</code> 162ioctl is called. Applications can set this bit and the corresponding 163<em class="structfield"><code>timecode</code></em> structure when <em class="structfield"><code>type</code></em> 164refers 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 165application. Drivers set or clear this flag when the 166<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. 167Typically applications shall use this flag if the data captured in the buffer 168is not going to be touched by the CPU, instead the buffer will, probably, be 169passed on to a DMA-capable hardware unit for further processing or output. 170</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. 171Typically applications shall use this flag for output buffers if the data 172in this buffer has not been created by the CPU but by some DMA-capable unit, 173in which case caches have not been used.</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 174 timestamp type, mask out bits not belonging to timestamp 175 type by performing a logical and operation with buffer 176 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 177 drivers before Linux 3.9 and may be either monotonic (see 178 below) or realtime (wall clock). Monotonic clock has been 179 favoured in embedded systems whereas most of the drivers 180 use the realtime clock. Either kinds of timestamps are 181 available in user space via 182 <code class="function">clock_gettime(2)</code> using clock IDs 183 <code class="constant">CLOCK_MONOTONIC</code> and 184 <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 185 <code class="constant">CLOCK_MONOTONIC</code> clock. To access the 186 same clock outside V4L2, use 187 <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 188 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 189 defines the point of time the timestamp is taken in relation to 190 the frame. Logical 'and' operation between the 191 <em class="structfield"><code>flags</code></em> field and 192 <code class="constant">V4L2_BUF_FLAG_TSTAMP_SRC_MASK</code> produces the 193 value of the timestamp source. Applications must set the timestamp 194 source when <em class="structfield"><code>type</code></em> refers to an output stream 195 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 196 when the last pixel of the frame has been received or the 197 last pixel of the frame has been transmitted. In practice, 198 software generated timestamps will typically be read from 199 the clock a small amount of time after the last pixel has 200 been received or transmitten, depending on the system and 201 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 202 taken when the exposure of the frame has begun. This is 203 only valid for the 204 <code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE</code> buffer 205 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 206mapping</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 207pointer</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 208buffer</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="idp1104802220"></a>Timecodes</h3></div></div></div><p>The <span class="structname">v4l2_timecode</span> structure is 209designed 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. 210(struct <span class="structname">timeval</span> timestamps are stored in 211struct <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 212 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 213in 29.97 fps material. When set, frame numbers 0 and 1 at the start of 214each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the 215count.</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> 216