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
193 * - __u32
194 - ``flags``
195 - Flags set by the application or driver, see :ref:`buffer-flags`.
196 * - __u32
197 - ``field``
198 - Indicates the field order of the image in the buffer, see
199 :c:type:`v4l2_field`. This field is not used when the buffer
202 * - struct timeval
203 - ``timestamp``
204 - For capture streams this is time when the first data byte was
207 :ref:`buffer-flags`. For output streams the driver stores the
214 * - struct :c:type:`v4l2_timecode`
215 - ``timecode``
216 - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
217 structure contains a frame timecode. In
223 * - __u32
224 - ``sequence``
225 - Set by the driver, counting the frames (not fields!) in sequence.
227 * - :cspan:`2`
231 zero and includes dropped or repeated frames. A dropped frame was
233 free buffer space. A repeated frame was displayed again by an
245 * - __u32
246 - ``memory``
247 - This field must be set by applications and/or drivers in
249 * - union {
250 - ``m``
251 * - __u32
252 - ``offset``
253 - For the single-planar API and when ``memory`` is
254 ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
259 * - unsigned long
260 - ``userptr``
261 - For the single-planar API and when ``memory`` is
262 ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
265 * - struct v4l2_plane
266 - ``*planes``
267 - When using the multi-planar API, contains a userspace pointer to
271 * - int
272 - ``fd``
273 - For the single-plane API and when ``memory`` is
275 a DMABUF buffer.
276 * - }
277 -
278 * - __u32
279 - ``length``
280 - Size of the buffer (not the payload) in bytes for the
281 single-planar API. This is set by the driver based on the calls to
284 multi-planar API the application sets this to the number of
287 * - __u32
288 - ``reserved2``
289 - A place holder for future extensions. Drivers and applications
291 * - __u32
292 - ``request_fd``
293 - The file descriptor of the request to queue the buffer to. If the flag
294 ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be
319 .. flat-table::
320 :header-rows: 0
321 :stub-columns: 0
324 * - __u32
325 - ``bytesused``
326 - The number of bytes occupied by data in the plane (its payload).
334 * - __u32
335 - ``length``
336 - Size in bytes of the plane (not its payload). This is set by the
340 * - union {
341 - ``m``
342 * - __u32
343 - ``mem_offset``
344 - When the memory type in the containing struct
349 * - unsigned long
350 - ``userptr``
351 - When the memory type in the containing struct
355 * - int
356 - ``fd``
357 - When the memory type in the containing struct
359 this is a file descriptor associated with a DMABUF buffer, similar
361 * - }
362 -
363 * - __u32
364 - ``data_offset``
365 - Offset in bytes to video data in the plane. Drivers must set this
372 size of the image in the plane is ``bytesused``-``data_offset``
374 * - __u32
375 - ``reserved[11]``
376 - Reserved for future use. Should be zeroed by drivers and
389 .. flat-table::
390 :header-rows: 0
391 :stub-columns: 0
394 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
395 - 1
396 - Buffer of a single-planar video capture stream, see
398 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
399 - 9
400 - Buffer of a multi-planar video capture stream, see
402 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
403 - 2
404 - Buffer of a single-planar video output stream, see
406 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
407 - 10
408 - Buffer of a multi-planar video output stream, see :ref:`output`.
409 * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
410 - 3
411 - Buffer for video overlay, see :ref:`overlay`.
412 * - ``V4L2_BUF_TYPE_VBI_CAPTURE``
413 - 4
414 - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
415 * - ``V4L2_BUF_TYPE_VBI_OUTPUT``
416 - 5
417 - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
418 * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
419 - 6
420 - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
421 * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
422 - 7
423 - Buffer of a sliced VBI output stream, see :ref:`sliced`.
424 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
425 - 8
426 - Buffer for video output overlay (OSD), see :ref:`osd`.
427 * - ``V4L2_BUF_TYPE_SDR_CAPTURE``
428 - 11
429 - Buffer for Software Defined Radio (SDR) capture stream, see
431 * - ``V4L2_BUF_TYPE_SDR_OUTPUT``
432 - 12
433 - Buffer for Software Defined Radio (SDR) output stream, see
435 * - ``V4L2_BUF_TYPE_META_CAPTURE``
436 - 13
437 - Buffer for metadata capture, see :ref:`metadata`.
438 * - ``V4L2_BUF_TYPE_META_OUTPUT``
439 - 14
440 - Buffer for metadata output, see :ref:`metadata`.
443 .. _buffer-flags:
445 Buffer Flags
456 .. flat-table::
457 :header-rows: 0
458 :stub-columns: 0
461 * .. _`V4L2-BUF-FLAG-MAPPED`:
463 - ``V4L2_BUF_FLAG_MAPPED``
464 - 0x00000001
465 - The buffer resides in device memory and has been mapped into the
472 * .. _`V4L2-BUF-FLAG-QUEUED`:
474 - ``V4L2_BUF_FLAG_QUEUED``
475 - 0x00000002
476 - Internally drivers maintain two buffer queues, an incoming and
477 outgoing queue. When this flag is set, the buffer is currently on
479 after the buffer has been filled (capture devices) or displayed
484 * .. _`V4L2-BUF-FLAG-DONE`:
486 - ``V4L2_BUF_FLAG_DONE``
487 - 0x00000004
488 - When this flag is set, the buffer is currently on the outgoing
492 cleared. Of course a buffer cannot be on both queues at the same
495 buffer is in "dequeued" state, in the application domain so to
497 * .. _`V4L2-BUF-FLAG-ERROR`:
499 - ``V4L2_BUF_FLAG_ERROR``
500 - 0x00000040
501 - When this flag is set, the buffer has been dequeued successfully,
503 streaming may continue as normal and the buffer may be reused
506 * .. _`V4L2-BUF-FLAG-IN-REQUEST`:
508 - ``V4L2_BUF_FLAG_IN_REQUEST``
509 - 0x00000080
510 - This buffer is part of a request that hasn't been queued yet.
511 * .. _`V4L2-BUF-FLAG-KEYFRAME`:
513 - ``V4L2_BUF_FLAG_KEYFRAME``
514 - 0x00000008
515 - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
516 ioctl. It may be set by video capture devices when the buffer
517 contains a compressed image which is a key frame (or field), i. e.
518 can be decompressed on its own. Also known as an I-frame.
521 * .. _`V4L2-BUF-FLAG-PFRAME`:
523 - ``V4L2_BUF_FLAG_PFRAME``
524 - 0x00000010
525 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
526 or fields which contain only differences to a previous key frame.
529 * .. _`V4L2-BUF-FLAG-BFRAME`:
531 - ``V4L2_BUF_FLAG_BFRAME``
532 - 0x00000020
533 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
534 predicted frame or field which contains only the differences
535 between the current frame and both the preceding and following key
538 * .. _`V4L2-BUF-FLAG-TIMECODE`:
540 - ``V4L2_BUF_FLAG_TIMECODE``
541 - 0x00000100
542 - The ``timecode`` field is valid. Drivers set or clear this flag
546 * .. _`V4L2-BUF-FLAG-PREPARED`:
548 - ``V4L2_BUF_FLAG_PREPARED``
549 - 0x00000400
550 - The buffer has been prepared for I/O and can be queued by the
556 * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`:
558 - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
559 - 0x00000800
560 - Caches do not have to be invalidated for this buffer. Typically
562 buffer is not going to be touched by the CPU, instead the buffer
563 will, probably, be passed on to a DMA-capable hardware unit for
567 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
568 * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
570 - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
571 - 0x00001000
572 - Caches do not have to be cleaned for this buffer. Typically
574 this buffer has not been created by the CPU but by some
575 DMA-capable unit, in which case caches have not been used. This flag
578 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
579 * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`:
581 - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF``
582 - 0x00000200
583 …- Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE…
585 output buffers each decode to a slice of the decoded frame.
586 Applications can set this flag when queueing the output buffer
587 to prevent the driver from dequeueing the capture buffer after
588 the output buffer has been decoded (i.e. the capture buffer is
589 'held'). If the timestamp of this output buffer differs from that
590 of the previous output buffer, then that indicates the start of a
591 new frame and the previously held capture buffer is dequeued.
592 * .. _`V4L2-BUF-FLAG-LAST`:
594 - ``V4L2_BUF_FLAG_LAST``
595 - 0x00100000
596 - Last buffer produced by the hardware. mem2mem codec drivers set
597 this flag on the capture queue for the last buffer when the
600 hardware limitations, the last buffer may be empty. In this case
605 * .. _`V4L2-BUF-FLAG-REQUEST-FD`:
607 - ``V4L2_BUF_FLAG_REQUEST_FD``
608 - 0x00800000
609 - The ``request_fd`` field contains a valid file descriptor.
610 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`:
612 - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
613 - 0x0000e000
614 - Mask for timestamp types below. To test the timestamp type, mask
616 and operation with buffer flags and timestamp mask.
617 * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`:
619 - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
620 - 0x00000000
621 - Unknown timestamp type. This type is used by drivers before Linux
628 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`:
630 - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
631 - 0x00002000
632 - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
635 * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`:
637 - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
638 - 0x00004000
639 - The CAPTURE buffer timestamp has been taken from the corresponding
640 OUTPUT buffer. This flag applies only to mem2mem devices.
641 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`:
643 - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
644 - 0x00070000
645 - Mask for timestamp sources below. The timestamp source defines the
646 point of time the timestamp is taken in relation to the frame.
652 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`:
654 - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
655 - 0x00000000
656 - End Of Frame. The buffer timestamp has been taken when the last
657 pixel of the frame has been received or the last pixel of the
658 frame has been transmitted. In practice, software generated
662 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`:
664 - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
665 - 0x00010000
666 - Start Of Exposure. The buffer timestamp has been taken when the
667 exposure of the frame has begun. This is only valid for the
668 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
679 .. flat-table::
680 :header-rows: 0
681 :stub-columns: 0
684 * - ``V4L2_MEMORY_MMAP``
685 - 1
686 - The buffer is used for :ref:`memory mapping <mmap>` I/O.
687 * - ``V4L2_MEMORY_USERPTR``
688 - 2
689 - The buffer is used for :ref:`user pointer <userp>` I/O.
690 * - ``V4L2_MEMORY_OVERLAY``
691 - 3
692 - [to do]
693 * - ``V4L2_MEMORY_DMABUF``
694 - 4
695 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
697 .. _memory-flags:
700 ------------------------
710 .. flat-table::
711 :header-rows: 0
712 :stub-columns: 0
715 * .. _`V4L2-MEMORY-FLAG-NON-COHERENT`:
717 - ``V4L2_MEMORY_FLAG_NON_COHERENT``
718 - 0x00000001
719 - A buffer is allocated either in coherent (it will be automatically
720 coherent between the CPU and the bus) or non-coherent memory. The
722 sync/flush operations can be avoided if the buffer is accessed by the
724 buffer. However, this requires extra care from the driver -- it must
727 allocate the buffer in non-coherent memory. The flag takes effect
728 only if the buffer is used for :ref:`memory mapping <mmap>` I/O and the
730 <V4L2-BUF-CAP-SUPPORTS-MMAP-CACHE-HINTS>` capability.
747 --------------------
751 .. flat-table::
752 :header-rows: 0
753 :stub-columns: 0
756 * - __u32
757 - ``type``
758 - Frame rate the timecodes are based on, see :ref:`timecode-type`.
759 * - __u32
760 - ``flags``
761 - Timecode flags, see :ref:`timecode-flags`.
762 * - __u8
763 - ``frames``
764 - Frame count, 0 ... 23/24/29/49/59, depending on the type of
766 * - __u8
767 - ``seconds``
768 - Seconds count, 0 ... 59. This is a binary, not BCD number.
769 * - __u8
770 - ``minutes``
771 - Minutes count, 0 ... 59. This is a binary, not BCD number.
772 * - __u8
773 - ``hours``
774 - Hours count, 0 ... 29. This is a binary, not BCD number.
775 * - __u8
776 - ``userbits``\ [4]
777 - The "user group" bits from the timecode.
780 .. _timecode-type:
783 --------------
785 .. flat-table::
786 :header-rows: 0
787 :stub-columns: 0
790 * - ``V4L2_TC_TYPE_24FPS``
791 - 1
792 - 24 frames per second, i. e. film.
793 * - ``V4L2_TC_TYPE_25FPS``
794 - 2
795 - 25 frames per second, i. e. PAL or SECAM video.
796 * - ``V4L2_TC_TYPE_30FPS``
797 - 3
798 - 30 frames per second, i. e. NTSC video.
799 * - ``V4L2_TC_TYPE_50FPS``
800 - 4
801 -
802 * - ``V4L2_TC_TYPE_60FPS``
803 - 5
804 -
807 .. _timecode-flags:
810 --------------
814 .. flat-table::
815 :header-rows: 0
816 :stub-columns: 0
819 * - ``V4L2_TC_FLAG_DROPFRAME``
820 - 0x0001
821 - Indicates "drop frame" semantics for counting frames in 29.97 fps
822 material. When set, frame numbers 0 and 1 at the start of each
825 * - ``V4L2_TC_FLAG_COLORFRAME``
826 - 0x0002
827 - The "color frame" flag.
828 * - ``V4L2_TC_USERBITS_field``
829 - 0x000C
830 - Field mask for the "binary group flags".
831 * - ``V4L2_TC_USERBITS_USERDEFINED``
832 - 0x0000
833 - Unspecified format.
834 * - ``V4L2_TC_USERBITS_8BITCHARS``
835 - 0x0008
836 - 8-bit ISO characters.