1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. _decoder:
4
5 **********************************************
6 Memory-to-Memory Stateful Video Decoder Interf
7 **********************************************
8
9 A stateful video decoder takes complete chunks
10 H.264/HEVC stream, raw VP8/9 stream) and decod
11 display order. The decoder is expected not to
12 from the client to process these buffers.
13
14 Performing software parsing, processing etc. o
15 order to support this interface is strongly di
16 operations are needed, use of the Stateless Vi
17 development) is strongly advised.
18
19 Conventions and Notations Used in This Documen
20 ==============================================
21
22 1. The general V4L2 API rules apply if not spe
23 otherwise.
24
25 2. The meaning of words "must", "may", "should
26 2119 <https://tools.ietf.org/html/rfc2119>`
27
28 3. All steps not marked "optional" are require
29
30 4. :c:func:`VIDIOC_G_EXT_CTRLS` and :c:func:`V
31 interchangeably with :c:func:`VIDIOC_G_CTRL
32 unless specified otherwise.
33
34 5. Single-planar API (see :ref:`planar-apis`)
35 used interchangeably with multi-planar API,
36 depending on decoder capabilities and follo
37
38 6. i = [a..b]: sequence of integers from a to
39 [0..2]: i = 0, 1, 2.
40
41 7. Given an ``OUTPUT`` buffer A, then A' repre
42 queue containing data that resulted from pr
43
44 .. _decoder-glossary:
45
46 Glossary
47 ========
48
49 CAPTURE
50 the destination buffer queue; for decoders,
51 decoded frames; for encoders, the queue of
52 bytestream; ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
53 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``; dat
54 into ``CAPTURE`` buffers.
55
56 client
57 the application communicating with the deco
58 this interface.
59
60 coded format
61 encoded/compressed video bytestream format
62 also: raw format.
63
64 coded height
65 height for given coded resolution.
66
67 coded resolution
68 stream resolution in pixels aligned to code
69 typically visible resolution rounded up to
70 see also: visible resolution.
71
72 coded width
73 width for given coded resolution.
74
75 coding tree unit
76 processing unit of the HEVC codec (correspo
77 H.264, VP8, VP9),
78 can use block structures of up to 64×64 pi
79 Good at sub-partitioning the picture into v
80
81 decode order
82 the order in which frames are decoded; may
83 coded format includes a feature of frame re
84 ``OUTPUT`` buffers must be queued by the cl
85 encoders ``CAPTURE`` buffers must be return
86
87 destination
88 data resulting from the decode process; see
89
90 display order
91 the order in which frames must be displayed
92 buffers must be queued by the client in dis
93 ``CAPTURE`` buffers must be returned by the
94
95 DPB
96 Decoded Picture Buffer; an H.264/HEVC term
97 raw frame available for reference in furthe
98
99 EOS
100 end of stream.
101
102 IDR
103 Instantaneous Decoder Refresh; a type of a
104 stream, which clears the list of earlier re
105
106 keyframe
107 an encoded frame that does not reference fr
108 can be decoded fully on its own.
109
110 macroblock
111 a processing unit in image and video compre
112 block transforms (e.g. H.264, VP8, VP9); co
113 popular codecs the size is 16x16 samples (p
114 slightly more flexible processing unit call
115
116 OUTPUT
117 the source buffer queue; for decoders, the
118 an encoded bytestream; for encoders, the qu
119 frames; ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or
120 ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``; the
121 from ``OUTPUT`` buffers.
122
123 PPS
124 Picture Parameter Set; a type of metadata e
125
126 raw format
127 uncompressed format containing raw pixel da
128
129 resume point
130 a point in the bytestream from which decodi
131 any previous state/data present, e.g.: a ke
132 SPS/PPS/IDR sequence (H.264/HEVC); a resume
133 of a new stream, or to resume decoding afte
134
135 source
136 data fed to the decoder or encoder; see ``O
137
138 source height
139 height in pixels for given source resolutio
140
141 source resolution
142 resolution in pixels of source frames being
143 subject to further cropping to the bounds o
144 encoders only.
145
146 source width
147 width in pixels for given source resolution
148
149 SPS
150 Sequence Parameter Set; a type of metadata
151
152 stream metadata
153 additional (non-visual) information contain
154 for example: coded resolution, visible reso
155
156 visible height
157 height for given visible resolution; displa
158
159 visible resolution
160 stream resolution of the visible picture, i
161 display purposes; must be smaller or equal
162 display resolution.
163
164 visible width
165 width for given visible resolution; display
166
167 State Machine
168 =============
169
170 .. kernel-render:: DOT
171 :alt: DOT digraph of decoder state machine
172 :caption: Decoder State Machine
173
174 digraph decoder_state_machine {
175 node [shape = doublecircle, label="Deco
176
177 node [shape = circle, label="Initializa
178 node [shape = circle, label="Capture\ns
179 node [shape = circle, label="Dynamic\nR
180 node [shape = circle, label="Stopped"]
181 node [shape = circle, label="Drain"] Dr
182 node [shape = circle, label="Seek"] See
183 node [shape = circle, label="End of Str
184
185 node [shape = point]; qi
186 qi -> Initialization [ label = "open()"
187
188 Initialization -> CaptureSetup [ label
189
190 CaptureSetup -> Stopped [ label = "CAPT
191
192 Decoding -> ResChange [ label = "Stream
193 Decoding -> Drain [ label = "V4L2_DEC_C
194 Decoding -> EoS [ label = "EoS mark\nin
195 Decoding -> Seek [ label = "VIDIOC_STRE
196 Decoding -> Stopped [ label = "VIDIOC_S
197 Decoding -> Decoding;
198
199 ResChange -> CaptureSetup [ label = "CA
200 ResChange -> Seek [ label = "VIDIOC_STR
201
202 EoS -> Drain [ label = "Implicit\ndrain
203
204 Drain -> Stopped [ label = "All CAPTURE
205 Drain -> Seek [ label = "VIDIOC_STREAMO
206
207 Seek -> Decoding [ label = "VIDIOC_STRE
208 Seek -> Initialization [ label = "VIDIO
209
210 Stopped -> Decoding [ label = "V4L2_DEC
211 Stopped -> Seek [ label = "VIDIOC_STREA
212 }
213
214 Querying Capabilities
215 =====================
216
217 1. To enumerate the set of coded formats suppo
218 client may call :c:func:`VIDIOC_ENUM_FMT` o
219
220 * The full set of supported formats will be
221 format set on ``CAPTURE``.
222 * Check the flags field of :c:type:`v4l2_fm
223 about the decoder's capabilities with res
224 In particular whether or not the decoder
225 parser and if the decoder supports dynami
226
227 2. To enumerate the set of supported raw forma
228 :c:func:`VIDIOC_ENUM_FMT` on ``CAPTURE``.
229
230 * Only the formats supported for the format
231 will be returned.
232
233 * In order to enumerate raw formats support
234 the client must first set that coded form
235 enumerate formats on ``CAPTURE``.
236
237 3. The client may use :c:func:`VIDIOC_ENUM_FRA
238 resolutions for a given format, passing des
239 :c:type:`v4l2_frmsizeenum` ``pixel_format``
240
241 * Values returned by :c:func:`VIDIOC_ENUM_F
242 format will include all possible coded re
243 decoder for given coded pixel format.
244
245 * Values returned by :c:func:`VIDIOC_ENUM_F
246 will include all possible frame buffer re
247 decoder for given raw pixel format and th
248 ``OUTPUT``.
249
250 4. Supported profiles and levels for the coded
251 ``OUTPUT``, if applicable, may be queried u
252 via :c:func:`VIDIOC_QUERYCTRL`.
253
254 Initialization
255 ==============
256
257 1. Set the coded format on ``OUTPUT`` via :c:f
258
259 * **Required fields:**
260
261 ``type``
262 a ``V4L2_BUF_TYPE_*`` enum appropriat
263
264 ``pixelformat``
265 a coded pixel format.
266
267 ``width``, ``height``
268 coded resolution of the stream; requi
269 from the stream for the given coded f
270 use this resolution as a placeholder
271 as soon as it can parse the actual co
272
273 ``sizeimage``
274 desired size of ``OUTPUT`` buffers; t
275 match hardware requirements.
276
277 other fields
278 follow standard semantics.
279
280 * **Returned fields:**
281
282 ``sizeimage``
283 adjusted size of ``OUTPUT`` buffers.
284
285 * The ``CAPTURE`` format will be updated wi
286 resolution instantly based on the width a
287 :c:func:`VIDIOC_S_FMT`.
288 However, for coded formats that include s
289 after the decoder is done parsing the inf
290 update the ``CAPTURE`` format with new va
291 event, regardless of whether they match t
292 not.
293
294 .. important::
295
296 Changing the ``OUTPUT`` format may chang
297 format. How the new ``CAPTURE`` format i
298 and the client must ensure it matches it
299
300 2. Allocate source (bytestream) buffers via :
301 ``OUTPUT``.
302
303 * **Required fields:**
304
305 ``count``
306 requested number of buffers to alloc
307
308 ``type``
309 a ``V4L2_BUF_TYPE_*`` enum appropria
310
311 ``memory``
312 follows standard semantics.
313
314 * **Returned fields:**
315
316 ``count``
317 the actual number of buffers allocat
318
319 .. warning::
320
321 The actual number of allocated buffers
322 given. The client must check the update
323 call returns.
324
325 Alternatively, :c:func:`VIDIOC_CREATE_BUFS
326 used to have more control over buffer allo
327
328 * **Required fields:**
329
330 ``count``
331 requested number of buffers to alloc
332
333 ``type``
334 a ``V4L2_BUF_TYPE_*`` enum appropria
335
336 ``memory``
337 follows standard semantics.
338
339 ``format``
340 follows standard semantics.
341
342 * **Returned fields:**
343
344 ``count``
345 adjusted to the number of allocated
346
347 .. warning::
348
349 The actual number of allocated buffers
350 given. The client must check the update
351 call returns.
352
353 3. Start streaming on the ``OUTPUT`` queue vi
354
355 4. **This step only applies to coded formats
356 in the stream.** Continue queuing/dequeuin
357 ``OUTPUT`` queue via :c:func:`VIDIOC_QBUF`
358 buffers will be processed and returned to
359 required metadata to configure the ``CAPTU
360 indicated by the decoder sending a ``V4L2_
361 ``changes`` set to ``V4L2_EVENT_SRC_CH_RES
362
363 * It is not an error if the first buffer d
364 this to occur. Processing of the buffers
365 data is needed.
366
367 * If data in a buffer that triggers the ev
368 first frame, it will not be returned to
369 initialization sequence completes and th
370
371 * If the client has not set the coded reso
372 calling :c:func:`VIDIOC_G_FMT`, :c:func:
373 :c:func:`VIDIOC_TRY_FMT` or :c:func:`VID
374 queue will not return the real values fo
375 ``V4L2_EVENT_SOURCE_CHANGE`` event with
376 ``V4L2_EVENT_SRC_CH_RESOLUTION`` is sign
377
378 .. important::
379
380 Any client query issued after the decod
381 values applying to the just parsed stre
382 selection rectangles and controls.
383
384 .. note::
385
386 A client capable of acquiring stream pa
387 its own may attempt to set the width an
388 to non-zero values matching the coded s
389 and continue with the `Capture Setup` s
390 rely on any driver queries regarding st
391 selection rectangles and controls, sinc
392 from the stream yet. If the values conf
393 those parsed by the decoder, a `Dynamic
394 triggered to reconfigure them.
395
396 .. note::
397
398 No decoded frames are produced during t
399
400 5. Continue with the `Capture Setup` sequence
401
402 Capture Setup
403 =============
404
405 1. Call :c:func:`VIDIOC_G_FMT` on the ``CAPTU
406 destination buffers parsed/decoded from th
407
408 * **Required fields:**
409
410 ``type``
411 a ``V4L2_BUF_TYPE_*`` enum appropria
412
413 * **Returned fields:**
414
415 ``width``, ``height``
416 frame buffer resolution for the deco
417
418 ``pixelformat``
419 pixel format for decoded frames.
420
421 ``num_planes`` (for _MPLANE ``type`` onl
422 number of planes for pixelformat.
423
424 ``sizeimage``, ``bytesperline``
425 as per standard semantics; matching
426
427 .. note::
428
429 The value of ``pixelformat`` may be any
430 decoder for the current stream. The dec
431 preferred/optimal format for the defaul
432 YUV format may be preferred over an RGB
433 conversion step would be required for t
434
435 2. **Optional.** Acquire the visible resoluti
436 :c:func:`VIDIOC_G_SELECTION`.
437
438 * **Required fields:**
439
440 ``type``
441 a ``V4L2_BUF_TYPE_*`` enum appropria
442
443 ``target``
444 set to ``V4L2_SEL_TGT_COMPOSE``.
445
446 * **Returned fields:**
447
448 ``r.left``, ``r.top``, ``r.width``, ``r.
449 the visible rectangle; it must fit w
450 returned by :c:func:`VIDIOC_G_FMT` o
451
452 * The following selection targets are supp
453
454 ``V4L2_SEL_TGT_CROP_BOUNDS``
455 corresponds to the coded resolution
456
457 ``V4L2_SEL_TGT_CROP_DEFAULT``
458 the rectangle covering the part of t
459 contains meaningful picture data (vi
460 will be equal to the visible resolut
461
462 ``V4L2_SEL_TGT_CROP``
463 the rectangle within the coded resol
464 ``CAPTURE``; defaults to ``V4L2_SEL_
465 hardware without additional compose/
466
467 ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
468 the maximum rectangle within a ``CAP
469 frame can be composed into; equal to
470 hardware does not support compose/sc
471
472 ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
473 equal to ``V4L2_SEL_TGT_CROP``.
474
475 ``V4L2_SEL_TGT_COMPOSE``
476 the rectangle inside a ``CAPTURE`` b
477 frame is written; defaults to ``V4L2
478 read-only on hardware without additi
479
480 ``V4L2_SEL_TGT_COMPOSE_PADDED``
481 the rectangle inside a ``CAPTURE`` b
482 hardware; equal to ``V4L2_SEL_TGT_CO
483 write padding pixels.
484
485 .. warning::
486
487 The values are guaranteed to be meaning
488 successfully parses the stream metadata
489 query before that happens.
490
491 3. **Optional.** Enumerate ``CAPTURE`` format
492 the ``CAPTURE`` queue. Once the stream inf
493 client may use this ioctl to discover whic
494 given stream and select one of them via :c
495
496 .. important::
497
498 The decoder will return only formats su
499 established coded format, as per the ``
500 metadata parsed in this initialization
501 may be supported by the decoder in gene
502 returned will be a subset of the initia
503 `Querying Capabilities` section.
504
505 For example, a decoder may support YUV
506 1920x1088 and lower, but only YUV for h
507 hardware limitations). After parsing a
508 :c:func:`VIDIOC_ENUM_FMT` may return a
509 but after parsing resolution higher tha
510 return RGB, unsupported for this resolu
511
512 However, subsequent resolution change e
513 discovering a resolution change within
514 the stream into a lower resolution and
515 would return RGB formats again in that
516
517 4. **Optional.** Set the ``CAPTURE`` format v
518 ``CAPTURE`` queue. The client may choose a
519 selected/suggested by the decoder in :c:fu
520
521 * **Required fields:**
522
523 ``type``
524 a ``V4L2_BUF_TYPE_*`` enum appropria
525
526 ``pixelformat``
527 a raw pixel format.
528
529 ``width``, ``height``
530 frame buffer resolution of the decode
531 what was returned with :c:func:`VIDIO
532 if the hardware supports composition
533
534 * Setting the ``CAPTURE`` format will reset
535 to their default values, based on the new
536 previous step.
537
538 5. **Optional.** Set the compose rectangle via
539 the ``CAPTURE`` queue if it is desired and
540 scaling capabilities.
541
542 * **Required fields:**
543
544 ``type``
545 a ``V4L2_BUF_TYPE_*`` enum appropriat
546
547 ``target``
548 set to ``V4L2_SEL_TGT_COMPOSE``.
549
550 ``r.left``, ``r.top``, ``r.width``, ``r.h
551 the rectangle inside a ``CAPTURE`` bu
552 frame is written; defaults to ``V4L2_
553 read-only on hardware without additio
554
555 * **Returned fields:**
556
557 ``r.left``, ``r.top``, ``r.width``, ``r.h
558 the visible rectangle; it must fit wi
559 returned by :c:func:`VIDIOC_G_FMT` on
560
561 .. warning::
562
563 The decoder may adjust the compose recta
564 supported one to meet codec and hardware
565 to check the adjusted rectangle returned
566
567 6. If all the following conditions are met, t
568 instantly:
569
570 * ``sizeimage`` of the new format (determi
571 than or equal to the size of currently a
572
573 * the number of buffers currently allocate
574 minimum number of buffers acquired in pr
575 requirement, the client may use :c:func:
576 buffers.
577
578 In that case, the remaining steps do not a
579 the decoding by one of the following actio
580
581 * if the ``CAPTURE`` queue is streaming, c
582 with the ``V4L2_DEC_CMD_START`` command,
583
584 * if the ``CAPTURE`` queue is not streamin
585 on the ``CAPTURE`` queue.
586
587 However, if the client intends to change t
588 memory usage or for any other reasons, it
589 the steps below.
590
591 7. **If the** ``CAPTURE`` **queue is streamin
592 buffers on the ``CAPTURE`` queue until a b
593 ``V4L2_BUF_FLAG_LAST`` flag is dequeued.
594
595 8. **If the** ``CAPTURE`` **queue is streamin
596 on the ``CAPTURE`` queue to stop streaming
597
598 .. warning::
599
600 The ``OUTPUT`` queue must remain stream
601 :c:func:`VIDIOC_STREAMOFF` on it would
602 seek.
603
604 9. **If the** ``CAPTURE`` **queue has buffers
605 buffers using :c:func:`VIDIOC_REQBUFS`.
606
607 * **Required fields:**
608
609 ``count``
610 set to 0.
611
612 ``type``
613 a ``V4L2_BUF_TYPE_*`` enum appropria
614
615 ``memory``
616 follows standard semantics.
617
618 10. Allocate ``CAPTURE`` buffers via :c:func:`
619 ``CAPTURE`` queue.
620
621 * **Required fields:**
622
623 ``count``
624 requested number of buffers to alloc
625
626 ``type``
627 a ``V4L2_BUF_TYPE_*`` enum appropria
628
629 ``memory``
630 follows standard semantics.
631
632 * **Returned fields:**
633
634 ``count``
635 actual number of buffers allocated.
636
637 .. warning::
638
639 The actual number of allocated buffers
640 given. The client must check the update
641 call returns.
642
643 .. note::
644
645 To allocate more than the minimum numbe
646 depth), the client may query the ``V4L2
647 control to get the minimum number of bu
648 obtained value plus the number of addit
649 ``count`` field to :c:func:`VIDIOC_REQB
650
651 Alternatively, :c:func:`VIDIOC_CREATE_BUFS
652 used to have more control over buffer allo
653 allocating buffers larger than the current
654 resolution changes can be accommodated.
655
656 * **Required fields:**
657
658 ``count``
659 requested number of buffers to alloc
660
661 ``type``
662 a ``V4L2_BUF_TYPE_*`` enum appropria
663
664 ``memory``
665 follows standard semantics.
666
667 ``format``
668 a format representing the maximum fr
669 accommodated by newly allocated buff
670
671 * **Returned fields:**
672
673 ``count``
674 adjusted to the number of allocated
675
676 .. warning::
677
678 The actual number of allocated buffers
679 given. The client must check the updat
680 call returns.
681
682 .. note::
683
684 To allocate buffers for a format differ
685 metadata, the client must proceed as fo
686 parsing is initiated:
687
688 * set width and height of the ``OUTPUT`
689 let the decoder configure the ``CAPTU
690
691 * query the ``CAPTURE`` format using :c
692 until this step.
693
694 The format obtained in the query may be
695 :c:func:`VIDIOC_CREATE_BUFS` in this st
696
697 11. Call :c:func:`VIDIOC_STREAMON` on the ``CA
698 frames.
699
700 Decoding
701 ========
702
703 This state is reached after the `Capture Setup
704 In this state, the client queues and dequeues
705 :c:func:`VIDIOC_QBUF` and :c:func:`VIDIOC_DQBU
706 semantics.
707
708 The content of the source ``OUTPUT`` buffers d
709 format and may be affected by codec-specific e
710 the documentation of each format.
711
712 Both queues operate independently, following t
713 buffer queues and memory-to-memory devices. In
714 frames dequeued from the ``CAPTURE`` queue may
715 coded frames to the ``OUTPUT`` queue, due to p
716 format, e.g. frame reordering.
717
718 The client must not assume any direct relation
719 and ``OUTPUT`` buffers and any specific timing
720 available to dequeue. Specifically:
721
722 * a buffer queued to ``OUTPUT`` may result in
723 on ``CAPTURE`` (e.g. if it does not contain
724 metadata syntax structures are present in it
725
726 * a buffer queued to ``OUTPUT`` may result in
727 on ``CAPTURE`` (if the encoded data containe
728 returning a decoded frame allowed the decode
729 preceded it in decode, but succeeded it in t
730
731 * a buffer queued to ``OUTPUT`` may result in
732 ``CAPTURE`` later into decode process, and/o
733 ``OUTPUT`` buffers, or be returned out of or
734 reordering is used,
735
736 * buffers may become available on the ``CAPTUR
737 buffers queued to ``OUTPUT`` (e.g. during dr
738 ``OUTPUT`` buffers queued in the past whose
739 available at later time, due to specifics of
740
741 .. note::
742
743 To allow matching decoded ``CAPTURE`` buffe
744 originated from, the client can set the ``t
745 :c:type:`v4l2_buffer` struct when queuing a
746 ``CAPTURE`` buffer(s), which resulted from
747 will have their ``timestamp`` field set to
748
749 In addition to the straightforward case of
750 one ``CAPTURE`` buffer, the following cases
751
752 * one ``OUTPUT`` buffer generates multiple
753 ``OUTPUT`` timestamp will be copied to mu
754
755 * multiple ``OUTPUT`` buffers generate one
756 the ``OUTPUT`` buffer queued first will b
757
758 * the decoding order differs from the displ
759 buffers are out-of-order compared to the
760 timestamps will not retain the order of `
761
762 .. note::
763
764 The backing memory of ``CAPTURE`` buffers t
765 by the stream may be read by the hardware e
766 Consequently, the client should avoid writi
767 ``CAPTURE`` queue is streaming. Failure to
768 corruption of decoded frames.
769
770 Similarly, when using a memory type other t
771 client should make sure that each ``CAPTURE
772 the same backing memory for as long as the
773 The reason for this is that V4L2 buffer ind
774 identify frames. Thus, if the backing memor
775 submitted under a different buffer ID, the
776 decode a new frame into it while it is stil
777 of the following frames.
778
779 During the decoding, the decoder may initiate
780 listed below. The sequences will result in the
781 ``CAPTURE`` buffers that originated from all t
782 before the sequence started. Last of the buffe
783 ``V4L2_BUF_FLAG_LAST`` flag set. To determine
784 must check if there is any pending event and:
785
786 * if a ``V4L2_EVENT_SOURCE_CHANGE`` event with
787 ``V4L2_EVENT_SRC_CH_RESOLUTION`` is pending,
788 Change` sequence needs to be followed,
789
790 * if a ``V4L2_EVENT_EOS`` event is pending, th
791 to be followed.
792
793 Some of the sequences can be intermixed with e
794 as they happen. The exact operation is documen
795
796 Should a decoding error occur, it will be repo
797 of details depending on the decoder capabiliti
798
799 * the CAPTURE buffer that contains the results
800 will be returned with the V4L2_BUF_FLAG_ERRO
801
802 * if the decoder is able to precisely report t
803 the error, such buffer will be returned with
804 set.
805
806 In case of a fatal failure that does not allow
807 further operations on corresponding decoder fi
808 error code. The client may close the file hand
809 alternatively reinitialize the instance by sto
810 releasing all buffers and performing the Initi
811
812 Seek
813 ====
814
815 Seek is controlled by the ``OUTPUT`` queue, as
816 The seek does not require any specific operati
817 it may be affected as per normal decoder opera
818
819 1. Stop the ``OUTPUT`` queue to begin the seek
820 :c:func:`VIDIOC_STREAMOFF`.
821
822 * **Required fields:**
823
824 ``type``
825 a ``V4L2_BUF_TYPE_*`` enum appropriat
826
827 * The decoder will drop all the pending ``O
828 treated as returned to the client (follow
829
830 2. Restart the ``OUTPUT`` queue via :c:func:`V
831
832 * **Required fields:**
833
834 ``type``
835 a ``V4L2_BUF_TYPE_*`` enum appropriat
836
837 * The decoder will start accepting new sour
838 call returns.
839
840 3. Start queuing buffers containing coded data
841 queue until a suitable resume point is foun
842
843 .. note::
844
845 There is no requirement to begin queuing
846 from a resume point (e.g. SPS or a keyfr
847 buffers will be processed and returned t
848 resume point is found. While looking fo
849 should not produce any decoded frames in
850
851 Some hardware is known to mishandle seek
852 operation may result in an unspecified n
853 being made available on the ``CAPTURE``
854 no fatal decoding errors or crashes occu
855 handling and workarounds for hardware is
856
857 .. warning::
858
859 In case of the H.264/HEVC codec, the cli
860 over a change of SPS/PPS. Even though th
861 keyframe, the stale SPS/PPS inside decod
862 results when decoding. Although the deco
863 a crash or a fatal decode error, the cli
864 decode output.
865
866 If the hardware can detect such corrupte
867 corresponding buffers will be returned t
868 V4L2_BUF_FLAG_ERROR set. See the `Decodi
869 description of decode error reporting.
870
871 4. After a resume point is found, the decoder
872 buffers containing decoded frames.
873
874 .. important::
875
876 A seek may result in the `Dynamic Resolutio
877 initiated, due to the seek target having de
878 the part of the stream decoded before the s
879 as per normal decoder operation.
880
881 .. warning::
882
883 It is not specified when the ``CAPTURE`` qu
884 containing decoded data from the ``OUTPUT``
885 as it operates independently from the ``OUT
886
887 The decoder may return a number of remainin
888 decoded frames originating from the ``OUTPU
889 seek sequence is performed.
890
891 The ``VIDIOC_STREAMOFF`` operation discards
892 ``OUTPUT`` buffers, which means that not al
893 queued before the seek sequence may have ma
894 produced. For example, given the sequence
895 ``OUTPUT`` queue:
896
897 QBUF(A), QBUF(B), STREAMOFF(), STREAMON()
898
899 any of the following results on the ``CAPTU
900
901 {A', B', G', H'}, {A', G', H'}, {G', H'}.
902
903 To determine the CAPTURE buffer containing
904 seek, the client may observe the timestamps
905 buffers or use V4L2_DEC_CMD_STOP and V4L2_D
906 decoder.
907
908 .. note::
909
910 To achieve instantaneous seek, the client m
911 ``CAPTURE`` queue too to discard decoded, b
912
913 Dynamic Resolution Change
914 =========================
915
916 Streams that include resolution metadata in th
917 to a different resolution during the decoding.
918
919 .. note::
920
921 Not all decoders can detect resolution chan
922 ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for t
923 :c:func:`VIDIOC_ENUM_FMT` is called.
924
925 The sequence starts when the decoder detects a
926 the following parameters different from those
927 reflected by corresponding queries):
928
929 * coded resolution (``OUTPUT`` width and heigh
930
931 * visible resolution (selection rectangles),
932
933 * the minimum number of buffers needed for dec
934
935 * bit-depth of the bitstream has been changed.
936
937 Whenever that happens, the decoder must procee
938
939 1. After encountering a resolution change in
940 ``V4L2_EVENT_SOURCE_CHANGE`` event with ``
941 ``V4L2_EVENT_SRC_CH_RESOLUTION``.
942
943 .. important::
944
945 Any client query issued after the decod
946 values applying to the stream after the
947 queue formats, selection rectangles and
948
949 2. The decoder will then process and decode a
950 the resolution change point.
951
952 * The last buffer from before the change m
953 ``V4L2_BUF_FLAG_LAST`` flag, similarly t
954
955 .. warning::
956
957 The last buffer may be empty (with :c:t
958 = 0) and in that case it must be ignore
959 contain a decoded frame.
960
961 .. note::
962
963 Any attempt to dequeue more ``CAPTURE``
964 with ``V4L2_BUF_FLAG_LAST`` will result
965 :c:func:`VIDIOC_DQBUF`.
966
967 The client must continue the sequence as descr
968 decoding process.
969
970 1. Dequeue the source change event.
971
972 .. important::
973
974 A source change triggers an implicit de
975 explicit `Drain` sequence. The decoder
976 The decoding process must be resumed wi
977 :c:func:`VIDIOC_STREAMOFF` and :c:func:
978 ``CAPTURE`` queue, or a call to :c:func
979 ``V4L2_DEC_CMD_START`` command.
980
981 2. Continue with the `Capture Setup` sequence
982
983 .. note::
984
985 During the resolution change sequence, the
986 streaming. Calling :c:func:`VIDIOC_STREAMOF
987 abort the sequence and initiate a seek.
988
989 In principle, the ``OUTPUT`` queue operates
990 queue and this remains true for the duratio
991 sequence as well.
992
993 The client should, for best performance and
994 buffers to/from the ``OUTPUT`` queue even w
995
996 Drain
997 =====
998
999 To ensure that all queued ``OUTPUT`` buffers h
1000 ``CAPTURE`` buffers are given to the client,
1001 sequence described below. After the drain seq
1002 received all decoded frames for all ``OUTPUT`
1003 sequence was started.
1004
1005 1. Begin drain by issuing :c:func:`VIDIOC_DEC
1006
1007 * **Required fields:**
1008
1009 ``cmd``
1010 set to ``V4L2_DEC_CMD_STOP``.
1011
1012 ``flags``
1013 set to 0.
1014
1015 ``pts``
1016 set to 0.
1017
1018 .. warning::
1019
1020 The sequence can be only initiated if b
1021 queues are streaming. For compatibility
1022 :c:func:`VIDIOC_DECODER_CMD` will not f
1023 not streaming, but at the same time it
1024 sequence and so the steps described bel
1025
1026 2. Any ``OUTPUT`` buffers queued by the clien
1027 :c:func:`VIDIOC_DECODER_CMD` was issued wi
1028 normal. The client must continue to handle
1029 similarly to normal decode operation. This
1030
1031 * handling any operations triggered as a r
1032 such as the `Dynamic Resolution Change`
1033 the drain sequence,
1034
1035 * queuing and dequeuing ``CAPTURE`` buffer
1036 ``V4L2_BUF_FLAG_LAST`` flag is dequeued,
1037
1038 .. warning::
1039
1040 The last buffer may be empty (with :c
1041 ``bytesused`` = 0) and in that case i
1042 as it does not contain a decoded fram
1043
1044 .. note::
1045
1046 Any attempt to dequeue more ``CAPTURE
1047 marked with ``V4L2_BUF_FLAG_LAST`` wi
1048 :c:func:`VIDIOC_DQBUF`.
1049
1050 * dequeuing processed ``OUTPUT`` buffers,
1051 before the ``V4L2_DEC_CMD_STOP`` command
1052
1053 * dequeuing the ``V4L2_EVENT_EOS`` event,
1054
1055 .. note::
1056
1057 For backwards compatibility, the decode
1058 event when the last frame has been deco
1059 dequeued. It is a deprecated behavior a
1060 The ``V4L2_BUF_FLAG_LAST`` buffer flag
1061
1062 3. Once all the ``OUTPUT`` buffers queued bef
1063 are dequeued and the last ``CAPTURE`` buff
1064 stopped and it will accept, but not proces
1065 buffers until the client issues any of the
1066
1067 * ``V4L2_DEC_CMD_START`` - the decoder wil
1068 operation normally, with all the state f
1069
1070 * a pair of :c:func:`VIDIOC_STREAMOFF` and
1071 ``CAPTURE`` queue - the decoder will res
1072 however any ``CAPTURE`` buffers still in
1073 client,
1074
1075 * a pair of :c:func:`VIDIOC_STREAMOFF` and
1076 ``OUTPUT`` queue - any pending source bu
1077 client and the `Seek` sequence will be t
1078
1079 .. note::
1080
1081 Once the drain sequence is initiated, the
1082 completion, as described by the steps abov
1083 issuing :c:func:`VIDIOC_STREAMOFF` on any
1084 queues. The client is not allowed to issu
1085 ``V4L2_DEC_CMD_STOP`` again while the drai
1086 will fail with -EBUSY error code if attemp
1087
1088 Although not mandatory, the availability o
1089 using :c:func:`VIDIOC_TRY_DECODER_CMD`.
1090
1091 End of Stream
1092 =============
1093
1094 If the decoder encounters an end of stream ma
1095 will initiate the `Drain` sequence, which the
1096 above, skipping the initial :c:func:`VIDIOC_D
1097
1098 Commit Points
1099 =============
1100
1101 Setting formats and allocating buffers trigge
1102 decoder.
1103
1104 1. Setting the format on the ``OUTPUT`` queue
1105 supported/advertised on the ``CAPTURE`` qu
1106 that the ``CAPTURE`` format may be reset a
1107 previously set format being preserved.
1108
1109 2. Enumerating formats on the ``CAPTURE`` que
1110 supported for the current ``OUTPUT`` forma
1111
1112 3. Setting the format on the ``CAPTURE`` queu
1113 formats available on the ``OUTPUT`` queue.
1114 format that is not supported for the curre
1115 will result in the decoder adjusting the r
1116 supported one.
1117
1118 4. Enumerating formats on the ``OUTPUT`` queu
1119 supported coded formats, irrespectively of
1120
1121 5. While buffers are allocated on any of the
1122 the client must not change the format on t
1123 return the -EBUSY error code for any such
1124
1125 To summarize, setting formats and allocation
1126 ``OUTPUT`` queue and the ``OUTPUT`` queue is
1127 set of supported formats for the ``CAPTURE``
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.