[linux-2.6-block.git] / Documentation / userspace-api / media / v4l / pixfmt-compressed.rst

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

******************
Compressed Formats
******************


.. _compressed-formats:

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|

.. flat-table:: Compressed Image Formats
    :header-rows:  1
    :stub-columns: 0
    :widths:       3 1 4

    * - Identifier
      - Code
      - Details
    * .. _V4L2-PIX-FMT-JPEG:

      - ``V4L2_PIX_FMT_JPEG``
      - 'JPEG'
      - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`,
	:ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`.
    * .. _V4L2-PIX-FMT-MPEG:

      - ``V4L2_PIX_FMT_MPEG``
      - 'MPEG'
      - MPEG multiplexed stream. The actual format is determined by
	extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
	:ref:`mpeg-control-id`.
    * .. _V4L2-PIX-FMT-H264:

      - ``V4L2_PIX_FMT_H264``
      - 'H264'
      - H264 Access Unit.
	The decoder expects one Access Unit per buffer.
	The encoder generates one Access Unit per buffer.
	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	then the decoder has no requirements since it can parse all the
	information from the raw bytestream.
    * .. _V4L2-PIX-FMT-H264-NO-SC:

      - ``V4L2_PIX_FMT_H264_NO_SC``
      - 'AVC1'
      - H264 video elementary stream without start codes.
    * .. _V4L2-PIX-FMT-H264-MVC:

      - ``V4L2_PIX_FMT_H264_MVC``
      - 'M264'
      - H264 MVC video elementary stream.
    * .. _V4L2-PIX-FMT-H264-SLICE:

      - ``V4L2_PIX_FMT_H264_SLICE``
      - 'S264'
      - H264 parsed slice data, including slice headers, either with or
	without the start code, as extracted from the H264 bitstream.
	This format is adapted for stateless video decoders that implement an
	H264 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
	This pixelformat has two modifiers that must be set at least once
	through the ``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE``
        and ``V4L2_CID_MPEG_VIDEO_H264_START_CODE`` controls.
	In addition, metadata associated with the frame to decode are
	required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``,
	``V4L2_CID_MPEG_VIDEO_H264_PPS``,
	``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``,
	``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and
	``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS`` controls.  See the
	:ref:`associated Codec Control IDs <v4l2-mpeg-h264>`.  Exactly
	one output and one capture buffer must be provided for use
	with this pixel format. The output buffer must contain the
	appropriate number of macroblocks to decode a full
	corresponding frame to the matching capture buffer.

	The syntax for this format is documented in :ref:`h264`, section
	7.3.2.8 "Slice layer without partitioning RBSP syntax" and the following
	sections.

	.. note::

	   This format is not yet part of the public kernel API and it
	   is expected to change.

    * .. _V4L2-PIX-FMT-H263:

      - ``V4L2_PIX_FMT_H263``
      - 'H263'
      - H263 video elementary stream.
    * .. _V4L2-PIX-FMT-MPEG1:

      - ``V4L2_PIX_FMT_MPEG1``
      - 'MPG1'
      - MPEG1 Picture. Each buffer starts with a Picture header, followed
	by other headers as needed and ending with the Picture data.
	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	then the decoder has no requirements since it can parse all the
	information from the raw bytestream.
    * .. _V4L2-PIX-FMT-MPEG2:

      - ``V4L2_PIX_FMT_MPEG2``
      - 'MPG2'
      - MPEG2 Picture. Each buffer starts with a Picture header, followed
	by other headers as needed and ending with the Picture data.
	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	then the decoder has no requirements since it can parse all the
	information from the raw bytestream.
    * .. _V4L2-PIX-FMT-MPEG2-SLICE:

      - ``V4L2_PIX_FMT_MPEG2_SLICE``
      - 'MG2S'
      - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
	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
	quantization matrices can optionally be specified through the
	``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION`` control.
	See the :ref:`associated Codec Control IDs <v4l2-mpeg-mpeg2>`.
	Exactly one output and one capture buffer must be provided for use with
	this pixel format. The output buffer must contain the appropriate number
	of macroblocks to decode a full corresponding frame to the matching
	capture buffer.
    * .. _V4L2-PIX-FMT-MPEG4:

      - ``V4L2_PIX_FMT_MPEG4``
      - 'MPG4'
      - MPEG4 video elementary stream.
    * .. _V4L2-PIX-FMT-XVID:

      - ``V4L2_PIX_FMT_XVID``
      - 'XVID'
      - Xvid video elementary stream.
    * .. _V4L2-PIX-FMT-VC1-ANNEX-G:

      - ``V4L2_PIX_FMT_VC1_ANNEX_G``
      - 'VC1G'
      - VC1, SMPTE 421M Annex G compliant stream.
    * .. _V4L2-PIX-FMT-VC1-ANNEX-L:

      - ``V4L2_PIX_FMT_VC1_ANNEX_L``
      - 'VC1L'
      - VC1, SMPTE 421M Annex L compliant stream.
    * .. _V4L2-PIX-FMT-VP8:

      - ``V4L2_PIX_FMT_VP8``
      - 'VP80'
      - VP8 compressed video frame. The encoder generates one
	compressed frame per buffer, and the decoder requires one
	compressed frame per buffer.
    * .. _V4L2-PIX-FMT-VP8-FRAME:

      - ``V4L2_PIX_FMT_VP8_FRAME``
      - 'VP8F'
      - VP8 parsed frame, as extracted from the container.
	This format is adapted for stateless video decoders that implement a
	VP8 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_VP8_FRAME_HEADER`` control.
	See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`.
	Exactly one output and one capture buffer must be provided for use with
	this pixel format. The output buffer must contain the appropriate number
	of macroblocks to decode a full corresponding frame to the matching
	capture buffer.

	.. note::

	   This format is not yet part of the public kernel API and it
	   is expected to change.

    * .. _V4L2-PIX-FMT-VP9:

      - ``V4L2_PIX_FMT_VP9``
      - 'VP90'
      - VP9 compressed video frame. The encoder generates one
	compressed frame per buffer, and the decoder requires one
	compressed frame per buffer.
    * .. _V4L2-PIX-FMT-HEVC:

      - ``V4L2_PIX_FMT_HEVC``
      - 'HEVC'
      - HEVC/H.265 Access Unit.
	The decoder expects one Access Unit per buffer.
	The encoder generates one Access Unit per buffer.
	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	then the decoder has no	requirements since it can parse all the
	information from the raw bytestream.
    * .. _V4L2-PIX-FMT-HEVC-SLICE:

      - ``V4L2_PIX_FMT_HEVC_SLICE``
      - 'S265'
      - HEVC parsed slice data, as extracted from the HEVC bitstream.
	This format is adapted for stateless video decoders that implement a
	HEVC pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
	This pixelformat has two modifiers that must be set at least once
	through the ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE``
        and ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE`` controls.
	Metadata associated with the frame to decode is required to be passed
	through the following controls :
        * ``V4L2_CID_MPEG_VIDEO_HEVC_SPS``
        * ``V4L2_CID_MPEG_VIDEO_HEVC_PPS``
        * ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS``
	See the :ref:`associated Codec Control IDs <v4l2-mpeg-hevc>`.
	Buffers associated with this pixel format must contain the appropriate
	number of macroblocks to decode a full corresponding frame.

	.. note::

	   This format is not yet part of the public kernel API and it
	   is expected to change.
    * .. _V4L2-PIX-FMT-FWHT:

      - ``V4L2_PIX_FMT_FWHT``
      - 'FWHT'
      - Video elementary stream using a codec based on the Fast Walsh Hadamard
        Transform. This codec is implemented by the vicodec ('Virtual Codec')
	driver. See the codec-fwht.h header for more details.
	:ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	since the decoder can parse all the information from the raw bytestream.
    * .. _V4L2-PIX-FMT-FWHT-STATELESS:

      - ``V4L2_PIX_FMT_FWHT_STATELESS``
      - 'SFWH'
      - Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation.
	See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`.
