History

media: uapi: h264: Clarify SLICE_BASED mode

Currently, the SLICE_BASED and FRAME_BASED modes documentation is misleading and not matching the intended use-cases. Drop non-required fields SLICE_PARAMS 'start_byte_offset' and DECODE_PARAMS 'num_slices' and clarify the decoding modes in the documentation. On SLICE_BASED mode, a single slice is expected per OUTPUT buffer, and therefore 'start_byte_offset' is not needed (since the offset to the slice is the start of the buffer). This mode requires the use of CAPTURE buffer holding, and so the number of slices shall not be required. On FRAME_BASED mode, the devices are expected to take care of slice parsing. Neither SLICE_PARAMS are required (and shouldn't be exposed by frame-based drivers), nor the number of slices.

Ezequiel Garcia committed 6 years ago

Commit 2287c5e1 parent f6f0d582 files · +10 −33Browse files

Showing the changes to Documentation/userspace-api (1 of 2 files). Show all

Unified · Split

Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst+10−29
@@ -1748,9 +1748,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - · 1747 unmodified lines
17481748 This compound control is not yet part of the public kernel API
17491749 and it is expected to change.
17501750
1751− This structure is expected to be passed as an array, with one
1752− entry for each slice included in the bitstream buffer.
1753−
17541751 .. c:type:: v4l2_ctrl_h264_slice_params
17551752
17561753 .. cssclass:: longtable
@@ -1760,17 +1757,9 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - · 3 unmodified lines
17601757 :stub-columns: 0
17611758 :widths: 1 1 2
17621759
1763− * - __u32
1764− - ``start_byte_offset``
1765− Offset (in bytes) from the beginning of the OUTPUT buffer to the start
1766− of the slice. If the slice starts with a start code, then this is the
1767− offset to such start code. When operating in slice-based decoding mode
1768− (see :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field should
1769− be set to 0. When operating in frame-based decoding mode, this field
1770− should be 0 for the first slice.
17711760 * - __u32
17721761 - ``header_bit_size``
1773− -
1762+ - Offset in bits to slice_data() from the beginning of this slice.
17741763 * - __u32
17751764 - ``first_mb_in_slice``
17761765 -
@@ -1998,12 +1987,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - · 221 unmodified lines
19981987 * - struct :c:type:`v4l2_h264_dpb_entry`
19991988 - ``dpb[16]``
20001989 -
2001− * - __u16
2002− - ``num_slices``
2003− - Number of slices needed to decode the current frame/field. When
2004− operating in slice-based decoding mode (see
2005− :c:type:`v4l2_mpeg_video_h264_decode_mode`), this field
2006− should always be set to one.
20071990 * - __u16
20081991 - ``nal_ref_idc``
20091992 - NAL reference ID value coming from the NAL Unit header
@@ -2121,22 +2104,20 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - · 111 unmodified lines
21212104 * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_SLICE_BASED``
21222105 - 0
21232106 - Decoding is done at the slice granularity.
2124− In this mode, ``num_slices`` field in struct
2125− :c:type:`v4l2_ctrl_h264_decode_params` should be set to 1,
2126− and ``start_byte_offset`` in struct
2127− :c:type:`v4l2_ctrl_h264_slice_params` should be set to 0.
21282107 The OUTPUT buffer must contain a single slice.
2108+ When this mode is selected, the ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS``
2109+ control shall be set. When multiple slices compose a frame,
2110+ use of ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` flag
2111+ is required.
21292112 * - ``V4L2_MPEG_VIDEO_H264_DECODE_MODE_FRAME_BASED``
21302113 - 1
2131− - Decoding is done at the frame granularity.
2132− In this mode, ``num_slices`` field in struct
2133− :c:type:`v4l2_ctrl_h264_decode_params` should be set to the number
2134− of slices in the frame, and ``start_byte_offset`` in struct
2135− :c:type:`v4l2_ctrl_h264_slice_params` should be set accordingly
2136− for each slice. For the first slice, ``start_byte_offset`` should
2137− be zero.
2114+ - Decoding is done at the frame granularity,
21382115 The OUTPUT buffer must contain all slices needed to decode the
21392116 frame. The OUTPUT buffer must also contain both fields.
2117+ This mode will be supported by devices that
2118+ parse the slice(s) header(s) in hardware. When this mode is
2119+ selected, the ``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS``
2120+ control shall not be set.
21402121
21412122 ``V4L2_CID_MPEG_VIDEO_H264_START_CODE (enum)``
21422123 Specifies the H264 slice start code expected for each slice.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t