1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3******************
4Compressed Formats
5******************
6
7
8.. _compressed-formats:
9
10.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
11
12.. flat-table:: Compressed Image Formats
13    :header-rows:  1
14    :stub-columns: 0
15    :widths:       3 1 4
16
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'
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.
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.
53    * .. _V4L2-PIX-FMT-H264-SLICE:
54
55      - ``V4L2_PIX_FMT_H264_SLICE``
56      - 'S264'
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`).
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.
64	In addition, metadata associated with the frame to decode are
65	required to be passed through the ``V4L2_CID_MPEG_VIDEO_H264_SPS``,
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
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
80	.. note::
81
82	   This format is not yet part of the public kernel API and it
83	   is expected to change.
84
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'
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.
99    * .. _V4L2-PIX-FMT-MPEG2:
100
101      - ``V4L2_PIX_FMT_MPEG2``
102      - 'MPG2'
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.
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
114	MPEG-2 pipeline (using the :ref:`mem2mem` and :ref:`media-request-api`).
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.
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'
148      - VP8 compressed video frame. The encoder generates one
149	compressed frame per buffer, and the decoder requires one
150	compressed frame per buffer.
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
171    * .. _V4L2-PIX-FMT-VP9:
172
173      - ``V4L2_PIX_FMT_VP9``
174      - 'VP90'
175      - VP9 compressed video frame. The encoder generates one
176	compressed frame per buffer, and the decoder requires one
177	compressed frame per buffer.
178    * .. _V4L2-PIX-FMT-HEVC:
179
180      - ``V4L2_PIX_FMT_HEVC``
181      - 'HEVC'
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.
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.
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')
217	driver. See the codec-fwht.h header for more details.
218	:ref:`VIDIOC_ENUM_FMT` reports ``V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM``
219	since the decoder can parse all the information from the raw bytestream.
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>`.
226