diff options
112 files changed, 15395 insertions, 31022 deletions
diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index 21893ee1384a..ac58966ccb9b 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -48,236 +48,149 @@ struct v4l2_buffer :stub-columns: 0 :widths: 1 2 1 10 - - - .. row 1 - - - __u32 - - - ``index`` - - - - - Number of the buffer, set by the application except when calling - :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the - driver. This field can range from zero to the number of buffers - allocated with the :ref:`VIDIOC_REQBUFS` ioctl - (struct :c:type:`v4l2_requestbuffers` - ``count``), plus any buffers allocated with - :ref:`VIDIOC_CREATE_BUFS` minus one. - - - .. row 2 - - - __u32 - - - ``type`` - - - - - Type of the buffer, same as struct - :c:type:`v4l2_format` ``type`` or struct - :c:type:`v4l2_requestbuffers` ``type``, set - by the application. See :c:type:`v4l2_buf_type` - - - .. row 3 - - - __u32 - - - ``bytesused`` - - - - - 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 ``type`` refers to a capture stream, applications - when it refers to an output stream. If the application sets this - to 0 for an output stream, then ``bytesused`` will be set to the - size of the buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the - ``planes`` pointer is used instead. - - - .. row 4 - - - __u32 - - - ``flags`` - - - - - Flags set by the application or driver, see :ref:`buffer-flags`. - - - .. row 5 - - - __u32 - - - ``field`` - - - - - Indicates the field order of the image in the buffer, see - :c:type:`v4l2_field`. This field is not used when the buffer - contains VBI data. Drivers must set it when ``type`` refers to a - capture stream, applications when it refers to an output stream. - - - .. row 6 - - - struct timeval - - - ``timestamp`` - - - - - For capture streams this is time when the first data byte was - captured, as returned by the :c:func:`clock_gettime()` function - for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in - :ref:`buffer-flags`. For output streams the driver stores the - time at which the last data byte was actually sent out in the - ``timestamp`` field. This permits applications to monitor the - drift between the video and system clock. For output streams that - use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill - in the timestamp which will be copied by the driver to the capture - stream. - - - .. row 7 - - - struct :c:type:`v4l2_timecode` - - - ``timecode`` - - - - - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the - ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this - structure contains a frame timecode. In - :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` 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 ``timestamp`` and ``sequence`` fields. - - - .. row 8 - - - __u32 - - - ``sequence`` - - - - - Set by the driver, counting the frames (not fields!) in sequence. - This field is set for both input and output devices. - - - .. row 9 - - - :cspan:`3` - - In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` 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. - - .. 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 - :ref:`standard`. - - - - .. row 10 - - - __u32 - - - ``memory`` - - - - - This field must be set by applications and/or drivers in - accordance with the selected I/O method. See :c:type:`v4l2_memory` - - - .. row 11 - - - union - - - ``m`` - - - |