Lines Matching +full:frame +full:- +full:buffer
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
16 A buffer contains data exchanged by application and driver using one of
17 the Streaming I/O methods. In the multi-planar API, the data is held in
18 planes, while the buffer structure acts as a container for the planes.
20 copied. These pointers, together with meta-information like timestamps
24 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
25 some plane-specific members of struct :c:type:`v4l2_buffer`,
31 part of the frame and with which clock the timestamp is taken. Please
33 ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
39 mem-to-mem devices is an exception to the rule: the timestamp source
40 flags are copied from the OUTPUT video buffer to the CAPTURE video
41 buffer.
47 V4L2 exposes parameters that influence the buffer size, or the way data is
48 laid out in the buffer. Those parameters are exposed through both formats and
50 that modifies the direction in which pixels are stored in the buffer, as well
51 as the buffer size when the selected format includes padding at the end of
54 The set of information needed to interpret the content of a buffer (e.g. the
56 collectively referred to in the rest of this section as the buffer layout.
58 Controls that can modify the buffer layout shall set the
61 Modifying formats or controls that influence the buffer size or layout require
76 selection rectangles. When those ioctls result in a buffer size or layout
80 Controls that only influence the buffer layout can be modified at any time
81 when the stream is stopped. As they don't influence the buffer size, no
82 special handling is needed to synchronize those controls with buffer
86 Formats and controls that influence the buffer size interact with buffer
106 value into account to compute the buffer size to allocate. Applications can
118 influences the buffer size while buffers are allocated shall cause the format
120 buffer too small for the current format or controls shall cause the
123 Buffer reallocation is an expensive operation. To avoid that cost, drivers can
124 (and are encouraged to) allow format or controls that influence the buffer
139 allowed to return a ``EBUSY`` error from these ioctls if any buffer is
143 :c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the
147 Userspace applications can query the buffer size required for a given format
150 buffer size.
172 .. flat-table:: struct v4l2_buffer
173 :header-rows: 0
174 :stub-columns: 0
177 * - __u32
178 - ``index``
179 -
180 - Number of the buffer, set by the application except when calling
187 * - __u32
188 - ``type``
189 -
190 - Type of the buffer, same as struct
194 * - __u32
195 - ``bytesused``
196 -
197 - The number of bytes occupied by the data in the buffer. It depends
198 on the negotiated data format and may change with each buffer for
203 size of the buffer (see the ``length`` field of this struct) by
206 * - __u32
207 - ``flags``
208 -
209 - Flags set by the application or driver, see :ref:`buffer-flags`.
210 * - __u32
211 - ``field``
212 -
213 - Indicates the field order of the image in the buffer, see
214 :c:type:`v4l2_field`. This field is not used when the buffer
217 * - struct timeval
218 - ``timestamp``
219 -
220 - For capture streams this is time when the first data byte was
223 :ref:`buffer-flags`. For output streams the driver stores the
230 * - struct :c:type:`v4l2_timecode`
231 - ``timecode``
232 -
233 - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
234 structure contains a frame timecode. In
240 * - __u32
241 - ``sequence``
242 -
243 - Set by the driver, counting the frames (not fields!) in sequence.
245 * - :cspan:`3`
249 zero and includes dropped or repeated frames. A dropped frame was
251 free buffer space. A repeated frame was displayed again by an
263 * - __u32
264 - ``memory``
265 -
266 - This field must be set by applications and/or drivers in
268 * - union
269 - ``m``
270 * -
271 - __u32
272 - ``offset``
273 - For the single-planar API and when ``memory`` is
274 ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
277 :ref:`mmap() <func-mmap>` function not useful for applications.
279 * -
280 - unsigned long
281 - ``userptr``
282 - For the single-planar API and when ``memory`` is
283 ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
286 * -
287 - struct v4l2_plane
288 - ``*planes``
289 - When using the multi-planar API, contains a userspace pointer to
293 * -
294 - int
295 - ``fd``
296 - For the single-plane API and when ``memory`` is
298 a DMABUF buffer.
299 * - __u32
300 - ``length``
301 -
302 - Size of the buffer (not the payload) in bytes for the
303 single-planar API. This is set by the driver based on the calls to
306 multi-planar API the application sets this to the number of
309 * - __u32
310 - ``reserved2``
311 -
312 - A place holder for future extensions. Drivers and applications
314 * - __u32
315 - ``request_fd``
316 -
317 - The file descriptor of the request to queue the buffer to. If the flag
318 ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be
344 .. flat-table::
345 :header-rows: 0
346 :stub-columns: 0
349 * - __u32
350 - ``bytesused``
351 -
352 - The number of bytes occupied by data in the plane (its payload).
363 * - __u32
364 - ``length``
365 -
366 - Size in bytes of the plane (not its payload). This is set by the
370 * - union
371 - ``m``
372 -
373 -
374 * -
375 - __u32
376 - ``mem_offset``
377 - When the memory type in the containing struct
379 is the value that should be passed to :ref:`mmap() <func-mmap>`,
382 * -
383 - unsigned long
384 - ``userptr``
385 - When the memory type in the containing struct
389 * -
390 - int
391 - ``fd``
392 - When the memory type in the containing struct
394 this is a file descriptor associated with a DMABUF buffer, similar
396 * - __u32
397 - ``data_offset``
398 -
399 - Offset in bytes to video data in the plane. Drivers must set this
406 size of the image in the plane is ``bytesused``-``data_offset``
408 * - __u32
409 - ``reserved[11]``
410 -
411 - Reserved for future use. Should be zeroed by drivers and
425 .. flat-table::
426 :header-rows: 0
427 :stub-columns: 0
430 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
431 - 1
432 - Buffer of a single-planar video capture stream, see
434 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
435 - 9
436 - Buffer of a multi-planar video capture stream, see
438 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
439 - 2
440 - Buffer of a single-planar video output stream, see
442 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
443 - 10
444 - Buffer of a multi-planar video output stream, see :ref:`output`.
445 * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
446 - 3
447 - Buffer for video overlay, see :ref:`overlay`.
448 * - ``V4L2_BUF_TYPE_VBI_CAPTURE``
449 - 4
450 - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
451 * - ``V4L2_BUF_TYPE_VBI_OUTPUT``
452 - 5
453 - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
454 * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
455 - 6
456 - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
457 * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
458 - 7
459 - Buffer of a sliced VBI output stream, see :ref:`sliced`.
460 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
461 - 8
462 - Buffer for video output overlay (OSD), see :ref:`osd`.
463 * - ``V4L2_BUF_TYPE_SDR_CAPTURE``
464 - 11
465 - Buffer for Software Defined Radio (SDR) capture stream, see
467 * - ``V4L2_BUF_TYPE_SDR_OUTPUT``
468 - 12
469 - Buffer for Software Defined Radio (SDR) output stream, see
471 * - ``V4L2_BUF_TYPE_META_CAPTURE``
472 - 13
473 - Buffer for metadata capture, see :ref:`metadata`.
474 * - ``V4L2_BUF_TYPE_META_OUTPUT``
475 - 14
476 - Buffer for metadata output, see :ref:`metadata`.
480 .. _buffer-flags:
482 Buffer Flags
493 .. flat-table::
494 :header-rows: 0
495 :stub-columns: 0
498 * .. _`V4L2-BUF-FLAG-MAPPED`:
500 - ``V4L2_BUF_FLAG_MAPPED``
501 - 0x00000001
502 - The buffer resides in device memory and has been mapped into the
509 * .. _`V4L2-BUF-FLAG-QUEUED`:
511 - ``V4L2_BUF_FLAG_QUEUED``
512 - 0x00000002
513 - Internally drivers maintain two buffer queues, an incoming and
514 outgoing queue. When this flag is set, the buffer is currently on
516 after the buffer has been filled (capture devices) or displayed
521 * .. _`V4L2-BUF-FLAG-DONE`:
523 - ``V4L2_BUF_FLAG_DONE``
524 - 0x00000004
525 - When this flag is set, the buffer is currently on the outgoing
529 cleared. Of course a buffer cannot be on both queues at the same
532 buffer is in "dequeued" state, in the application domain so to
534 * .. _`V4L2-BUF-FLAG-ERROR`:
536 - ``V4L2_BUF_FLAG_ERROR``
537 - 0x00000040
538 - When this flag is set, the buffer has been dequeued successfully,
540 streaming may continue as normal and the buffer may be reused
543 * .. _`V4L2-BUF-FLAG-IN-REQUEST`:
545 - ``V4L2_BUF_FLAG_IN_REQUEST``
546 - 0x00000080
547 - This buffer is part of a request that hasn't been queued yet.
548 * .. _`V4L2-BUF-FLAG-KEYFRAME`:
550 - ``V4L2_BUF_FLAG_KEYFRAME``
551 - 0x00000008
552 - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
553 ioctl. It may be set by video capture devices when the buffer
554 contains a compressed image which is a key frame (or field), i. e.
555 can be decompressed on its own. Also known as an I-frame.
558 * .. _`V4L2-BUF-FLAG-PFRAME`:
560 - ``V4L2_BUF_FLAG_PFRAME``
561 - 0x00000010
562 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
563 or fields which contain only differences to a previous key frame.
566 * .. _`V4L2-BUF-FLAG-BFRAME`:
568 - ``V4L2_BUF_FLAG_BFRAME``
569 - 0x00000020
570 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
571 predicted frame or field which contains only the differences
572 between the current frame and both the preceding and following key
575 * .. _`V4L2-BUF-FLAG-TIMECODE`:
577 - ``V4L2_BUF_FLAG_TIMECODE``
578 - 0x00000100
579 - The ``timecode`` field is valid. Drivers set or clear this flag
583 * .. _`V4L2-BUF-FLAG-PREPARED`:
585 - ``V4L2_BUF_FLAG_PREPARED``
586 - 0x00000400
587 - The buffer has been prepared for I/O and can be queued by the
593 * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`:
595 - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
596 - 0x00000800
597 - Caches do not have to be invalidated for this buffer. Typically
599 buffer is not going to be touched by the CPU, instead the buffer
600 will, probably, be passed on to a DMA-capable hardware unit for
602 * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`:
604 - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
605 - 0x00001000
606 - Caches do not have to be cleaned for this buffer. Typically
608 this buffer has not been created by the CPU but by some
609 DMA-capable unit, in which case caches have not been used.
610 * .. _`V4L2-BUF-FLAG-LAST`:
612 - ``V4L2_BUF_FLAG_LAST``
613 - 0x00100000
614 - Last buffer produced by the hardware. mem2mem codec drivers set
615 this flag on the capture queue for the last buffer when the
618 hardware limitations, the last buffer may be empty. In this case
623 * .. _`V4L2-BUF-FLAG-REQUEST-FD`:
625 - ``V4L2_BUF_FLAG_REQUEST_FD``
626 - 0x00800000
627 - The ``request_fd`` field contains a valid file descriptor.
628 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`:
630 - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
631 - 0x0000e000
632 - Mask for timestamp types below. To test the timestamp type, mask
634 and operation with buffer flags and timestamp mask.
635 * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`:
637 - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
638 - 0x00000000
639 - Unknown timestamp type. This type is used by drivers before Linux
646 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`:
648 - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
649 - 0x00002000
650 - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
653 * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`:
655 - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
656 - 0x00004000
657 - The CAPTURE buffer timestamp has been taken from the corresponding
658 OUTPUT buffer. This flag applies only to mem2mem devices.
659 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`:
661 - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
662 - 0x00070000
663 - Mask for timestamp sources below. The timestamp source defines the
664 point of time the timestamp is taken in relation to the frame.
670 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`:
672 - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
673 - 0x00000000
674 - End Of Frame. The buffer timestamp has been taken when the last
675 pixel of the frame has been received or the last pixel of the
676 frame has been transmitted. In practice, software generated
680 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`:
682 - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
683 - 0x00010000
684 - Start Of Exposure. The buffer timestamp has been taken when the
685 exposure of the frame has begun. This is only valid for the
686 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
700 .. flat-table::
701 :header-rows: 0
702 :stub-columns: 0
705 * - ``V4L2_MEMORY_MMAP``
706 - 1
707 - The buffer is used for :ref:`memory mapping <mmap>` I/O.
708 * - ``V4L2_MEMORY_USERPTR``
709 - 2
710 - The buffer is used for :ref:`user pointer <userp>` I/O.
711 * - ``V4L2_MEMORY_OVERLAY``
712 - 3
713 - [to do]
714 * - ``V4L2_MEMORY_DMABUF``
715 - 4
716 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
732 --------------------
736 .. flat-table::
737 :header-rows: 0
738 :stub-columns: 0
741 * - __u32
742 - ``type``
743 - Frame rate the timecodes are based on, see :ref:`timecode-type`.
744 * - __u32
745 - ``flags``
746 - Timecode flags, see :ref:`timecode-flags`.
747 * - __u8
748 - ``frames``
749 - Frame count, 0 ... 23/24/29/49/59, depending on the type of
751 * - __u8
752 - ``seconds``
753 - Seconds count, 0 ... 59. This is a binary, not BCD number.
754 * - __u8
755 - ``minutes``
756 - Minutes count, 0 ... 59. This is a binary, not BCD number.
757 * - __u8
758 - ``hours``
759 - Hours count, 0 ... 29. This is a binary, not BCD number.
760 * - __u8
761 - ``userbits``\ [4]
762 - The "user group" bits from the timecode.
766 .. _timecode-type:
769 --------------
773 .. flat-table::
774 :header-rows: 0
775 :stub-columns: 0
778 * - ``V4L2_TC_TYPE_24FPS``
779 - 1
780 - 24 frames per second, i. e. film.
781 * - ``V4L2_TC_TYPE_25FPS``
782 - 2
783 - 25 frames per second, i. e. PAL or SECAM video.
784 * - ``V4L2_TC_TYPE_30FPS``
785 - 3
786 - 30 frames per second, i. e. NTSC video.
787 * - ``V4L2_TC_TYPE_50FPS``
788 - 4
789 -
790 * - ``V4L2_TC_TYPE_60FPS``
791 - 5
792 -
796 .. _timecode-flags:
799 --------------
803 .. flat-table::
804 :header-rows: 0
805 :stub-columns: 0
808 * - ``V4L2_TC_FLAG_DROPFRAME``
809 - 0x0001
810 - Indicates "drop frame" semantics for counting frames in 29.97 fps
811 material. When set, frame numbers 0 and 1 at the start of each
814 * - ``V4L2_TC_FLAG_COLORFRAME``
815 - 0x0002
816 - The "color frame" flag.
817 * - ``V4L2_TC_USERBITS_field``
818 - 0x000C
819 - Field mask for the "binary group flags".
820 * - ``V4L2_TC_USERBITS_USERDEFINED``
821 - 0x0000
822 - Unspecified format.
823 * - ``V4L2_TC_USERBITS_8BITCHARS``
824 - 0x0008
825 - 8-bit ISO characters.