Lines Matching +full:frame +full:- +full:buffer
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
10 A buffer contains data exchanged by application and driver using one of
11 the Streaming I/O methods. In the multi-planar API, the data is held in
12 planes, while the buffer structure acts as a container for the planes.
14 copied. These pointers, together with meta-information like timestamps
18 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
19 some plane-specific members of struct :c:type:`v4l2_buffer`,
25 part of the frame and with which clock the timestamp is taken. Please
27 ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
33 mem-to-mem devices is an exception to the rule: the timestamp source
34 flags are copied from the OUTPUT video buffer to the CAPTURE video
35 buffer.
40 V4L2 exposes parameters that influence the buffer size, or the way data is
41 laid out in the buffer. Those parameters are exposed through both formats and
43 that modifies the direction in which pixels are stored in the buffer, as well
44 as the buffer size when the selected format includes padding at the end of
47 The set of information needed to interpret the content of a buffer (e.g. the
49 collectively referred to in the rest of this section as the buffer layout.
51 Controls that can modify the buffer layout shall set the
54 Modifying formats or controls that influence the buffer size or layout require
69 selection rectangles. When those ioctls result in a buffer size or layout
73 Controls that only influence the buffer layout can be modified at any time
74 when the stream is stopped. As they don't influence the buffer size, no
75 special handling is needed to synchronize those controls with buffer
79 Formats and controls that influence the buffer size interact with buffer
99 value into account to compute the buffer size to allocate. Applications can
111 influences the buffer size while buffers are allocated shall cause the format
113 buffer too small for the current format or controls shall cause the
116 Buffer reallocation is an expensive operation. To avoid that cost, drivers can
117 (and are encouraged to) allow format or controls that influence the buffer
132 allowed to return a ``EBUSY`` error from these ioctls if any buffer is
136 :c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the
140 Userspace applications can query the buffer size required for a given format
143 buffer size.
164 .. flat-table:: struct v4l2_buffer
165 :header-rows: 0
166 :stub-columns: 0
169 * - __u32
170 - ``index``
171 - Number of the buffer, set by the application except when calling
178 * - __u32
179 - ``type``
180 - Type of the buffer, same as struct
184 * - __u32
185 - ``bytesused``
186 - The number of bytes occupied by the data in the buffer. It depends
187 on the negotiated data format and may change with each buffer for
192 size of the buffer (see the ``length`` field of this struct) by
195 * - __u32
196 - ``flags``
197 - Flags set by the application or driver, see :ref:`buffer-flags`.
198 * - __u32
199 - ``field``
200 - Indicates the field order of the image in the buffer, see
201 :c:type:`v4l2_field`. This field is not used when the buffer
204 * - struct timeval
205 - ``timestamp``
206 - For capture streams this is time when the first data byte was
209 :ref:`buffer-flags`. For output streams the driver stores the
216 * - struct :c:type:`v4l2_timecode`
217 - ``timecode``
218 - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
219 structure contains a frame timecode. In
225 * - __u32
226 - ``sequence``
227 - Set by the driver, counting the frames (not fields!) in sequence.
229 * - :cspan:`2`
233 zero and includes dropped or repeated frames. A dropped frame was
235 free buffer space. A repeated frame was displayed again by an
247 * - __u32
248 - ``memory``
249 - This field must be set by applications and/or drivers in
251 * - union {
252 - ``m``
253 * - __u32
254 - ``offset``
255 - For the single-planar API and when ``memory`` is
256 ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
261 * - unsigned long
262 - ``userptr``
263 - For the single-planar API and when ``memory`` is
264 ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
267 * - struct v4l2_plane
268 - ``*planes``
269 - When using the multi-planar API, contains a userspace pointer to
273 * - int
274 - ``fd``
275 - For the single-plane API and when ``memory`` is
277 a DMABUF buffer.
278 * - }
279 -
280 * - __u32
281 - ``length``
282 - Size of the buffer (not the payload) in bytes for the
283 single-planar API. This is set by the driver based on the calls to
286 multi-planar API the application sets this to the number of
289 * - __u32
290 - ``reserved2``
291 - A place holder for future extensions. Drivers and applications
293 * - __u32
294 - ``request_fd``
295 - The file descriptor of the request to queue the buffer to. If the flag
296 ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be
321 .. flat-table::
322 :header-rows: 0
323 :stub-columns: 0
326 * - __u32
327 - ``bytesused``
328 - The number of bytes occupied by data in the plane (its payload).
339 * - __u32
340 - ``length``
341 - Size in bytes of the plane (not its payload). This is set by the
345 * - union {
346 - ``m``
347 * - __u32
348 - ``mem_offset``
349 - When the memory type in the containing struct
354 * - unsigned long
355 - ``userptr``
356 - When the memory type in the containing struct
360 * - int
361 - ``fd``
362 - When the memory type in the containing struct
364 this is a file descriptor associated with a DMABUF buffer, similar
366 * - }
367 -
368 * - __u32
369 - ``data_offset``
370 - Offset in bytes to video data in the plane. Drivers must set this
377 size of the image in the plane is ``bytesused``-``data_offset``
379 * - __u32
380 - ``reserved[11]``
381 - Reserved for future use. Should be zeroed by drivers and
394 .. flat-table::
395 :header-rows: 0
396 :stub-columns: 0
399 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
400 - 1
401 - Buffer of a single-planar video capture stream, see
403 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
404 - 9
405 - Buffer of a multi-planar video capture stream, see
407 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
408 - 2
409 - Buffer of a single-planar video output stream, see
411 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
412 - 10
413 - Buffer of a multi-planar video output stream, see :ref:`output`.
414 * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
415 - 3
416 - Buffer for video overlay, see :ref:`overlay`.
417 * - ``V4L2_BUF_TYPE_VBI_CAPTURE``
418 - 4
419 - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
420 * - ``V4L2_BUF_TYPE_VBI_OUTPUT``
421 - 5
422 - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
423 * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
424 - 6
425 - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
426 * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
427 - 7
428 - Buffer of a sliced VBI output stream, see :ref:`sliced`.
429 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
430 - 8
431 - Buffer for video output overlay (OSD), see :ref:`osd`.
432 * - ``V4L2_BUF_TYPE_SDR_CAPTURE``
433 - 11
434 - Buffer for Software Defined Radio (SDR) capture stream, see
436 * - ``V4L2_BUF_TYPE_SDR_OUTPUT``
437 - 12
438 - Buffer for Software Defined Radio (SDR) output stream, see
440 * - ``V4L2_BUF_TYPE_META_CAPTURE``
441 - 13
442 - Buffer for metadata capture, see :ref:`metadata`.
443 * - ``V4L2_BUF_TYPE_META_OUTPUT``
444 - 14
445 - Buffer for metadata output, see :ref:`metadata`.
448 .. _buffer-flags:
450 Buffer Flags
461 .. flat-table::
462 :header-rows: 0
463 :stub-columns: 0
466 * .. _`V4L2-BUF-FLAG-MAPPED`:
468 - ``V4L2_BUF_FLAG_MAPPED``
469 - 0x00000001
470 - The buffer resides in device memory and has been mapped into the
477 * .. _`V4L2-BUF-FLAG-QUEUED`:
479 - ``V4L2_BUF_FLAG_QUEUED``
480 - 0x00000002
481 - Internally drivers maintain two buffer queues, an incoming and
482 outgoing queue. When this flag is set, the buffer is currently on
484 after the buffer has been filled (capture devices) or displayed
489 * .. _`V4L2-BUF-FLAG-DONE`:
491 - ``V4L2_BUF_FLAG_DONE``
492 - 0x00000004
493 - When this flag is set, the buffer is currently on the outgoing
497 cleared. Of course a buffer cannot be on both queues at the same
500 buffer is in "dequeued" state, in the application domain so to
502 * .. _`V4L2-BUF-FLAG-ERROR`:
504 - ``V4L2_BUF_FLAG_ERROR``
505 - 0x00000040
506 - When this flag is set, the buffer has been dequeued successfully,
508 streaming may continue as normal and the buffer may be reused
511 * .. _`V4L2-BUF-FLAG-IN-REQUEST`:
513 - ``V4L2_BUF_FLAG_IN_REQUEST``
514 - 0x00000080
515 - This buffer is part of a request that hasn't been queued yet.
516 * .. _`V4L2-BUF-FLAG-KEYFRAME`:
518 - ``V4L2_BUF_FLAG_KEYFRAME``
519 - 0x00000008
520 - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
521 ioctl. It may be set by video capture devices when the buffer
522 contains a compressed image which is a key frame (or field), i. e.
523 can be decompressed on its own. Also known as an I-frame.
526 * .. _`V4L2-BUF-FLAG-PFRAME`:
528 - ``V4L2_BUF_FLAG_PFRAME``
529 - 0x00000010
530 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
531 or fields which contain only differences to a previous key frame.
534 * .. _`V4L2-BUF-FLAG-BFRAME`:
536 - ``V4L2_BUF_FLAG_BFRAME``
537 - 0x00000020
538 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
539 predicted frame or field which contains only the differences
540 between the current frame and both the preceding and following key
543 * .. _`V4L2-BUF-FLAG-TIMECODE`:
545 - ``V4L2_BUF_FLAG_TIMECODE``
546 - 0x00000100
547 - The ``timecode`` field is valid. Drivers set or clear this flag
551 * .. _`V4L2-BUF-FLAG-PREPARED`:
553 - ``V4L2_BUF_FLAG_PREPARED``
554 - 0x00000400
555 - The buffer has been prepared for I/O and can be queued by the
561 * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`:
563 - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
564 - 0x00000800
565 - Caches do not have to be invalidated for this buffer. Typically
567 buffer is not going to be touched by the CPU, instead the buffer
568 will, probably, be passed on to a DMA-capable hardware unit for
572 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
573 * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
575 - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
576 - 0x00001000
577 - Caches do not have to be cleaned for this buffer. Typically
579 this buffer has not been created by the CPU but by some
580 DMA-capable unit, in which case caches have not been used. This flag
583 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
584 * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`:
586 - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF``
587 - 0x00000200
588 - Only valid if ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is
590 output buffers each decode to a slice of the decoded frame.
591 Applications can set this flag when queueing the output buffer
592 to prevent the driver from dequeueing the capture buffer after
593 the output buffer has been decoded (i.e. the capture buffer is
594 'held'). If the timestamp of this output buffer differs from that
595 of the previous output buffer, then that indicates the start of a
596 new frame and the previously held capture buffer is dequeued.
597 * .. _`V4L2-BUF-FLAG-LAST`:
599 - ``V4L2_BUF_FLAG_LAST``
600 - 0x00100000
601 - Last buffer produced by the hardware. mem2mem codec drivers set
602 this flag on the capture queue for the last buffer when the
605 hardware limitations, the last buffer may be empty. In this case
610 * .. _`V4L2-BUF-FLAG-REQUEST-FD`:
612 - ``V4L2_BUF_FLAG_REQUEST_FD``
613 - 0x00800000
614 - The ``request_fd`` field contains a valid file descriptor.
615 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`:
617 - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
618 - 0x0000e000
619 - Mask for timestamp types below. To test the timestamp type, mask
621 and operation with buffer flags and timestamp mask.
622 * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`:
624 - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
625 - 0x00000000
626 - Unknown timestamp type. This type is used by drivers before Linux
633 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`:
635 - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
636 - 0x00002000
637 - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
640 * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`:
642 - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
643 - 0x00004000
644 - The CAPTURE buffer timestamp has been taken from the corresponding
645 OUTPUT buffer. This flag applies only to mem2mem devices.
646 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`:
648 - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
649 - 0x00070000
650 - Mask for timestamp sources below. The timestamp source defines the
651 point of time the timestamp is taken in relation to the frame.
657 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`:
659 - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
660 - 0x00000000
661 - End Of Frame. The buffer timestamp has been taken when the last
662 pixel of the frame has been received or the last pixel of the
663 frame has been transmitted. In practice, software generated
667 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`:
669 - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
670 - 0x00010000
671 - Start Of Exposure. The buffer timestamp has been taken when the
672 exposure of the frame has begun. This is only valid for the
673 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
679 .. _memory-flags:
686 .. flat-table::
687 :header-rows: 0
688 :stub-columns: 0
691 * - ``V4L2_MEMORY_MMAP``
692 - 1
693 - The buffer is used for :ref:`memory mapping <mmap>` I/O.
694 * - ``V4L2_MEMORY_USERPTR``
695 - 2
696 - The buffer is used for :ref:`user pointer <userp>` I/O.
697 * - ``V4L2_MEMORY_OVERLAY``
698 - 3
699 - [to do]
700 * - ``V4L2_MEMORY_DMABUF``
701 - 4
702 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
716 --------------------
720 .. flat-table::
721 :header-rows: 0
722 :stub-columns: 0
725 * - __u32
726 - ``type``
727 - Frame rate the timecodes are based on, see :ref:`timecode-type`.
728 * - __u32
729 - ``flags``
730 - Timecode flags, see :ref:`timecode-flags`.
731 * - __u8
732 - ``frames``
733 - Frame count, 0 ... 23/24/29/49/59, depending on the type of
735 * - __u8
736 - ``seconds``
737 - Seconds count, 0 ... 59. This is a binary, not BCD number.
738 * - __u8
739 - ``minutes``
740 - Minutes count, 0 ... 59. This is a binary, not BCD number.
741 * - __u8
742 - ``hours``
743 - Hours count, 0 ... 29. This is a binary, not BCD number.
744 * - __u8
745 - ``userbits``\ [4]
746 - The "user group" bits from the timecode.
749 .. _timecode-type:
752 --------------
756 .. flat-table::
757 :header-rows: 0
758 :stub-columns: 0
761 * - ``V4L2_TC_TYPE_24FPS``
762 - 1
763 - 24 frames per second, i. e. film.
764 * - ``V4L2_TC_TYPE_25FPS``
765 - 2
766 - 25 frames per second, i. e. PAL or SECAM video.
767 * - ``V4L2_TC_TYPE_30FPS``
768 - 3
769 - 30 frames per second, i. e. NTSC video.
770 * - ``V4L2_TC_TYPE_50FPS``
771 - 4
772 -
773 * - ``V4L2_TC_TYPE_60FPS``
774 - 5
775 -
778 .. _timecode-flags:
781 --------------
785 .. flat-table::
786 :header-rows: 0
787 :stub-columns: 0
790 * - ``V4L2_TC_FLAG_DROPFRAME``
791 - 0x0001
792 - Indicates "drop frame" semantics for counting frames in 29.97 fps
793 material. When set, frame numbers 0 and 1 at the start of each
796 * - ``V4L2_TC_FLAG_COLORFRAME``
797 - 0x0002
798 - The "color frame" flag.
799 * - ``V4L2_TC_USERBITS_field``
800 - 0x000C
801 - Field mask for the "binary group flags".
802 * - ``V4L2_TC_USERBITS_USERDEFINED``
803 - 0x0000
804 - Unspecified format.
805 * - ``V4L2_TC_USERBITS_8BITCHARS``
806 - 0x0008
807 - 8-bit ISO characters.