Commit	Line	Data
059b1c5b	1	.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
82559ac0	2
5377d91f MH	3	******************
	4	Compressed Formats
	5	******************
	6
	7
	8	.. _compressed-formats:
	9
5bd4bb78 MCC	10	.. tabularcolumns:: \|p{6.6cm}\|p{2.2cm}\|p{8.7cm}\|
5bd4bb78 MCC	11
5377d91f MH	12	.. flat-table:: Compressed Image Formats
	13	:header-rows: 1
	14	:stub-columns: 0
	15	:widths: 3 1 4
	16
c2b66caf LP	17	* - Identifier
	18	- Code
	19	- Details
	20	* .. _V4L2-PIX-FMT-JPEG:
	21
	22	- ``V4L2_PIX_FMT_JPEG``
	23	- 'JPEG'
	24	- TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`,
	25	:ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`.
	26	* .. _V4L2-PIX-FMT-MPEG:
	27
	28	- ``V4L2_PIX_FMT_MPEG``
	29	- 'MPEG'
	30	- MPEG multiplexed stream. The actual format is determined by
	31	extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
	32	:ref:`mpeg-control-id`.
	33	* .. _V4L2-PIX-FMT-H264:
	34
	35	- ``V4L2_PIX_FMT_H264``
	36	- 'H264'
d4e0f82a HV	37	- H264 Access Unit.
	38	The decoder expects one Access Unit per buffer.
	39	The encoder generates one Access Unit per buffer.
	40	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	41	then the decoder has no requirements since it can parse all the
	42	information from the raw bytestream.
