1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _codec-stateless-controls:
4
5*********************************
6Stateless Codec Control Reference
7*********************************
8
9The Stateless Codec control class is intended to support
10stateless decoder and encoders (i.e. hardware accelerators).
11
12These drivers are typically supported by the :ref:`stateless_decoder`,
13and deal with parsed pixel formats such as V4L2_PIX_FMT_H264_SLICE.
14
15Stateless Codec Control ID
16==========================
17
18.. _codec-stateless-control-id:
19
20``V4L2_CID_CODEC_STATELESS_CLASS (class)``
21    The Stateless Codec class descriptor.
22
23.. _v4l2-codec-stateless-h264:
24
25``V4L2_CID_STATELESS_H264_SPS (struct)``
26    Specifies the sequence parameter set (as extracted from the
27    bitstream) for the associated H264 slice data. This includes the
28    necessary parameters for configuring a stateless hardware decoding
29    pipeline for H264. The bitstream parameters are defined according
30    to :ref:`h264`, section 7.4.2.1.1 "Sequence Parameter Set Data
31    Semantics". For further documentation, refer to the above
32    specification, unless there is an explicit comment stating
33    otherwise.
34
35.. c:type:: v4l2_ctrl_h264_sps
36
37.. raw:: latex
38
39    \small
40
41.. tabularcolumns:: |p{1.2cm}|p{8.6cm}|p{7.5cm}|
42
43.. flat-table:: struct v4l2_ctrl_h264_sps
44    :header-rows:  0
45    :stub-columns: 0
46    :widths:       1 1 2
47
48    * - __u8
49      - ``profile_idc``
50      -
51    * - __u8
52      - ``constraint_set_flags``
53      - See :ref:`Sequence Parameter Set Constraints Set Flags <h264_sps_constraints_set_flags>`
54    * - __u8
55      - ``level_idc``
56      -
57    * - __u8
58      - ``seq_parameter_set_id``
59      -
60    * - __u8
61      - ``chroma_format_idc``
62      -
63    * - __u8
64      - ``bit_depth_luma_minus8``
65      -
66    * - __u8
67      - ``bit_depth_chroma_minus8``
68      -
69    * - __u8
70      - ``log2_max_frame_num_minus4``
71      -
72    * - __u8
73      - ``pic_order_cnt_type``
74      -
75    * - __u8
76      - ``log2_max_pic_order_cnt_lsb_minus4``
77      -
78    * - __u8
79      - ``max_num_ref_frames``
80      -
81    * - __u8
82      - ``num_ref_frames_in_pic_order_cnt_cycle``
83      -
84    * - __s32
85      - ``offset_for_ref_frame[255]``
86      -
87    * - __s32
88      - ``offset_for_non_ref_pic``
89      -
90    * - __s32
91      - ``offset_for_top_to_bottom_field``
92      -
93    * - __u16
94      - ``pic_width_in_mbs_minus1``
95      -
96    * - __u16
97      - ``pic_height_in_map_units_minus1``
98      -
99    * - __u32
100      - ``flags``
101      - See :ref:`Sequence Parameter Set Flags <h264_sps_flags>`
102
103.. raw:: latex
104
105    \normalsize
106
107.. _h264_sps_constraints_set_flags:
108
109``Sequence Parameter Set Constraints Set Flags``
110
111.. cssclass:: longtable
112
113.. flat-table::
114    :header-rows:  0
115    :stub-columns: 0
116    :widths:       1 1 2
117
118    * - ``V4L2_H264_SPS_CONSTRAINT_SET0_FLAG``
119      - 0x00000001
120      -
121    * - ``V4L2_H264_SPS_CONSTRAINT_SET1_FLAG``
122      - 0x00000002
123      -
124    * - ``V4L2_H264_SPS_CONSTRAINT_SET2_FLAG``
125      - 0x00000004
126      -
127    * - ``V4L2_H264_SPS_CONSTRAINT_SET3_FLAG``
128      - 0x00000008
129      -
130    * - ``V4L2_H264_SPS_CONSTRAINT_SET4_FLAG``
131      - 0x00000010
132      -
133    * - ``V4L2_H264_SPS_CONSTRAINT_SET5_FLAG``
134      - 0x00000020
135      -
136
137.. _h264_sps_flags:
138
139``Sequence Parameter Set Flags``
140
141.. cssclass:: longtable
142
143.. flat-table::
144    :header-rows:  0
145    :stub-columns: 0
146    :widths:       1 1 2
147
148    * - ``V4L2_H264_SPS_FLAG_SEPARATE_COLOUR_PLANE``
149      - 0x00000001
150      -
151    * - ``V4L2_H264_SPS_FLAG_QPPRIME_Y_ZERO_TRANSFORM_BYPASS``
152      - 0x00000002
153      -
154    * - ``V4L2_H264_SPS_FLAG_DELTA_PIC_ORDER_ALWAYS_ZERO``
155      - 0x00000004
156      -
157    * - ``V4L2_H264_SPS_FLAG_GAPS_IN_FRAME_NUM_VALUE_ALLOWED``
158      - 0x00000008
159      -
160    * - ``V4L2_H264_SPS_FLAG_FRAME_MBS_ONLY``
161      - 0x00000010
162      -
163    * - ``V4L2_H264_SPS_FLAG_MB_ADAPTIVE_FRAME_FIELD``
164      - 0x00000020
165      -
166    * - ``V4L2_H264_SPS_FLAG_DIRECT_8X8_INFERENCE``
167      - 0x00000040
168      -
169
170``V4L2_CID_STATELESS_H264_PPS (struct)``
171    Specifies the picture parameter set (as extracted from the
172    bitstream) for the associated H264 slice data. This includes the
173    necessary parameters for configuring a stateless hardware decoding
174    pipeline for H264.  The bitstream parameters are defined according
175    to :ref:`h264`, section 7.4.2.2 "Picture Parameter Set RBSP
176    Semantics". For further documentation, refer to the above
177    specification, unless there is an explicit comment stating
178    otherwise.
179
180.. c:type:: v4l2_ctrl_h264_pps
181
182.. raw:: latex
183
184    \small
185
186.. flat-table:: struct v4l2_ctrl_h264_pps
187    :header-rows:  0
188    :stub-columns: 0
189    :widths:       1 1 2
190
191    * - __u8
192      - ``pic_parameter_set_id``
193      -
194    * - __u8
195      - ``seq_parameter_set_id``
196      -
197    * - __u8
198      - ``num_slice_groups_minus1``
199      -
200    * - __u8
201      - ``num_ref_idx_l0_default_active_minus1``
202      -
203    * - __u8
204      - ``num_ref_idx_l1_default_active_minus1``
205      -
206    * - __u8
207      - ``weighted_bipred_idc``
208      -
209    * - __s8
210      - ``pic_init_qp_minus26``
211      -
212    * - __s8
213      - ``pic_init_qs_minus26``
214      -
215    * - __s8
216      - ``chroma_qp_index_offset``
217      -
218    * - __s8
219      - ``second_chroma_qp_index_offset``
220      -
221    * - __u16
222      - ``flags``
223      - See :ref:`Picture Parameter Set Flags <h264_pps_flags>`
224
225.. raw:: latex
226
227    \normalsize
228
229.. _h264_pps_flags:
230
231``Picture Parameter Set Flags``
232
233.. raw:: latex
234
235    \begingroup
236    \scriptsize
237    \setlength{\tabcolsep}{2pt}
238
239.. tabularcolumns:: |p{9.8cm}|p{1.0cm}|p{6.5cm}|
240
241.. flat-table::
242    :header-rows:  0
243    :stub-columns: 0
244    :widths:       10 1 4
245
246    * - ``V4L2_H264_PPS_FLAG_ENTROPY_CODING_MODE``
247      - 0x0001
248      -
249    * - ``V4L2_H264_PPS_FLAG_BOTTOM_FIELD_PIC_ORDER_IN_FRAME_PRESENT``
250      - 0x0002
251      -
252    * - ``V4L2_H264_PPS_FLAG_WEIGHTED_PRED``
253      - 0x0004
254      -
255    * - ``V4L2_H264_PPS_FLAG_DEBLOCKING_FILTER_CONTROL_PRESENT``
256      - 0x0008
257      -
258    * - ``V4L2_H264_PPS_FLAG_CONSTRAINED_INTRA_PRED``
259      - 0x0010
260      -
261    * - ``V4L2_H264_PPS_FLAG_REDUNDANT_PIC_CNT_PRESENT``
262      - 0x0020
263      -
264    * - ``V4L2_H264_PPS_FLAG_TRANSFORM_8X8_MODE``
265      - 0x0040
266      -
267    * - ``V4L2_H264_PPS_FLAG_SCALING_MATRIX_PRESENT``
268      - 0x0080
269      - ``V4L2_CID_STATELESS_H264_SCALING_MATRIX``
270        must be used for this picture.
271
272.. raw:: latex
273
274    \endgroup
275
276``V4L2_CID_STATELESS_H264_SCALING_MATRIX (struct)``
277    Specifies the scaling matrix (as extracted from the bitstream) for
278    the associated H264 slice data. The bitstream parameters are
279    defined according to :ref:`h264`, section 7.4.2.1.1.1 "Scaling
280    List Semantics". For further documentation, refer to the above
281    specification, unless there is an explicit comment stating
282    otherwise.
283
284.. c:type:: v4l2_ctrl_h264_scaling_matrix
285
286.. raw:: latex
287
288    \small
289
290.. tabularcolumns:: |p{0.6cm}|p{4.8cm}|p{11.9cm}|
291
292.. flat-table:: struct v4l2_ctrl_h264_scaling_matrix
293    :header-rows:  0
294    :stub-columns: 0
295    :widths:       1 1 2
296
297    * - __u8
298      - ``scaling_list_4x4[6][16]``
299      - Scaling matrix after applying the inverse scanning process.
300        Expected list order is Intra Y, Intra Cb, Intra Cr, Inter Y,
301        Inter Cb, Inter Cr. The values on each scaling list are
302        expected in raster scan order.
303    * - __u8
304      - ``scaling_list_8x8[6][64]``
305      - Scaling matrix after applying the inverse scanning process.
306        Expected list order is Intra Y, Inter Y, Intra Cb, Inter Cb,
307        Intra Cr, Inter Cr. The values on each scaling list are
308        expected in raster scan order.
309
310``V4L2_CID_STATELESS_H264_SLICE_PARAMS (struct)``
311    Specifies the slice parameters (as extracted from the bitstream)
312    for the associated H264 slice data. This includes the necessary
313    parameters for configuring a stateless hardware decoding pipeline
314    for H264.  The bitstream parameters are defined according to
315    :ref:`h264`, section 7.4.3 "Slice Header Semantics". For further
316    documentation, refer to the above specification, unless there is
317    an explicit comment stating otherwise.
318
319.. c:type:: v4l2_ctrl_h264_slice_params
320
321.. raw:: latex
322
323    \small
324
325.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}|
326
327.. flat-table:: struct v4l2_ctrl_h264_slice_params
328    :header-rows:  0
329    :stub-columns: 0
330    :widths:       1 1 2
331
332    * - __u32
333      - ``header_bit_size``
334      - Offset in bits to slice_data() from the beginning of this slice.
335    * - __u32
336      - ``first_mb_in_slice``
337      -
338    * - __u8
339      - ``slice_type``
340      -
341    * - __u8
342      - ``colour_plane_id``
343      -
344    * - __u8
345      - ``redundant_pic_cnt``
346      -
347    * - __u8
348      - ``cabac_init_idc``
349      -
350    * - __s8
351      - ``slice_qp_delta``
352      -
353    * - __s8
354      - ``slice_qs_delta``
355      -
356    * - __u8
357      - ``disable_deblocking_filter_idc``
358      -
359    * - __s8
360      - ``slice_alpha_c0_offset_div2``
361      -
362    * - __s8
363      - ``slice_beta_offset_div2``
364      -
365    * - __u8
366      - ``num_ref_idx_l0_active_minus1``
367      - If num_ref_idx_active_override_flag is not set, this field must be
368        set to the value of num_ref_idx_l0_default_active_minus1
369    * - __u8
370      - ``num_ref_idx_l1_active_minus1``
371      - If num_ref_idx_active_override_flag is not set, this field must be
372        set to the value of num_ref_idx_l1_default_active_minus1
373    * - __u8
374      - ``reserved``
375      - Applications and drivers must set this to zero.
376    * - struct :c:type:`v4l2_h264_reference`
377      - ``ref_pic_list0[32]``
378      - Reference picture list after applying the per-slice modifications
379    * - struct :c:type:`v4l2_h264_reference`
380      - ``ref_pic_list1[32]``
381      - Reference picture list after applying the per-slice modifications
382    * - __u32
383      - ``flags``
384      - See :ref:`Slice Parameter Flags <h264_slice_flags>`
385
386.. raw:: latex
387
388    \normalsize
389
390.. _h264_slice_flags:
391
392``Slice Parameter Set Flags``
393
394.. cssclass:: longtable
395
396.. flat-table::
397    :header-rows:  0
398    :stub-columns: 0
399    :widths:       1 1 2
400
401    * - ``V4L2_H264_SLICE_FLAG_DIRECT_SPATIAL_MV_PRED``
402      - 0x00000001
403      -
404    * - ``V4L2_H264_SLICE_FLAG_SP_FOR_SWITCH``
405      - 0x00000002
406      -
407
408``V4L2_CID_STATELESS_H264_PRED_WEIGHTS (struct)``
409    Prediction weight table defined according to :ref:`h264`,
410    section 7.4.3.2 "Prediction Weight Table Semantics".
411    The prediction weight table must be passed by applications
412    under the conditions explained in section 7.3.3 "Slice header
413    syntax".
414
415.. c:type:: v4l2_ctrl_h264_pred_weights
416
417.. raw:: latex
418
419    \small
420
421.. tabularcolumns:: |p{4.9cm}|p{4.9cm}|p{7.5cm}|
422
423.. flat-table:: struct v4l2_ctrl_h264_pred_weights
424    :header-rows:  0
425    :stub-columns: 0
426    :widths:       1 1 2
427
428    * - __u16
429      - ``luma_log2_weight_denom``
430      -
431    * - __u16
432      - ``chroma_log2_weight_denom``
433      -
434    * - struct :c:type:`v4l2_h264_weight_factors`
435      - ``weight_factors[2]``
436      - The weight factors at index 0 are the weight factors for the reference
437        list 0, the one at index 1 for the reference list 1.
438
439.. raw:: latex
440
441    \normalsize
442
443.. c:type:: v4l2_h264_weight_factors
444
445.. raw:: latex
446
447    \small
448
449.. tabularcolumns:: |p{1.0cm}|p{4.5cm}|p{11.8cm}|
450
451.. flat-table:: struct v4l2_h264_weight_factors
452    :header-rows:  0
453    :stub-columns: 0
454    :widths:       1 1 2
455
456    * - __s16
457      - ``luma_weight[32]``
458      -
459    * - __s16
460      - ``luma_offset[32]``
461      -
462    * - __s16
463      - ``chroma_weight[32][2]``
464      -
465    * - __s16
466      - ``chroma_offset[32][2]``
467      -
468
469.. raw:: latex
470
471    \normalsize
472
473``Picture Reference``
474
475.. c:type:: v4l2_h264_reference
476
477.. cssclass:: longtable
478
479.. flat-table:: struct v4l2_h264_reference
480    :header-rows:  0
481    :stub-columns: 0
482    :widths:       1 1 2
483
484    * - __u8
485      - ``fields``
486      - Specifies how the picture is referenced. See :ref:`Reference Fields <h264_ref_fields>`
487    * - __u8
488      - ``index``
489      - Index into the :c:type:`v4l2_ctrl_h264_decode_params`.dpb array.
490
491.. _h264_ref_fields:
492
493``Reference Fields``
494
495.. raw:: latex
496
497    \small
498
499.. tabularcolumns:: |p{5.4cm}|p{0.8cm}|p{11.1cm}|
500
501.. flat-table::
502    :header-rows:  0
503    :stub-columns: 0
504    :widths:       1 1 2
505
506    * - ``V4L2_H264_TOP_FIELD_REF``
507      - 0x1
508      - The top field in field pair is used for short-term reference.
509    * - ``V4L2_H264_BOTTOM_FIELD_REF``
510      - 0x2
511      - The bottom field in field pair is used for short-term reference.
512    * - ``V4L2_H264_FRAME_REF``
513      - 0x3
514      - The frame (or the top/bottom fields, if it's a field pair)
515        is used for short-term reference.
516
517.. raw:: latex
518
519    \normalsize
520
521``V4L2_CID_STATELESS_H264_DECODE_PARAMS (struct)``
522    Specifies the decode parameters (as extracted from the bitstream)
523    for the associated H264 slice data. This includes the necessary
524    parameters for configuring a stateless hardware decoding pipeline
525    for H264. The bitstream parameters are defined according to
526    :ref:`h264`. For further documentation, refer to the above
527    specification, unless there is an explicit comment stating
528    otherwise.
529
530.. c:type:: v4l2_ctrl_h264_decode_params
531
532.. raw:: latex
533
534    \small
535
536.. tabularcolumns:: |p{4.0cm}|p{5.9cm}|p{7.4cm}|
537
538.. flat-table:: struct v4l2_ctrl_h264_decode_params
539    :header-rows:  0
540    :stub-columns: 0
541    :widths:       1 1 2
542
543    * - struct :c:type:`v4l2_h264_dpb_entry`
544      - ``dpb[16]``
545      -
546    * - __u16
547      - ``nal_ref_idc``
548      - NAL reference ID value coming from the NAL Unit header
549    * - __u16
550      - ``frame_num``
551      -
552    * - __s32
553      - ``top_field_order_cnt``
554      - Picture Order Count for the coded top field
555    * - __s32
556      - ``bottom_field_order_cnt``
557      - Picture Order Count for the coded bottom field
558    * - __u16
559      - ``idr_pic_id``
560      -
561    * - __u16
562      - ``pic_order_cnt_lsb``
563      -
564    * - __s32
565      - ``delta_pic_order_cnt_bottom``
566      -
567    * - __s32
568      - ``delta_pic_order_cnt0``
569      -
570    * - __s32
571      - ``delta_pic_order_cnt1``
572      -
573    * - __u32
574      - ``dec_ref_pic_marking_bit_size``
575      - Size in bits of the dec_ref_pic_marking() syntax element.
576    * - __u32
577      - ``pic_order_cnt_bit_size``
578      - Combined size in bits of the picture order count related syntax
579        elements: pic_order_cnt_lsb, delta_pic_order_cnt_bottom,
580        delta_pic_order_cnt0, and delta_pic_order_cnt1.
581    * - __u32
582      - ``slice_group_change_cycle``
583      -
584    * - __u32
585      - ``reserved``
586      - Applications and drivers must set this to zero.
587    * - __u32
588      - ``flags``
589      - See :ref:`Decode Parameters Flags <h264_decode_params_flags>`
590
591.. raw:: latex
592
593    \normalsize
594
595.. _h264_decode_params_flags:
596
597``Decode Parameters Flags``
598
599.. raw:: latex
600
601    \small
602
603.. tabularcolumns:: |p{8.3cm}|p{2.1cm}|p{6.9cm}|
604
605.. flat-table::
606    :header-rows:  0
607    :stub-columns: 0
608    :widths:       1 1 2
609
610    * - ``V4L2_H264_DECODE_PARAM_FLAG_IDR_PIC``
611      - 0x00000001
612      - That picture is an IDR picture
613    * - ``V4L2_H264_DECODE_PARAM_FLAG_FIELD_PIC``
614      - 0x00000002
615      -
616    * - ``V4L2_H264_DECODE_PARAM_FLAG_BOTTOM_FIELD``
617      - 0x00000004
618      -
619
620.. raw:: latex
621
622    \normalsize
623
624.. c:type:: v4l2_h264_dpb_entry
625
626.. raw:: latex
627
628    \small
629
630.. tabularcolumns:: |p{1.0cm}|p{4.9cm}|p{11.4cm}|
631
632.. flat-table:: struct v4l2_h264_dpb_entry
633    :header-rows:  0
634    :stub-columns: 0
635    :widths:       1 1 2
636
637    * - __u64
638      - ``reference_ts``
639      - Timestamp of the V4L2 capture buffer to use as reference, used
640        with B-coded and P-coded frames. The timestamp refers to the
641        ``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the
642        :c:func:`v4l2_timeval_to_ns()` function to convert the struct
643        :c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64.
644    * - __u32
645      - ``pic_num``
646      -
647    * - __u16
648      - ``frame_num``
649      -
650    * - __u8
651      - ``fields``
652      - Specifies how the DPB entry is referenced. See :ref:`Reference Fields <h264_ref_fields>`
653    * - __u8
654      - ``reserved[5]``
655      - Applications and drivers must set this to zero.
656    * - __s32
657      - ``top_field_order_cnt``
658      -
659    * - __s32
660      - ``bottom_field_order_cnt``
661      -
662    * - __u32
663      - ``flags``
664      - See :ref:`DPB Entry Flags <h264_dpb_flags>`
665
666.. raw:: latex
667
668    \normalsize
669
670.. _h264_dpb_flags:
671
672``DPB Entries Flags``
673
674.. raw:: latex
675
676    \small
677
678.. tabularcolumns:: |p{7.7cm}|p{2.1cm}|p{7.5cm}|
679
680.. flat-table::
681    :header-rows:  0
682    :stub-columns: 0
683    :widths:       1 1 2
684
685    * - ``V4L2_H264_DPB_ENTRY_FLAG_VALID``
686      - 0x00000001
687      - The DPB entry is valid (non-empty) and should be considered.
688    * - ``V4L2_H264_DPB_ENTRY_FLAG_ACTIVE``
689      - 0x00000002
690      - The DPB entry is used for reference.
691    * - ``V4L2_H264_DPB_ENTRY_FLAG_LONG_TERM``
692      - 0x00000004
693      - The DPB entry is used for long-term reference.
694    * - ``V4L2_H264_DPB_ENTRY_FLAG_FIELD``
695      - 0x00000008
696      - The DPB entry is a single field or a complementary field pair.
697
698.. raw:: latex
699
700    \normalsize
701
702``V4L2_CID_STATELESS_H264_DECODE_MODE (enum)``
703    Specifies the decoding mode to use. Currently exposes slice-based and
704    frame-based decoding but new modes might be added later on.
705    This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE
706    pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE
707    are required to set this control in order to specify the decoding mode
708    that is expected for the buffer.
709    Drivers may expose a single or multiple decoding modes, depending
710    on what they can support.
711
712.. c:type:: v4l2_stateless_h264_decode_mode
713
714.. raw:: latex
715
716    \scriptsize
717
718.. tabularcolumns:: |p{7.4cm}|p{0.3cm}|p{9.6cm}|
719
720.. flat-table::
721    :header-rows:  0
722    :stub-columns: 0
723    :widths:       1 1 2
724
725    * - ``V4L2_STATELESS_H264_DECODE_MODE_SLICE_BASED``
726      - 0
727      - Decoding is done at the slice granularity.
728        The OUTPUT buffer must contain a single slice.
729        When this mode is selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS``
730        control shall be set. When multiple slices compose a frame,
731        use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag
732        is required.
733    * - ``V4L2_STATELESS_H264_DECODE_MODE_FRAME_BASED``
734      - 1
735      - Decoding is done at the frame granularity,
736        The OUTPUT buffer must contain all slices needed to decode the
737        frame. The OUTPUT buffer must also contain both fields.
738        This mode will be supported by devices that
739        parse the slice(s) header(s) in hardware. When this mode is
740        selected, the ``V4L2_CID_STATELESS_H264_SLICE_PARAMS``
741        control shall not be set.
742
743.. raw:: latex
744
745    \normalsize
746
747``V4L2_CID_STATELESS_H264_START_CODE (enum)``
748    Specifies the H264 slice start code expected for each slice.
749    This control is used as a modifier for V4L2_PIX_FMT_H264_SLICE
750    pixel format. Applications that support V4L2_PIX_FMT_H264_SLICE
751    are required to set this control in order to specify the start code
752    that is expected for the buffer.
753    Drivers may expose a single or multiple start codes, depending
754    on what they can support.
755
756.. c:type:: v4l2_stateless_h264_start_code
757
758.. raw:: latex
759
760    \small
761
762.. tabularcolumns:: |p{7.9cm}|p{0.4cm}|p{9.0cm}|
763
764.. flat-table::
765    :header-rows:  0
766    :stub-columns: 0
767    :widths:       4 1 4
768
769    * - ``V4L2_STATELESS_H264_START_CODE_NONE``
770      - 0
771      - Selecting this value specifies that H264 slices are passed
772        to the driver without any start code. The bitstream data should be
773        according to :ref:`h264` 7.3.1 NAL unit syntax, hence contains
774        emulation prevention bytes when required.
775    * - ``V4L2_STATELESS_H264_START_CODE_ANNEX_B``
776      - 1
777      - Selecting this value specifies that H264 slices are expected
778        to be prefixed by Annex B start codes. According to :ref:`h264`
779        valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001.
780
781.. raw:: latex
782
783    \normalsize
784
785.. _codec-stateless-fwht:
786
787``V4L2_CID_STATELESS_FWHT_PARAMS (struct)``
788    Specifies the FWHT (Fast Walsh Hadamard Transform) parameters (as extracted
789    from the bitstream) for the associated FWHT data. This includes the necessary
790    parameters for configuring a stateless hardware decoding pipeline for FWHT.
791    This codec is specific to the vicodec test driver.
792
793.. c:type:: v4l2_ctrl_fwht_params
794
795.. raw:: latex
796
797    \small
798
799.. tabularcolumns:: |p{1.4cm}|p{3.9cm}|p{12.0cm}|
800
801.. flat-table:: struct v4l2_ctrl_fwht_params
802    :header-rows:  0
803    :stub-columns: 0
804    :widths:       1 1 2
805
806    * - __u64
807      - ``backward_ref_ts``
808      - Timestamp of the V4L2 capture buffer to use as backward reference, used
809        with P-coded frames. The timestamp refers to the
810	``timestamp`` field in struct :c:type:`v4l2_buffer`. Use the
811	:c:func:`v4l2_timeval_to_ns()` function to convert the struct
812	:c:type:`timeval` in struct :c:type:`v4l2_buffer` to a __u64.
813    * - __u32
814      - ``version``
815      - The version of the codec. Set to ``V4L2_FWHT_VERSION``.
816    * - __u32
817      - ``width``
818      - The width of the frame.
819    * - __u32
820      - ``height``
821      - The height of the frame.
822    * - __u32
823      - ``flags``
824      - The flags of the frame, see :ref:`fwht-flags`.
825    * - __u32
826      - ``colorspace``
827      - The colorspace of the frame, from enum :c:type:`v4l2_colorspace`.
828    * - __u32
829      - ``xfer_func``
830      - The transfer function, from enum :c:type:`v4l2_xfer_func`.
831    * - __u32
832      - ``ycbcr_enc``
833      - The Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
834    * - __u32
835      - ``quantization``
836      - The quantization range, from enum :c:type:`v4l2_quantization`.
837
838.. raw:: latex
839
840    \normalsize
841
842.. _fwht-flags:
843
844FWHT Flags
845==========
846
847.. raw:: latex
848
849    \small
850
851.. tabularcolumns:: |p{7.0cm}|p{2.3cm}|p{8.0cm}|
852
853.. flat-table::
854    :header-rows:  0
855    :stub-columns: 0
856    :widths:       3 1 4
857
858    * - ``V4L2_FWHT_FL_IS_INTERLACED``
859      - 0x00000001
860      - Set if this is an interlaced format.
861    * - ``V4L2_FWHT_FL_IS_BOTTOM_FIRST``
862      - 0x00000002
863      - Set if this is a bottom-first (NTSC) interlaced format.
864    * - ``V4L2_FWHT_FL_IS_ALTERNATE``
865      - 0x00000004
866      - Set if each 'frame' contains just one field.
867    * - ``V4L2_FWHT_FL_IS_BOTTOM_FIELD``
868      - 0x00000008
869      - If V4L2_FWHT_FL_IS_ALTERNATE was set, then this is set if this 'frame' is the
870	bottom field, else it is the top field.
871    * - ``V4L2_FWHT_FL_LUMA_IS_UNCOMPRESSED``
872      - 0x00000010
873      - Set if the Y' (luma) plane is uncompressed.
874    * - ``V4L2_FWHT_FL_CB_IS_UNCOMPRESSED``
875      - 0x00000020
876      - Set if the Cb plane is uncompressed.
877    * - ``V4L2_FWHT_FL_CR_IS_UNCOMPRESSED``
878      - 0x00000040
879      - Set if the Cr plane is uncompressed.
880    * - ``V4L2_FWHT_FL_CHROMA_FULL_HEIGHT``
881      - 0x00000080
882      - Set if the chroma plane has the same height as the luma plane,
883	else the chroma plane is half the height of the luma plane.
884    * - ``V4L2_FWHT_FL_CHROMA_FULL_WIDTH``
885      - 0x00000100
886      - Set if the chroma plane has the same width as the luma plane,
887	else the chroma plane is half the width of the luma plane.
888    * - ``V4L2_FWHT_FL_ALPHA_IS_UNCOMPRESSED``
889      - 0x00000200
890      - Set if the alpha plane is uncompressed.
891    * - ``V4L2_FWHT_FL_I_FRAME``
892      - 0x00000400
893      - Set if this is an I-frame.
894    * - ``V4L2_FWHT_FL_COMPONENTS_NUM_MSK``
895      - 0x00070000
896      - The number of color components minus one.
897    * - ``V4L2_FWHT_FL_PIXENC_MSK``
898      - 0x00180000
899      - The mask for the pixel encoding.
900    * - ``V4L2_FWHT_FL_PIXENC_YUV``
901      - 0x00080000
902      - Set if the pixel encoding is YUV.
903    * - ``V4L2_FWHT_FL_PIXENC_RGB``
904      - 0x00100000
905      - Set if the pixel encoding is RGB.
906    * - ``V4L2_FWHT_FL_PIXENC_HSV``
907      - 0x00180000
908      - Set if the pixel encoding is HSV.
909
910.. raw:: latex
911
912    \normalsize
913
914.. _v4l2-codec-stateless-vp8:
915
916``V4L2_CID_STATELESS_VP8_FRAME (struct)``
917    Specifies the frame parameters for the associated VP8 parsed frame data.
918    This includes the necessary parameters for
919    configuring a stateless hardware decoding pipeline for VP8.
920    The bitstream parameters are defined according to :ref:`vp8`.
921
922.. c:type:: v4l2_ctrl_vp8_frame
923
924.. raw:: latex
925
926    \small
927
928.. tabularcolumns:: |p{7.0cm}|p{4.6cm}|p{5.7cm}|
929
930.. cssclass:: longtable
931
932.. flat-table:: struct v4l2_ctrl_vp8_frame
933    :header-rows:  0
934    :stub-columns: 0
935    :widths:       1 1 2
936
937    * - struct :c:type:`v4l2_vp8_segment`
938      - ``segment``
939      - Structure with segment-based adjustments metadata.
940    * - struct :c:type:`v4l2_vp8_loop_filter`
941      - ``lf``
942      - Structure with loop filter level adjustments metadata.
943    * - struct :c:type:`v4l2_vp8_quantization`
944      - ``quant``
945      - Structure with VP8 dequantization indices metadata.
946    * - struct :c:type:`v4l2_vp8_entropy`
947      - ``entropy``
948      - Structure with VP8 entropy coder probabilities metadata.
949    * - struct :c:type:`v4l2_vp8_entropy_coder_state`
950      - ``coder_state``
951      - Structure with VP8 entropy coder state.
952    * - __u16
953      - ``width``
954      - The width of the frame. Must be set for all frames.
955    * - __u16
956      - ``height``
957      - The height of the frame. Must be set for all frames.
958    * - __u8
959      - ``horizontal_scale``
960      - Horizontal scaling factor.
961    * - __u8
962      - ``vertical_scaling factor``
963      - Vertical scale.
964    * - __u8
965      - ``version``
966      - Bitstream version.
967    * - __u8
968      - ``prob_skip_false``
969      - Indicates the probability that the macroblock is not skipped.
970    * - __u8
971      - ``prob_intra``
972      - Indicates the probability that a macroblock is intra-predicted.
973    * - __u8
974      - ``prob_last``
975      - Indicates the probability that the last reference frame is used
976        for inter-prediction
977    * - __u8
978      - ``prob_gf``
979      - Indicates the probability that the golden reference frame is used
980        for inter-prediction
981    * - __u8
982      - ``num_dct_parts``
983      - Number of DCT coefficients partitions. Must be one of: 1, 2, 4, or 8.
984    * - __u32
985      - ``first_part_size``
986      - Size of the first partition, i.e. the control partition.
987    * - __u32
988      - ``first_part_header_bits``
989      - Size in bits of the first partition header portion.
990    * - __u32
991      - ``dct_part_sizes[8]``
992      - DCT coefficients sizes.
993    * - __u64
994      - ``last_frame_ts``
995      - Timestamp for the V4L2 capture buffer to use as last reference frame, used
996        with inter-coded frames. The timestamp refers to the ``timestamp`` field in
997	struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
998	function to convert the struct :c:type:`timeval` in struct
999	:c:type:`v4l2_buffer` to a __u64.
1000    * - __u64
1001      - ``golden_frame_ts``
1002      - Timestamp for the V4L2 capture buffer to use as last reference frame, used
1003        with inter-coded frames. The timestamp refers to the ``timestamp`` field in
1004	struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
1005	function to convert the struct :c:type:`timeval` in struct
1006	:c:type:`v4l2_buffer` to a __u64.
1007    * - __u64
1008      - ``alt_frame_ts``
1009      - Timestamp for the V4L2 capture buffer to use as alternate reference frame, used
1010        with inter-coded frames. The timestamp refers to the ``timestamp`` field in
1011	struct :c:type:`v4l2_buffer`. Use the :c:func:`v4l2_timeval_to_ns()`
1012	function to convert the struct :c:type:`timeval` in struct
1013	:c:type:`v4l2_buffer` to a __u64.
1014    * - __u64
1015      - ``flags``
1016      - See :ref:`Frame Flags <vp8_frame_flags>`
1017
1018.. raw:: latex
1019
1020    \normalsize
1021
1022.. _vp8_frame_flags:
1023
1024``Frame Flags``
1025
1026.. tabularcolumns:: |p{9.8cm}|p{0.8cm}|p{6.7cm}|
1027
1028.. cssclass:: longtable
1029
1030.. flat-table::
1031    :header-rows:  0
1032    :stub-columns: 0
1033    :widths:       1 1 2
1034
1035    * - ``V4L2_VP8_FRAME_FLAG_KEY_FRAME``
1036      - 0x01
1037      - Indicates if the frame is a key frame.
1038    * - ``V4L2_VP8_FRAME_FLAG_EXPERIMENTAL``
1039      - 0x02
1040      - Experimental bitstream.
1041    * - ``V4L2_VP8_FRAME_FLAG_SHOW_FRAME``
1042      - 0x04
1043      - Show frame flag, indicates if the frame is for display.
1044    * - ``V4L2_VP8_FRAME_FLAG_MB_NO_SKIP_COEFF``
1045      - 0x08
1046      - Enable/disable skipping of macroblocks with no non-zero coefficients.
1047    * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_GOLDEN``
1048      - 0x10
1049      - Sign of motion vectors when the golden frame is referenced.
1050    * - ``V4L2_VP8_FRAME_FLAG_SIGN_BIAS_ALT``
1051      - 0x20
1052      - Sign of motion vectors when the alt frame is referenced.
1053
1054.. c:type:: v4l2_vp8_entropy_coder_state
1055
1056.. cssclass:: longtable
1057
1058.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}|
1059
1060.. flat-table:: struct v4l2_vp8_entropy_coder_state
1061    :header-rows:  0
1062    :stub-columns: 0
1063    :widths:       1 1 2
1064
1065    * - __u8
1066      - ``range``
1067      - coder state value for "Range"
1068    * - __u8
1069      - ``value``
1070      - coder state value for "Value"-
1071    * - __u8
1072      - ``bit_count``
1073      - number of bits left.
1074    * - __u8
1075      - ``padding``
1076      - Applications and drivers must set this to zero.
1077
1078.. c:type:: v4l2_vp8_segment
1079
1080.. cssclass:: longtable
1081
1082.. tabularcolumns:: |p{1.2cm}|p{4.0cm}|p{12.1cm}|
1083
1084.. flat-table:: struct v4l2_vp8_segment
1085    :header-rows:  0
1086    :stub-columns: 0
1087    :widths:       1 1 2
1088
1089    * - __s8
1090      - ``quant_update[4]``
1091      - Signed quantizer value update.
1092    * - __s8
1093      - ``lf_update[4]``
1094      - Signed loop filter level value update.
1095    * - __u8
1096      - ``segment_probs[3]``
1097      - Segment probabilities.
1098    * - __u8
1099      - ``padding``
1100      - Applications and drivers must set this to zero.
1101    * - __u32
1102      - ``flags``
1103      - See :ref:`Segment Flags <vp8_segment_flags>`
1104
1105.. _vp8_segment_flags:
1106
1107``Segment Flags``
1108
1109.. raw:: latex
1110
1111    \small
1112
1113.. tabularcolumns:: |p{10cm}|p{1.0cm}|p{6.3cm}|
1114
1115.. flat-table::
1116    :header-rows:  0
1117    :stub-columns: 0
1118    :widths:       1 1 2
1119
1120    * - ``V4L2_VP8_SEGMENT_FLAG_ENABLED``
1121      - 0x01
1122      - Enable/disable segment-based adjustments.
1123    * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_MAP``
1124      - 0x02
1125      - Indicates if the macroblock segmentation map is updated in this frame.
1126    * - ``V4L2_VP8_SEGMENT_FLAG_UPDATE_FEATURE_DATA``
1127      - 0x04
1128      - Indicates if the segment feature data is updated in this frame.
1129    * - ``V4L2_VP8_SEGMENT_FLAG_DELTA_VALUE_MODE``
1130      - 0x08
1131      - If is set, the segment feature data mode is delta-value.
1132        If cleared, it's absolute-value.
1133
1134.. raw:: latex
1135
1136    \normalsize
1137
1138.. c:type:: v4l2_vp8_loop_filter
1139
1140.. cssclass:: longtable
1141
1142.. tabularcolumns:: |p{1.5cm}|p{3.9cm}|p{11.9cm}|
1143
1144.. flat-table:: struct v4l2_vp8_loop_filter
1145    :header-rows:  0
1146    :stub-columns: 0
1147    :widths:       1 1 2
1148
1149    * - __s8
1150      - ``ref_frm_delta[4]``
1151      - Reference adjustment (signed) delta value.
1152    * - __s8
1153      - ``mb_mode_delta[4]``
1154      - Macroblock prediction mode adjustment (signed) delta value.
1155    * - __u8
1156      - ``sharpness_level``
1157      - Sharpness level
1158    * - __u8
1159      - ``level``
1160      - Filter level
1161    * - __u16
1162      - ``padding``
1163      - Applications and drivers must set this to zero.
1164    * - __u32
1165      - ``flags``
1166      - See :ref:`Loop Filter Flags <vp8_loop_filter_flags>`
1167
1168.. _vp8_loop_filter_flags:
1169
1170``Loop Filter Flags``
1171
1172.. tabularcolumns:: |p{7.0cm}|p{1.2cm}|p{9.1cm}|
1173
1174.. flat-table::
1175    :header-rows:  0
1176    :stub-columns: 0
1177    :widths:       1 1 2
1178
1179    * - ``V4L2_VP8_LF_ADJ_ENABLE``
1180      - 0x01
1181      - Enable/disable macroblock-level loop filter adjustment.
1182    * - ``V4L2_VP8_LF_DELTA_UPDATE``
1183      - 0x02
1184      - Indicates if the delta values used in an adjustment are updated.
1185    * - ``V4L2_VP8_LF_FILTER_TYPE_SIMPLE``
1186      - 0x04
1187      - If set, indicates the filter type is simple.
1188        If cleared, the filter type is normal.
1189
1190.. c:type:: v4l2_vp8_quantization
1191
1192.. tabularcolumns:: |p{1.5cm}|p{3.5cm}|p{12.3cm}|
1193
1194.. flat-table:: struct v4l2_vp8_quantization
1195    :header-rows:  0
1196    :stub-columns: 0
1197    :widths:       1 1 2
1198
1199    * - __u8
1200      - ``y_ac_qi``
1201      - Luma AC coefficient table index.
1202    * - __s8
1203      - ``y_dc_delta``
1204      - Luma DC delta vaue.
1205    * - __s8
1206      - ``y2_dc_delta``
1207      - Y2 block DC delta value.
1208    * - __s8
1209      - ``y2_ac_delta``
1210      - Y2 block AC delta value.
1211    * - __s8
1212      - ``uv_dc_delta``
1213      - Chroma DC delta value.
1214    * - __s8
1215      - ``uv_ac_delta``
1216      - Chroma AC delta value.
1217    * - __u16
1218      - ``padding``
1219      - Applications and drivers must set this to zero.
1220
1221.. c:type:: v4l2_vp8_entropy
1222
1223.. cssclass:: longtable
1224
1225.. tabularcolumns:: |p{1.5cm}|p{5.8cm}|p{10.0cm}|
1226
1227.. flat-table:: struct v4l2_vp8_entropy
1228    :header-rows:  0
1229    :stub-columns: 0
1230    :widths:       1 1 2
1231
1232    * - __u8
1233      - ``coeff_probs[4][8][3][11]``
1234      - Coefficient update probabilities.
1235    * - __u8
1236      - ``y_mode_probs[4]``
1237      - Luma mode update probabilities.
1238    * - __u8
1239      - ``uv_mode_probs[3]``
1240      - Chroma mode update probabilities.
1241    * - __u8
1242      - ``mv_probs[2][19]``
1243      - MV decoding update probabilities.
1244    * - __u8
1245      - ``padding[3]``
1246      - Applications and drivers must set this to zero.
1247