aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorEzequiel Garcia <ezequiel@collabora.com>2021-04-29 16:48:12 +0200
committerMauro Carvalho Chehab <mchehab+huawei@kernel.org>2021-05-23 19:21:31 +0200
commitf329e21e9dadc5c8ee37c781b30fe63bf7217201 (patch)
tree34db63bf2ecfa482b87a92cdecd3fb7bc084536c /Documentation
parent88e78409a83a579fde7f150be7ebeefab0e1f774 (diff)
media: uapi: mpeg2: Split sequence and picture parameters
Typically, bitstreams are composed of a sequence header, followed by a number of picture header and picture coding extension headers. Each picture can be composed of a number of slices. Let's split the MPEG-2 uAPI to follow these semantics more closely, allowing more usage flexibility. Having these controls split up allows applications to set a sequence control at the beginning of a sequence, and then set a picture control for each frame. While here add padding fields where needed, and document the uAPI header thoroughly. Note that the V4L2_CTRL_TYPE_{} defines had to be moved because it clashes with existing ones. This is not really an issue since they will be re-defined when the controls are moved out of staging. Signed-off-by: Ezequiel Garcia <ezequiel@collabora.com> Tested-by: Jonas Karlman <jonas@kwiboo.se> Tested-by: Jernej Skrabec <jernej.skrabec@siol.net> Reviewed-by: Jernej Skrabec <jernej.skrabec@siol.net> Tested-by: Daniel Almeida <daniel.almeida@collabora.com> Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst64
-rw-r--r--Documentation/userspace-api/media/v4l/pixfmt-compressed.rst5
-rw-r--r--Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst12
-rw-r--r--Documentation/userspace-api/media/videodev2.h.rst.exceptions2
4 files changed, 59 insertions, 24 deletions
diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
index aa11346e7e27..f96a2dcb22cc 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
@@ -1636,14 +1636,6 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type -
* - __u32
- ``data_bit_offset``
- Offset (in bits) to the video data in the current slice data.
- * - struct :c:type:`v4l2_mpeg2_sequence`
- - ``sequence``
- - Structure with MPEG-2 sequence metadata, merging relevant fields from
- the sequence header and sequence extension parts of the bitstream.
- * - struct :c:type:`v4l2_mpeg2_picture`
- - ``picture``
- - Structure with MPEG-2 picture metadata, merging relevant fields from
- the picture header and picture coding extension parts of the bitstream.
* - __u64
- ``backward_ref_ts``
- Timestamp of the V4L2 capture buffer to use as backward reference, used
@@ -1661,14 +1653,28 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type -
* - __u32
- ``quantiser_scale_code``
- Code used to determine the quantization scale to use for the IDCT.
+ * - __u8
+ - ``reserved``
+ - Applications and drivers must set this to zero.
-.. c:type:: v4l2_mpeg2_sequence
+``V4L2_CID_MPEG_VIDEO_MPEG2_SEQUENCE (struct)``
+ Specifies the sequence parameters (as extracted from the bitstream) for the
+ associated MPEG-2 slice data. This includes fields matching the syntax
+ elements from the sequence header and sequence extension parts of the
+ bitstream as specified by :ref:`mpeg2part2`.
+
+ .. note::
+
+ This compound control is not yet part of the public kernel API and
+ it is expected to change.
+
+.. c:type:: v4l2_ctrl_mpeg2_sequence
.. cssclass:: longtable
.. tabularcolumns:: |p{1.4cm}|p{6.5cm}|p{9.4cm}|
-.. flat-table:: struct v4l2_mpeg2_sequence
+.. flat-table:: struct v4l2_ctrl_mpeg2_sequence
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
@@ -1690,7 +1696,7 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type -
* - __u8
- ``chroma_format``
- The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4).
- * - __u32
+ * - __u8
- ``flags``
- See :ref:`MPEG-2 Sequence Flags <mpeg2_sequence_flags>`.
@@ -1706,11 +1712,22 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type -
:widths: 1 1 2
* - ``V4L2_MPEG2_SEQ_FLAG_PROGRESSIVE``
- - 0x00000001
+ - 0x01
- Indication that all the frames for the sequence are progressive instead
of interlaced.
-.. c:type:: v4l2_mpeg2_picture
+``V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE (struct)``
+ Specifies the picture parameters (as extracted from the bitstream) for the
+ associated MPEG-2 slice data. This includes fields matching the syntax
+ elements from the picture header and picture coding extension parts of the
+ bitstream as specified by :ref:`mpeg2part2`.
+
+ .. note::
+
+ This compound control is not yet part of the public kernel API and
+ it is expected to change.
+
+.. c:type:: v4l2_ctrl_mpeg2_picture
.. raw:: latex
@@ -1720,30 +1737,33 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type -
.. tabularcolumns:: |p{1.0cm}|p{5.6cm}|p{10.7cm}|
-.. flat-table:: struct v4l2_mpeg2_picture
+.. flat-table:: struct v4l2_ctrl_mpeg2_picture
:header-rows: 0
:stub-columns: 0
:widths: 1 1 2
+ * - __u32
+ - ``flags``
+ - See :ref:`MPEG-2 Picture Flags <mpeg2_picture_flags>`.
+ * - __u8
+ - ``f_code[2][2]``
+ - Motion vector codes.
* - __u8
- ``picture_coding_type``
- Picture coding type for the frame covered by the current slice
(V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or
V4L2_MPEG2_PICTURE_CODING_TYPE_B).
* - __u8
- - ``f_code[2][2]``
- - Motion vector codes.
+ - ``picture_structure``
+ - Picture structure (1: interlaced top field, 2: interlaced bottom field,
+ 3: progressive frame).
* - __u8
- ``intra_dc_precision``
- Precision of Discrete Cosine transform (0: 8 bits precision,
1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision).
* - __u8
- - ``picture_structure``
- - Picture structure (1: interlaced top field, 2: interlaced bottom field,
- 3: progressive frame).
- * - __u32
- - ``flags``
- - See :ref:`MPEG-2 Picture Flags <mpeg2_picture_flags>`.
+ - ``reserved[5]``
+ - Applications and drivers must set this to zero.
.. _mpeg2_picture_flags:
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst
index cba607f789f0..bbbacbd65d6f 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-compressed.rst
@@ -114,8 +114,9 @@ Compressed Formats
This format is adapted for stateless video decoders that implement a
MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
Metadata associated with the frame to decode is required to be passed
- through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and
- quantisation matrices can optionally be specified through the
+ through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SEQUENCE``,
+ ``V4L2_CID_MPEG_VIDEO_MPEG2_PICTURE``, and ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS``
+ controls. Quantisation matrices can optionally be specified through the
``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTISATION`` control.
See the :ref:`associated Codec Control IDs <v4l2-mpeg-mpeg2>`.
Exactly one output and one capture buffer must be provided for use with
diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
index 4362945fd39b..afc1505a3a7e 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
@@ -429,6 +429,18 @@ See also the examples in :ref:`control`.
- n/a
- A struct :c:type:`v4l2_ctrl_mpeg2_quantisation`, containing MPEG-2
quantisation matrices for stateless video decoders.
+ * - ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``
+ - n/a
+ - n/a
+ - n/a
+ - A struct :c:type:`v4l2_ctrl_mpeg2_sequence`, containing MPEG-2
+ sequence parameters for stateless video decoders.
+ * - ``V4L2_CTRL_TYPE_MPEG2_PICTURE``
+ - n/a
+ - n/a
+ - n/a
+ - A struct :c:type:`v4l2_ctrl_mpeg2_picture`, containing MPEG-2
+ picture parameters for stateless video decoders.
* - ``V4L2_CTRL_TYPE_AREA``
- n/a
- n/a
diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
index 5b2ebaa35d24..928fdc419ee3 100644
--- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions
+++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
@@ -134,6 +134,8 @@ replace symbol V4L2_CTRL_TYPE_STRING :c:type:`v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_U16 :c:type:`v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_U32 :c:type:`v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_U8 :c:type:`v4l2_ctrl_type`
+replace symbol V4L2_CTRL_TYPE_MPEG2_SEQUENCE :c:type:`v4l2_ctrl_type`
+replace symbol V4L2_CTRL_TYPE_MPEG2_PICTURE :c:type:`v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS :c:type:`v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTISATION :c:type:`v4l2_ctrl_type`
replace symbol V4L2_CTRL_TYPE_H264_SPS :c:type:`v4l2_ctrl_type`

Privacy Policy