c2b66caf LP	43	* .. _V4L2-PIX-FMT-H264-NO-SC:
	44
	45	- ``V4L2_PIX_FMT_H264_NO_SC``
	46	- 'AVC1'
	47	- H264 video elementary stream without start codes.
	48	* .. _V4L2-PIX-FMT-H264-MVC:
	49
	50	- ``V4L2_PIX_FMT_H264_MVC``
	51	- 'M264'
	52	- H264 MVC video elementary stream.
7bb3c32a	53	* .. _V4L2-PIX-FMT-H264-SLICE:
67e84a98	54
7bb3c32a	55	- ``V4L2_PIX_FMT_H264_SLICE``
67e84a98	56	- 'S264'
8255b4d2 PZ	57	- H264 parsed slice data, including slice headers, either with or
	58	without the start code, as extracted from the H264 bitstream.
	59	This format is adapted for stateless video decoders that implement an
	60	H264 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
8cae93e0 EG	61	This pixelformat has two modifiers that must be set at least once
	62	through the ``V4L2_CID_MPEG_VIDEO_H264_DECODE_MODE``
	63	and ``V4L2_CID_MPEG_VIDEO_H264_START_CODE`` controls.
5604be66 BB	64	In addition, metadata associated with the frame to decode are
5604be66 BB	65	required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``,
67e84a98 MR	66	``V4L2_CID_MPEG_VIDEO_H264_PPS``,
	67	``V4L2_CID_MPEG_VIDEO_H264_SCALING_MATRIX``,
	68	``V4L2_CID_MPEG_VIDEO_H264_SLICE_PARAMS`` and
	69	``V4L2_CID_MPEG_VIDEO_H264_DECODE_PARAMS`` controls. See the
	70	:ref:`associated Codec Control IDs <v4l2-mpeg-h264>`. Exactly
	71	one output and one capture buffer must be provided for use
	72	with this pixel format. The output buffer must contain the
	73	appropriate number of macroblocks to decode a full
	74	corresponding frame to the matching capture buffer.
	75
8255b4d2 PZ	76	The syntax for this format is documented in :ref:`h264`, section
	77	7.3.2.8 "Slice layer without partitioning RBSP syntax" and the following
	78	sections.
	79
67e84a98 MR	80	.. note::
	81
	82	This format is not yet part of the public kernel API and it
	83	is expected to change.
	84
c2b66caf LP	85	* .. _V4L2-PIX-FMT-H263:
	86
	87	- ``V4L2_PIX_FMT_H263``
	88	- 'H263'
	89	- H263 video elementary stream.
	90	* .. _V4L2-PIX-FMT-MPEG1:
	91
	92	- ``V4L2_PIX_FMT_MPEG1``
	93	- 'MPG1'
d4e0f82a HV	94	- MPEG1 Picture. Each buffer starts with a Picture header, followed
	95	by other headers as needed and ending with the Picture data.
	96	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	97	then the decoder has no requirements since it can parse all the
	98	information from the raw bytestream.
c2b66caf LP	99	* .. _V4L2-PIX-FMT-MPEG2:
	100
	101	- ``V4L2_PIX_FMT_MPEG2``
	102	- 'MPG2'
d4e0f82a HV	103	- MPEG2 Picture. Each buffer starts with a Picture header, followed
	104	by other headers as needed and ending with the Picture data.
	105	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	106	then the decoder has no requirements since it can parse all the
	107	information from the raw bytestream.
c27bb30e PK	108	* .. _V4L2-PIX-FMT-MPEG2-SLICE:
	109
	110	- ``V4L2_PIX_FMT_MPEG2_SLICE``
	111	- 'MG2S'
	112	- MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream.
	113	This format is adapted for stateless video decoders that implement a
49179ff4	114	MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
c27bb30e PK	115	Metadata associated with the frame to decode is required to be passed
	116	through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and
	117	quantization matrices can optionally be specified through the
	118	``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION`` control.
	119	See the :ref:`associated Codec Control IDs <v4l2-mpeg-mpeg2>`.
	120	Exactly one output and one capture buffer must be provided for use with
	121	this pixel format. The output buffer must contain the appropriate number
	122	of macroblocks to decode a full corresponding frame to the matching
	123	capture buffer.
