Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 22a437cd authored by Hans Verkuil's avatar Hans Verkuil Committed by Mauro Carvalho Chehab
Browse files

[media] DocBook media: clarify v4l2_buffer/plane fields 



Be more specific as to who has to fill in each field/flag: the driver
or the application.

Signed-off-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <m.chehab@samsung.com>
parent 26092ffb

Documentation/DocBook/media/v4l/io.xml

+36 −18
Original line number Original line Diff line number Diff line
@@ -676,10 +676,11 @@ plane structures.</para> 
	    <entry>__u32</entry>

	    <entry>__u32</entry>

	    <entry><structfield>index</structfield></entry>

	    <entry><structfield>index</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Number of the buffer, set by the application. This

	    <entry>Number of the buffer, set by the application except

field is only used for <link linkend="mmap">memory mapping</link> I/O

when calling &VIDIOC-DQBUF;, then it is set by the driver.

and can range from zero to the number of buffers allocated

This field can range from zero to the number of buffers allocated

with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>

with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>),

plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry>

	  </row>

	  </row>

	  <row>

	  <row>

	    <entry>__u32</entry>

	    <entry>__u32</entry>
@@ -698,7 +699,7 @@ linkend="v4l2-buf-type" /></entry> 
buffer. It depends on the negotiated data format and may change with

buffer. It depends on the negotiated data format and may change with

each buffer for compressed variable size data like JPEG images.

each buffer for compressed variable size data like JPEG images.

Drivers must set this field when <structfield>type</structfield>

Drivers must set this field when <structfield>type</structfield>

refers to an input stream, applications when an output stream.</entry>

refers to an input stream, applications when it refers to an output stream.</entry>

	  </row>

	  </row>

	  <row>

	  <row>

	    <entry>__u32</entry>

	    <entry>__u32</entry>
@@ -715,7 +716,7 @@ linkend="buffer-flags" />.</entry> 
buffer, see <xref linkend="v4l2-field" />. This field is not used when

buffer, see <xref linkend="v4l2-field" />. This field is not used when

the buffer contains VBI data. Drivers must set it when

the buffer contains VBI data. Drivers must set it when

<structfield>type</structfield> refers to an input stream,

<structfield>type</structfield> refers to an input stream,

applications when an output stream.</entry>

applications when it refers to an output stream.</entry>

	  </row>

	  </row>

	  <row>

	  <row>

	    <entry>struct timeval</entry>

	    <entry>struct timeval</entry>
@@ -729,7 +730,9 @@ applications when an output stream.</entry> 
	    stores the time at which the last data byte was actually sent out

	    stores the time at which the last data byte was actually sent out

	    in the  <structfield>timestamp</structfield> field. This permits

	    in the  <structfield>timestamp</structfield> field. This permits

	    applications to monitor the drift between the video and system

	    applications to monitor the drift between the video and system

	    clock.</para></entry>

	    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>

	  <row>

	  <row>

	    <entry>&v4l2-timecode;</entry>

	    <entry>&v4l2-timecode;</entry>
@@ -822,7 +825,8 @@ is the file descriptor associated with a DMABUF buffer.</entry> 
	    <entry><structfield>length</structfield></entry>

	    <entry><structfield>length</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Size of the buffer (not the payload) in bytes for the

	    <entry>Size of the buffer (not the payload) in bytes for the

	    single-planar API. For the multi-planar API the application sets

	    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>

	    this to the number of elements in the <structfield>planes</structfield>

	    array. The driver will fill in the actual number of valid elements in

	    array. The driver will fill in the actual number of valid elements in

	    that array.

	    that array.
@@ -856,13 +860,15 @@ should set this to 0.</entry> 
	    <entry><structfield>bytesused</structfield></entry>

	    <entry><structfield>bytesused</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>The number of bytes occupied by data in the plane

	    <entry>The number of bytes occupied by data in the plane

	    (its payload).</entry>

	      (its payload). Drivers must set this field when <structfield>type</structfield>

	      refers to an input stream, applications when it refers to an output stream.</entry>

	  </row>

	  </row>

	  <row>

	  <row>

	    <entry>__u32</entry>

	    <entry>__u32</entry>

	    <entry><structfield>length</structfield></entry>

	    <entry><structfield>length</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Size in bytes of the plane (not its payload).</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>

	  <row>

	  <row>

	    <entry>union</entry>

	    <entry>union</entry>
@@ -901,7 +907,9 @@ should set this to 0.</entry> 
	    <entry>__u32</entry>

	    <entry>__u32</entry>

	    <entry><structfield>data_offset</structfield></entry>

	    <entry><structfield>data_offset</structfield></entry>

	    <entry></entry>

	    <entry></entry>

	    <entry>Offset in bytes to video data in the plane, if applicable.

	    <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.

	    </entry>

	    </entry>

	  </row>

	  </row>

	  <row>

	  <row>
@@ -1031,7 +1039,7 @@ buffer cannot be on both queues at the same time, the 
<constant>V4L2_BUF_FLAG_QUEUED</constant> and

<constant>V4L2_BUF_FLAG_QUEUED</constant> and

<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.

<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.

They can be both cleared however, then the buffer is in "dequeued"

They can be both cleared however, then the buffer is in "dequeued"

state, in the application domain to say so.</entry>

state, in the application domain so to say.</entry>

	  </row>

	  </row>

	  <row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>

	    <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
@@ -1049,27 +1057,35 @@ state, in the application domain to say so.</entry> 
	  <entry>Drivers set or clear this flag when calling the

	  <entry>Drivers set or clear this flag when calling the

<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video

<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video

capture devices when the buffer contains a compressed image which is a

capture devices when the buffer contains a compressed image which is a

key frame (or field), &ie; can be decompressed on its own.</entry>

key frame (or field), &ie; can be decompressed on its own. Also know as

an I-frame.  Applications can set this bit when <structfield>type</structfield>

refers to an output stream.</entry>

	  </row>

	  </row>

	  <row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>

	    <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>

	    <entry>0x00000010</entry>

	    <entry>0x00000010</entry>

	    <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>

	    <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>

this flags predicted frames or fields which contain only differences to a

this flags predicted frames or fields which contain only differences to a

previous key frame.</entry>

previous key frame. Applications can set this bit when <structfield>type</structfield>

refers to an output stream.</entry>

	  </row>

	  </row>

	  <row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>

	    <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>

	    <entry>0x00000020</entry>

	    <entry>0x00000020</entry>

	    <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>

	    <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>

	this is a bidirectional predicted frame or field. [ooc tbd]</entry>

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>

	  <row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>

	    <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>

	    <entry>0x00000100</entry>

	    <entry>0x00000100</entry>

	    <entry>The <structfield>timecode</structfield> field is valid.

	    <entry>The <structfield>timecode</structfield> field is valid.

Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>

Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>

ioctl is called.</entry>

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>

	  <row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>

	    <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
@@ -1141,7 +1157,9 @@ in which case caches have not been used.</entry> 
	    the frame. Logical 'and' operation between the

	    the frame. Logical 'and' operation between the

	    <structfield>flags</structfield> field and

	    <structfield>flags</structfield> field and

	    <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the

	    <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the

	    value of the timestamp source.</entry>

	    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>

	  <row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>

	    <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>