1.. -*- coding: utf-8; mode: rst -*- 2 3.. _buffer: 4 5******* 6Buffers 7******* 8 9A buffer contains data exchanged by application and driver using one of 10the Streaming I/O methods. In the multi-planar API, the data is held in 11planes, while the buffer structure acts as a container for the planes. 12Only pointers to buffers (planes) are exchanged, the data itself is not 13copied. These pointers, together with meta-information like timestamps 14or field parity, are stored in a struct :c:type:`v4l2_buffer`, 15argument to the :ref:`VIDIOC_QUERYBUF`, 16:ref:`VIDIOC_QBUF` and 17:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API, 18some plane-specific members of struct :c:type:`v4l2_buffer`, 19such as pointers and sizes for each plane, are stored in struct 20struct :c:type:`v4l2_plane` instead. In that case, struct 21struct :c:type:`v4l2_buffer` contains an array of plane structures. 22 23Dequeued video buffers come with timestamps. The driver decides at which 24part of the frame and with which clock the timestamp is taken. Please 25see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and 26``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags 27are always valid and constant across all buffers during the whole video 28stream. Changes in these flags may take place as a side effect of 29:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or 30:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The 31``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on 32mem-to-mem devices is an exception to the rule: the timestamp source 33flags are copied from the OUTPUT video buffer to the CAPTURE video 34buffer. 35 36 37.. c:type:: v4l2_buffer 38 39struct v4l2_buffer 40================== 41 42.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.3cm}|p{10.5cm}| 43 44.. cssclass:: longtable 45 46.. flat-table:: struct v4l2_buffer 47 :header-rows: 0 48 :stub-columns: 0 49 :widths: 1 2 1 10 50 51 * - __u32 52 - ``index`` 53 - 54 - Number of the buffer, set by the application except when calling 55 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the 56 driver. This field can range from zero to the number of buffers 57 allocated with the :ref:`VIDIOC_REQBUFS` ioctl 58 (struct :c:type:`v4l2_requestbuffers` 59 ``count``), plus any buffers allocated with 60 :ref:`VIDIOC_CREATE_BUFS` minus one. 61 * - __u32 62 - ``type`` 63 - 64 - Type of the buffer, same as struct 65 :c:type:`v4l2_format` ``type`` or struct 66 :c:type:`v4l2_requestbuffers` ``type``, set 67 by the application. See :c:type:`v4l2_buf_type` 68 * - __u32 69 - ``bytesused`` 70 - 71 - The number of bytes occupied by the data in the buffer. It depends 72 on the negotiated data format and may change with each buffer for 73 compressed variable size data like JPEG images. Drivers must set 74 this field when ``type`` refers to a capture stream, applications 75 when it refers to an output stream. If the application sets this 76 to 0 for an output stream, then ``bytesused`` will be set to the 77 size of the buffer (see the ``length`` field of this struct) by 78 the driver. For multiplanar formats this field is ignored and the 79 ``planes`` pointer is used instead. 80 * - __u32 81 - ``flags`` 82 - 83 - Flags set by the application or driver, see :ref:`buffer-flags`. 84 * - __u32 85 - ``field`` 86 - 87 - Indicates the field order of the image in the buffer, see 88 :c:type:`v4l2_field`. This field is not used when the buffer 89 contains VBI data. Drivers must set it when ``type`` refers to a 90 capture stream, applications when it refers to an output stream. 91 * - struct timeval 92 - ``timestamp`` 93 - 94 - For capture streams this is time when the first data byte was 95 captured, as returned by the :c:func:`clock_gettime()` function 96 for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in 97 :ref:`buffer-flags`. For output streams the driver stores the 98 time at which the last data byte was actually sent out in the 99 ``timestamp`` field. This permits applications to monitor the 100 drift between the video and system clock. For output streams that 101 use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill 102 in the timestamp which will be copied by the driver to the capture 103 stream. 104 * - struct :c:type:`v4l2_timecode` 105 - ``timecode`` 106 - 107 - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the 108 ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this 109 structure contains a frame timecode. In 110 :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and 111 bottom field contain the same timecode. Timecodes are intended to 112 help video editing and are typically recorded on video tapes, but 113 also embedded in compressed formats like MPEG. This field is 114 independent of the ``timestamp`` and ``sequence`` fields. 115 * - __u32 116 - ``sequence`` 117 - 118 - Set by the driver, counting the frames (not fields!) in sequence. 119 This field is set for both input and output devices. 120 * - :cspan:`3` 121 122 In :c:type:`V4L2_FIELD_ALTERNATE <v4l2_field>` mode the top and 123 bottom field have the same sequence number. The count starts at 124 zero and includes dropped or repeated frames. A dropped frame was 125 received by an input device but could not be stored due to lack of 126 free buffer space. A repeated frame was displayed again by an 127 output device because the application did not pass new data in 128 time. 129 130 .. note:: 131 132 This may count the frames received e.g. over USB, without 133 taking into account the frames dropped by the remote hardware due 134 to limited compression throughput or bus bandwidth. These devices 135 identify by not enumerating any video standards, see 136 :ref:`standard`. 137 138 * - __u32 139 - ``memory`` 140 - 141 - This field must be set by applications and/or drivers in 142 accordance with the selected I/O method. See :c:type:`v4l2_memory` 143 * - union 144 - ``m`` 145 * - 146 - __u32 147 - ``offset`` 148 - For the single-planar API and when ``memory`` is 149 ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the 150 start of the device memory. The value is returned by the driver 151 and apart of serving as parameter to the 152 :ref:`mmap() <func-mmap>` function not useful for applications. 153 See :ref:`mmap` for details 154 * - 155 - unsigned long 156 - ``userptr`` 157 - For the single-planar API and when ``memory`` is 158 ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to 159 unsigned long type) in virtual memory, set by the application. See 160 :ref:`userp` for details. 161 * - 162 - struct v4l2_plane 163 - ``*planes`` 164 - When using the multi-planar API, contains a userspace pointer to 165 an array of struct :c:type:`v4l2_plane`. The size of 166 the array should be put in the ``length`` field of this 167 struct :c:type:`v4l2_buffer` structure. 168 * - 169 - int 170 - ``fd`` 171 - For the single-plane API and when ``memory`` is 172 ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with 173 a DMABUF buffer. 174 * - __u32 175 - ``length`` 176 - 177 - Size of the buffer (not the payload) in bytes for the 178 single-planar API. This is set by the driver based on the calls to 179 :ref:`VIDIOC_REQBUFS` and/or 180 :ref:`VIDIOC_CREATE_BUFS`. For the 181 multi-planar API the application sets this to the number of 182 elements in the ``planes`` array. The driver will fill in the 183 actual number of valid elements in that array. 184 * - __u32 185 - ``reserved2`` 186 - 187 - A place holder for future extensions. Drivers and applications 188 must set this to 0. 189 * - __u32 190 - ``reserved`` 191 - 192 - A place holder for future extensions. Drivers and applications 193 must set this to 0. 194 195 196 197.. c:type:: v4l2_plane 198 199struct v4l2_plane 200================= 201 202.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| 203 204.. cssclass:: longtable 205 206.. flat-table:: 207 :header-rows: 0 208 :stub-columns: 0 209 :widths: 1 1 1 2 210 211 * - __u32 212 - ``bytesused`` 213 - 214 - The number of bytes occupied by data in the plane (its payload). 215 Drivers must set this field when ``type`` refers to a capture 216 stream, applications when it refers to an output stream. If the 217 application sets this to 0 for an output stream, then 218 ``bytesused`` will be set to the size of the plane (see the 219 ``length`` field of this struct) by the driver. 220 221 .. note:: 222 223 Note that the actual image data starts at ``data_offset`` 224 which may not be 0. 225 * - __u32 226 - ``length`` 227 - 228 - Size in bytes of the plane (not its payload). This is set by the 229 driver based on the calls to 230 :ref:`VIDIOC_REQBUFS` and/or 231 :ref:`VIDIOC_CREATE_BUFS`. 232 * - union 233 - ``m`` 234 - 235 - 236 * - 237 - __u32 238 - ``mem_offset`` 239 - When the memory type in the containing struct 240 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this 241 is the value that should be passed to :ref:`mmap() <func-mmap>`, 242 similar to the ``offset`` field in struct 243 :c:type:`v4l2_buffer`. 244 * - 245 - unsigned long 246 - ``userptr`` 247 - When the memory type in the containing struct 248 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``, 249 this is a userspace pointer to the memory allocated for this plane 250 by an application. 251 * - 252 - int 253 - ``fd`` 254 - When the memory type in the containing struct 255 :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``, 256 this is a file descriptor associated with a DMABUF buffer, similar 257 to the ``fd`` field in struct :c:type:`v4l2_buffer`. 258 * - __u32 259 - ``data_offset`` 260 - 261 - Offset in bytes to video data in the plane. Drivers must set this 262 field when ``type`` refers to a capture stream, applications when 263 it refers to an output stream. 264 265 .. note:: 266 267 That data_offset is included in ``bytesused``. So the 268 size of the image in the plane is ``bytesused``-``data_offset`` 269 at offset ``data_offset`` from the start of the plane. 270 * - __u32 271 - ``reserved[11]`` 272 - 273 - Reserved for future use. Should be zeroed by drivers and 274 applications. 275 276 277 278.. c:type:: v4l2_buf_type 279 280enum v4l2_buf_type 281================== 282 283.. cssclass:: longtable 284 285.. tabularcolumns:: |p{7.2cm}|p{0.6cm}|p{9.7cm}| 286 287.. flat-table:: 288 :header-rows: 0 289 :stub-columns: 0 290 :widths: 4 1 9 291 292 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` 293 - 1 294 - Buffer of a single-planar video capture stream, see 295 :ref:`capture`. 296 * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` 297 - 9 298 - Buffer of a multi-planar video capture stream, see 299 :ref:`capture`. 300 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` 301 - 2 302 - Buffer of a single-planar video output stream, see 303 :ref:`output`. 304 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` 305 - 10 306 - Buffer of a multi-planar video output stream, see :ref:`output`. 307 * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` 308 - 3 309 - Buffer for video overlay, see :ref:`overlay`. 310 * - ``V4L2_BUF_TYPE_VBI_CAPTURE`` 311 - 4 312 - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. 313 * - ``V4L2_BUF_TYPE_VBI_OUTPUT`` 314 - 5 315 - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. 316 * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` 317 - 6 318 - Buffer of a sliced VBI capture stream, see :ref:`sliced`. 319 * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` 320 - 7 321 - Buffer of a sliced VBI output stream, see :ref:`sliced`. 322 * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` 323 - 8 324 - Buffer for video output overlay (OSD), see :ref:`osd`. 325 * - ``V4L2_BUF_TYPE_SDR_CAPTURE`` 326 - 11 327 - Buffer for Software Defined Radio (SDR) capture stream, see 328 :ref:`sdr`. 329 * - ``V4L2_BUF_TYPE_SDR_OUTPUT`` 330 - 12 331 - Buffer for Software Defined Radio (SDR) output stream, see 332 :ref:`sdr`. 333 334 335 336.. _buffer-flags: 337 338Buffer Flags 339============ 340 341.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.3cm}| 342 343.. cssclass:: longtable 344 345.. flat-table:: 346 :header-rows: 0 347 :stub-columns: 0 348 :widths: 3 1 4 349 350 * .. _`V4L2-BUF-FLAG-MAPPED`: 351 352 - ``V4L2_BUF_FLAG_MAPPED`` 353 - 0x00000001 354 - The buffer resides in device memory and has been mapped into the 355 application's address space, see :ref:`mmap` for details. 356 Drivers set or clear this flag when the 357 :ref:`VIDIOC_QUERYBUF`, 358 :ref:`VIDIOC_QBUF` or 359 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the 360 driver. 361 * .. _`V4L2-BUF-FLAG-QUEUED`: 362 363 - ``V4L2_BUF_FLAG_QUEUED`` 364 - 0x00000002 365 - Internally drivers maintain two buffer queues, an incoming and 366 outgoing queue. When this flag is set, the buffer is currently on 367 the incoming queue. It automatically moves to the outgoing queue 368 after the buffer has been filled (capture devices) or displayed 369 (output devices). Drivers set or clear this flag when the 370 ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling 371 the ``VIDIOC_QBUF``\ ioctl it is always set and after 372 ``VIDIOC_DQBUF`` always cleared. 373 * .. _`V4L2-BUF-FLAG-DONE`: 374 375 - ``V4L2_BUF_FLAG_DONE`` 376 - 0x00000004 377 - When this flag is set, the buffer is currently on the outgoing 378 queue, ready to be dequeued from the driver. Drivers set or clear 379 this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After 380 calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always 381 cleared. Of course a buffer cannot be on both queues at the same 382 time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag 383 are mutually exclusive. They can be both cleared however, then the 384 buffer is in "dequeued" state, in the application domain so to 385 say. 386 * .. _`V4L2-BUF-FLAG-ERROR`: 387 388 - ``V4L2_BUF_FLAG_ERROR`` 389 - 0x00000040 390 - When this flag is set, the buffer has been dequeued successfully, 391 although the data might have been corrupted. This is recoverable, 392 streaming may continue as normal and the buffer may be reused 393 normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is 394 called. 395 * .. _`V4L2-BUF-FLAG-KEYFRAME`: 396 397 - ``V4L2_BUF_FLAG_KEYFRAME`` 398 - 0x00000008 399 - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` 400 ioctl. It may be set by video capture devices when the buffer 401 contains a compressed image which is a key frame (or field), i. e. 402 can be decompressed on its own. Also known as an I-frame. 403 Applications can set this bit when ``type`` refers to an output 404 stream. 405 * .. _`V4L2-BUF-FLAG-PFRAME`: 406 407 - ``V4L2_BUF_FLAG_PFRAME`` 408 - 0x00000010 409 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames 410 or fields which contain only differences to a previous key frame. 411 Applications can set this bit when ``type`` refers to an output 412 stream. 413 * .. _`V4L2-BUF-FLAG-BFRAME`: 414 415 - ``V4L2_BUF_FLAG_BFRAME`` 416 - 0x00000020 417 - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional 418 predicted frame or field which contains only the differences 419 between the current frame and both the preceding and following key 420 frames to specify its content. Applications can set this bit when 421 ``type`` refers to an output stream. 422 * .. _`V4L2-BUF-FLAG-TIMECODE`: 423 424 - ``V4L2_BUF_FLAG_TIMECODE`` 425 - 0x00000100 426 - The ``timecode`` field is valid. Drivers set or clear this flag 427 when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set 428 this bit and the corresponding ``timecode`` structure when 429 ``type`` refers to an output stream. 430 * .. _`V4L2-BUF-FLAG-PREPARED`: 431 432 - ``V4L2_BUF_FLAG_PREPARED`` 433 - 0x00000400 434 - The buffer has been prepared for I/O and can be queued by the 435 application. Drivers set or clear this flag when the 436 :ref:`VIDIOC_QUERYBUF`, 437 :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`, 438 :ref:`VIDIOC_QBUF` or 439 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. 440 * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: 441 442 - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` 443 - 0x00000800 444 - Caches do not have to be invalidated for this buffer. Typically 445 applications shall use this flag if the data captured in the 446 buffer is not going to be touched by the CPU, instead the buffer 447 will, probably, be passed on to a DMA-capable hardware unit for 448 further processing or output. 449 * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: 450 451 - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` 452 - 0x00001000 453 - Caches do not have to be cleaned for this buffer. Typically 454 applications shall use this flag for output buffers if the data in 455 this buffer has not been created by the CPU but by some 456 DMA-capable unit, in which case caches have not been used. 457 * .. _`V4L2-BUF-FLAG-LAST`: 458 459 - ``V4L2_BUF_FLAG_LAST`` 460 - 0x00100000 461 - Last buffer produced by the hardware. mem2mem codec drivers set 462 this flag on the capture queue for the last buffer when the 463 :ref:`VIDIOC_QUERYBUF` or 464 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to 465 hardware limitations, the last buffer may be empty. In this case 466 the driver will set the ``bytesused`` field to 0, regardless of 467 the format. Any Any subsequent call to the 468 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, 469 but return an ``EPIPE`` error code. 470 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: 471 472 - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` 473 - 0x0000e000 474 - Mask for timestamp types below. To test the timestamp type, mask 475 out bits not belonging to timestamp type by performing a logical 476 and operation with buffer flags and timestamp mask. 477 * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`: 478 479 - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` 480 - 0x00000000 481 - Unknown timestamp type. This type is used by drivers before Linux 482 3.9 and may be either monotonic (see below) or realtime (wall 483 clock). Monotonic clock has been favoured in embedded systems 484 whereas most of the drivers use the realtime clock. Either kinds 485 of timestamps are available in user space via 486 :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC`` 487 and ``CLOCK_REALTIME``, respectively. 488 * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`: 489 490 - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` 491 - 0x00002000 492 - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` 493 clock. To access the same clock outside V4L2, use 494 :c:func:`clock_gettime`. 495 * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`: 496 497 - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` 498 - 0x00004000 499 - The CAPTURE buffer timestamp has been taken from the corresponding 500 OUTPUT buffer. This flag applies only to mem2mem devices. 501 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`: 502 503 - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` 504 - 0x00070000 505 - Mask for timestamp sources below. The timestamp source defines the 506 point of time the timestamp is taken in relation to the frame. 507 Logical 'and' operation between the ``flags`` field and 508 ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the 509 timestamp source. Applications must set the timestamp source when 510 ``type`` refers to an output stream and 511 ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. 512 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`: 513 514 - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` 515 - 0x00000000 516 - End Of Frame. The buffer timestamp has been taken when the last 517 pixel of the frame has been received or the last pixel of the 518 frame has been transmitted. In practice, software generated 519 timestamps will typically be read from the clock a small amount of 520 time after the last pixel has been received or transmitten, 521 depending on the system and other activity in it. 522 * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`: 523 524 - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` 525 - 0x00010000 526 - Start Of Exposure. The buffer timestamp has been taken when the 527 exposure of the frame has begun. This is only valid for the 528 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. 529 530 531 532.. c:type:: v4l2_memory 533 534enum v4l2_memory 535================ 536 537.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 538 539.. flat-table:: 540 :header-rows: 0 541 :stub-columns: 0 542 :widths: 3 1 4 543 544 * - ``V4L2_MEMORY_MMAP`` 545 - 1 546 - The buffer is used for :ref:`memory mapping <mmap>` I/O. 547 * - ``V4L2_MEMORY_USERPTR`` 548 - 2 549 - The buffer is used for :ref:`user pointer <userp>` I/O. 550 * - ``V4L2_MEMORY_OVERLAY`` 551 - 3 552 - [to do] 553 * - ``V4L2_MEMORY_DMABUF`` 554 - 4 555 - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O. 556 557 558 559Timecodes 560========= 561 562The struct :c:type:`v4l2_timecode` structure is designed to hold a 563:ref:`smpte12m` or similar timecode. (struct 564struct :c:type:`timeval` timestamps are stored in struct 565:c:type:`v4l2_buffer` field ``timestamp``.) 566 567 568.. c:type:: v4l2_timecode 569 570struct v4l2_timecode 571-------------------- 572 573.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 574 575.. flat-table:: 576 :header-rows: 0 577 :stub-columns: 0 578 :widths: 1 1 2 579 580 * - __u32 581 - ``type`` 582 - Frame rate the timecodes are based on, see :ref:`timecode-type`. 583 * - __u32 584 - ``flags`` 585 - Timecode flags, see :ref:`timecode-flags`. 586 * - __u8 587 - ``frames`` 588 - Frame count, 0 ... 23/24/29/49/59, depending on the type of 589 timecode. 590 * - __u8 591 - ``seconds`` 592 - Seconds count, 0 ... 59. This is a binary, not BCD number. 593 * - __u8 594 - ``minutes`` 595 - Minutes count, 0 ... 59. This is a binary, not BCD number. 596 * - __u8 597 - ``hours`` 598 - Hours count, 0 ... 29. This is a binary, not BCD number. 599 * - __u8 600 - ``userbits``\ [4] 601 - The "user group" bits from the timecode. 602 603 604 605.. _timecode-type: 606 607Timecode Types 608-------------- 609 610.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 611 612.. flat-table:: 613 :header-rows: 0 614 :stub-columns: 0 615 :widths: 3 1 4 616 617 * - ``V4L2_TC_TYPE_24FPS`` 618 - 1 619 - 24 frames per second, i. e. film. 620 * - ``V4L2_TC_TYPE_25FPS`` 621 - 2 622 - 25 frames per second, i. e. PAL or SECAM video. 623 * - ``V4L2_TC_TYPE_30FPS`` 624 - 3 625 - 30 frames per second, i. e. NTSC video. 626 * - ``V4L2_TC_TYPE_50FPS`` 627 - 4 628 - 629 * - ``V4L2_TC_TYPE_60FPS`` 630 - 5 631 - 632 633 634 635.. _timecode-flags: 636 637Timecode Flags 638-------------- 639 640.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| 641 642.. flat-table:: 643 :header-rows: 0 644 :stub-columns: 0 645 :widths: 3 1 4 646 647 * - ``V4L2_TC_FLAG_DROPFRAME`` 648 - 0x0001 649 - Indicates "drop frame" semantics for counting frames in 29.97 fps 650 material. When set, frame numbers 0 and 1 at the start of each 651 minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the 652 count. 653 * - ``V4L2_TC_FLAG_COLORFRAME`` 654 - 0x0002 655 - The "color frame" flag. 656 * - ``V4L2_TC_USERBITS_field`` 657 - 0x000C 658 - Field mask for the "binary group flags". 659 * - ``V4L2_TC_USERBITS_USERDEFINED`` 660 - 0x0000 661 - Unspecified format. 662 * - ``V4L2_TC_USERBITS_8BITCHARS`` 663 - 0x0008 664 - 8-bit ISO characters. 665