c2b66caf LP	124	* .. _V4L2-PIX-FMT-MPEG4:
	125
	126	- ``V4L2_PIX_FMT_MPEG4``
	127	- 'MPG4'
	128	- MPEG4 video elementary stream.
	129	* .. _V4L2-PIX-FMT-XVID:
	130
	131	- ``V4L2_PIX_FMT_XVID``
	132	- 'XVID'
	133	- Xvid video elementary stream.
	134	* .. _V4L2-PIX-FMT-VC1-ANNEX-G:
	135
	136	- ``V4L2_PIX_FMT_VC1_ANNEX_G``
	137	- 'VC1G'
	138	- VC1, SMPTE 421M Annex G compliant stream.
	139	* .. _V4L2-PIX-FMT-VC1-ANNEX-L:
	140
	141	- ``V4L2_PIX_FMT_VC1_ANNEX_L``
	142	- 'VC1L'
	143	- VC1, SMPTE 421M Annex L compliant stream.
	144	* .. _V4L2-PIX-FMT-VP8:
	145
	146	- ``V4L2_PIX_FMT_VP8``
	147	- 'VP80'
d4e0f82a HV	148	- VP8 compressed video frame. The encoder generates one
	149	compressed frame per buffer, and the decoder requires one
	150	compressed frame per buffer.
a57d6aca PO	151	* .. _V4L2-PIX-FMT-VP8-FRAME:
	152
	153	- ``V4L2_PIX_FMT_VP8_FRAME``
	154	- 'VP8F'
	155	- VP8 parsed frame, as extracted from the container.
	156	This format is adapted for stateless video decoders that implement a
	157	VP8 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
	158	Metadata associated with the frame to decode is required to be passed
	159	through the ``V4L2_CID_MPEG_VIDEO_VP8_FRAME_HEADER`` control.
	160	See the :ref:`associated Codec Control IDs <v4l2-mpeg-vp8>`.
	161	Exactly one output and one capture buffer must be provided for use with
	162	this pixel format. The output buffer must contain the appropriate number
	163	of macroblocks to decode a full corresponding frame to the matching
	164	capture buffer.
	165
	166	.. note::
	167
	168	This format is not yet part of the public kernel API and it
	169	is expected to change.
	170
988fcf0c TL	171	* .. _V4L2-PIX-FMT-VP9:
	172
	173	- ``V4L2_PIX_FMT_VP9``
	174	- 'VP90'
d4e0f82a HV	175	- VP9 compressed video frame. The encoder generates one
	176	compressed frame per buffer, and the decoder requires one
	177	compressed frame per buffer.
49f60752 SM	178	* .. _V4L2-PIX-FMT-HEVC:
	179
	180	- ``V4L2_PIX_FMT_HEVC``
	181	- 'HEVC'
d4e0f82a HV	182	- HEVC/H.265 Access Unit.
	183	The decoder expects one Access Unit per buffer.
	184	The encoder generates one Access Unit per buffer.
	185	If :ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
	186	then the decoder has no requirements since it can parse all the
	187	information from the raw bytestream.
de06f289 PK	188	* .. _V4L2-PIX-FMT-HEVC-SLICE:
	189
	190	- ``V4L2_PIX_FMT_HEVC_SLICE``
	191	- 'S265'
	192	- HEVC parsed slice data, as extracted from the HEVC bitstream.
	193	This format is adapted for stateless video decoders that implement a
	194	HEVC pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
	195	This pixelformat has two modifiers that must be set at least once
	196	through the ``V4L2_CID_MPEG_VIDEO_HEVC_DECODE_MODE``
	197	and ``V4L2_CID_MPEG_VIDEO_HEVC_START_CODE`` controls.
	198	Metadata associated with the frame to decode is required to be passed
	199	through the following controls :
	200	* ``V4L2_CID_MPEG_VIDEO_HEVC_SPS``
	201	* ``V4L2_CID_MPEG_VIDEO_HEVC_PPS``
	202	* ``V4L2_CID_MPEG_VIDEO_HEVC_SLICE_PARAMS``
	203	See the :ref:`associated Codec Control IDs <v4l2-mpeg-hevc>`.
	204	Buffers associated with this pixel format must contain the appropriate
	205	number of macroblocks to decode a full corresponding frame.
	206
	207	.. note::
	208
	209	This format is not yet part of the public kernel API and it
	210	is expected to change.
62c3fce0 HV	211	* .. _V4L2-PIX-FMT-FWHT:
	212
	213	- ``V4L2_PIX_FMT_FWHT``
	214	- 'FWHT'
	215	- Video elementary stream using a codec based on the Fast Walsh Hadamard
	216	Transform. This codec is implemented by the vicodec ('Virtual Codec')
21abebf0	217	driver. See the codec-fwht.h header for more details.
d4e0f82a HV	218	:ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
d4e0f82a HV	219	since the decoder can parse all the information from the raw bytestream.
ee3963c4 DH	220	* .. _V4L2-PIX-FMT-FWHT-STATELESS:
	221
	222	- ``V4L2_PIX_FMT_FWHT_STATELESS``
	223	- 'SFWH'
	224	- Same format as V4L2_PIX_FMT_FWHT but requires stateless codec implementation.
	225	See the :ref:`associated Codec Control IDs <v4l2-mpeg-fwht>`.