1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _pixfmt-reserved:
11
12***************************
13Reserved Format Identifiers
14***************************
15
16These formats are not defined by this specification, they are just
17listed for reference and to avoid naming conflicts. If you want to
18register your own format, send an e-mail to the linux-media mailing list
19`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__
20for inclusion in the ``videodev2.h`` file. If you want to share your
21format with other developers add a link to your documentation and send a
22copy to the linux-media mailing list for inclusion in this section. If
23you think your format should be listed in a standard format section
24please make a proposal on the linux-media mailing list.
25
26
27.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
28
29.. _reserved-formats:
30
31.. flat-table:: Reserved Image Formats
32    :header-rows:  1
33    :stub-columns: 0
34    :widths:       3 1 4
35
36    * - Identifier
37      - Code
38      - Details
39    * .. _V4L2-PIX-FMT-DV:
40
41      - ``V4L2_PIX_FMT_DV``
42      - 'dvsd'
43      - unknown
44    * .. _V4L2-PIX-FMT-ET61X251:
45
46      - ``V4L2_PIX_FMT_ET61X251``
47      - 'E625'
48      - Compressed format of the ET61X251 driver.
49    * .. _V4L2-PIX-FMT-HI240:
50
51      - ``V4L2_PIX_FMT_HI240``
52      - 'HI24'
53      - 8 bit RGB format used by the BTTV driver.
54    * .. _V4L2-PIX-FMT-HM12:
55
56      - ``V4L2_PIX_FMT_HM12``
57      - 'HM12'
58      - YUV 4:2:0 format used by the IVTV driver.
59
60	The format is documented in the kernel sources in the file
61	``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst``
62    * .. _V4L2-PIX-FMT-CPIA1:
63
64      - ``V4L2_PIX_FMT_CPIA1``
65      - 'CPIA'
66      - YUV format used by the gspca cpia1 driver.
67    * .. _V4L2-PIX-FMT-JPGL:
68
69      - ``V4L2_PIX_FMT_JPGL``
70      - 'JPGL'
71      - JPEG-Light format (Pegasus Lossless JPEG) used in Divio webcams NW
72	80x.
73    * .. _V4L2-PIX-FMT-SPCA501:
74
75      - ``V4L2_PIX_FMT_SPCA501``
76      - 'S501'
77      - YUYV per line used by the gspca driver.
78    * .. _V4L2-PIX-FMT-SPCA505:
79
80      - ``V4L2_PIX_FMT_SPCA505``
81      - 'S505'
82      - YYUV per line used by the gspca driver.
83    * .. _V4L2-PIX-FMT-SPCA508:
84
85      - ``V4L2_PIX_FMT_SPCA508``
86      - 'S508'
87      - YUVY per line used by the gspca driver.
88    * .. _V4L2-PIX-FMT-SPCA561:
89
90      - ``V4L2_PIX_FMT_SPCA561``
91      - 'S561'
92      - Compressed GBRG Bayer format used by the gspca driver.
93    * .. _V4L2-PIX-FMT-PAC207:
94
95      - ``V4L2_PIX_FMT_PAC207``
96      - 'P207'
97      - Compressed BGGR Bayer format used by the gspca driver.
98    * .. _V4L2-PIX-FMT-MR97310A:
99
100      - ``V4L2_PIX_FMT_MR97310A``
101      - 'M310'
102      - Compressed BGGR Bayer format used by the gspca driver.
103    * .. _V4L2-PIX-FMT-JL2005BCD:
104
105      - ``V4L2_PIX_FMT_JL2005BCD``
106      - 'JL20'
107      - JPEG compressed RGGB Bayer format used by the gspca driver.
108    * .. _V4L2-PIX-FMT-OV511:
109
110      - ``V4L2_PIX_FMT_OV511``
111      - 'O511'
112      - OV511 JPEG format used by the gspca driver.
113    * .. _V4L2-PIX-FMT-OV518:
114
115      - ``V4L2_PIX_FMT_OV518``
116      - 'O518'
117      - OV518 JPEG format used by the gspca driver.
118    * .. _V4L2-PIX-FMT-PJPG:
119
120      - ``V4L2_PIX_FMT_PJPG``
121      - 'PJPG'
122      - Pixart 73xx JPEG format used by the gspca driver.
123    * .. _V4L2-PIX-FMT-SE401:
124
125      - ``V4L2_PIX_FMT_SE401``
126      - 'S401'
127      - Compressed RGB format used by the gspca se401 driver
128    * .. _V4L2-PIX-FMT-SQ905C:
129
130      - ``V4L2_PIX_FMT_SQ905C``
131      - '905C'
132      - Compressed RGGB bayer format used by the gspca driver.
133    * .. _V4L2-PIX-FMT-MJPEG:
134
135      - ``V4L2_PIX_FMT_MJPEG``
136      - 'MJPG'
137      - Compressed format used by the Zoran driver
138    * .. _V4L2-PIX-FMT-PWC1:
139
140      - ``V4L2_PIX_FMT_PWC1``
141      - 'PWC1'
142      - Compressed format of the PWC driver.
143    * .. _V4L2-PIX-FMT-PWC2:
144
145      - ``V4L2_PIX_FMT_PWC2``
146      - 'PWC2'
147      - Compressed format of the PWC driver.
148    * .. _V4L2-PIX-FMT-SN9C10X:
149
150      - ``V4L2_PIX_FMT_SN9C10X``
151      - 'S910'
152      - Compressed format of the SN9C102 driver.
153    * .. _V4L2-PIX-FMT-SN9C20X-I420:
154
155      - ``V4L2_PIX_FMT_SN9C20X_I420``
156      - 'S920'
157      - YUV 4:2:0 format of the gspca sn9c20x driver.
158    * .. _V4L2-PIX-FMT-SN9C2028:
159
160      - ``V4L2_PIX_FMT_SN9C2028``
161      - 'SONX'
162      - Compressed GBRG bayer format of the gspca sn9c2028 driver.
163    * .. _V4L2-PIX-FMT-STV0680:
164
165      - ``V4L2_PIX_FMT_STV0680``
166      - 'S680'
167      - Bayer format of the gspca stv0680 driver.
168    * .. _V4L2-PIX-FMT-WNVA:
169
170      - ``V4L2_PIX_FMT_WNVA``
171      - 'WNVA'
172      - Used by the Winnov Videum driver,
173	`http://www.thedirks.org/winnov/ <http://www.thedirks.org/winnov/>`__
174    * .. _V4L2-PIX-FMT-TM6000:
175
176      - ``V4L2_PIX_FMT_TM6000``
177      - 'TM60'
178      - Used by Trident tm6000
179    * .. _V4L2-PIX-FMT-CIT-YYVYUY:
180
181      - ``V4L2_PIX_FMT_CIT_YYVYUY``
182      - 'CITV'
183      - Used by xirlink CIT, found at IBM webcams.
184
185	Uses one line of Y then 1 line of VYUY
186    * .. _V4L2-PIX-FMT-KONICA420:
187
188      - ``V4L2_PIX_FMT_KONICA420``
189      - 'KONI'
190      - Used by Konica webcams.
191
192	YUV420 planar in blocks of 256 pixels.
193    * .. _V4L2-PIX-FMT-YYUV:
194
195      - ``V4L2_PIX_FMT_YYUV``
196      - 'YYUV'
197      - unknown
198    * .. _V4L2-PIX-FMT-Y4:
199
200      - ``V4L2_PIX_FMT_Y4``
201      - 'Y04 '
202      - Old 4-bit greyscale format. Only the most significant 4 bits of
203	each byte are used, the other bits are set to 0.
204    * .. _V4L2-PIX-FMT-Y6:
205
206      - ``V4L2_PIX_FMT_Y6``
207      - 'Y06 '
208      - Old 6-bit greyscale format. Only the most significant 6 bits of
209	each byte are used, the other bits are set to 0.
210    * .. _V4L2-PIX-FMT-S5C-UYVY-JPG:
211
212      - ``V4L2_PIX_FMT_S5C_UYVY_JPG``
213      - 'S5CI'
214      - Two-planar format used by Samsung S5C73MX cameras. The first plane
215	contains interleaved JPEG and UYVY image data, followed by meta
216	data in form of an array of offsets to the UYVY data blocks. The
217	actual pointer array follows immediately the interleaved JPEG/UYVY
218	data, the number of entries in this array equals the height of the
219	UYVY image. Each entry is a 4-byte unsigned integer in big endian
220	order and it's an offset to a single pixel line of the UYVY image.
221	The first plane can start either with JPEG or UYVY data chunk. The
222	size of a single UYVY block equals the UYVY image's width
223	multiplied by 2. The size of a JPEG chunk depends on the image and
224	can vary with each line.
225
226	The second plane, at an offset of 4084 bytes, contains a 4-byte
227	offset to the pointer array in the first plane. This offset is
228	followed by a 4-byte value indicating size of the pointer array.
229	All numbers in the second plane are also in big endian order.
230	Remaining data in the second plane is undefined. The information
231	in the second plane allows to easily find location of the pointer
232	array, which can be different for each frame. The size of the
233	pointer array is constant for given UYVY image height.
234
235	In order to extract UYVY and JPEG frames an application can
236	initially set a data pointer to the start of first plane and then
237	add an offset from the first entry of the pointers table. Such a
238	pointer indicates start of an UYVY image pixel line. Whole UYVY
239	line can be copied to a separate buffer. These steps should be
240	repeated for each line, i.e. the number of entries in the pointer
241	array. Anything what's in between the UYVY lines is JPEG data and
242	should be concatenated to form the JPEG stream.
243    * .. _V4L2-PIX-FMT-MT21C:
244
245      - ``V4L2_PIX_FMT_MT21C``
246      - 'MT21'
247      - Compressed two-planar YVU420 format used by Mediatek MT8173.
248	The compression is lossless.
249	It is an opaque intermediate format and the MDP hardware must be
250	used to convert ``V4L2_PIX_FMT_MT21C`` to ``V4L2_PIX_FMT_NV12M``,
251	``V4L2_PIX_FMT_YUV420M`` or ``V4L2_PIX_FMT_YVU420``.
252    * .. _V4L2-PIX-FMT-SUNXI-TILED-NV12:
253
254      - ``V4L2_PIX_FMT_SUNXI_TILED_NV12``
255      - 'ST12'
256      - Two-planar NV12-based format used by the video engine found on Allwinner
257	(codenamed sunxi) platforms, with 32x32 tiles for the luminance plane
258	and 32x64 tiles for the chrominance plane. The data in each tile is
259	stored in linear order, within the tile bounds. Each tile follows the
260	previous one linearly in memory (from left to right, top to bottom).
261
262	The associated buffer dimensions are aligned to match an integer number
263	of tiles, resulting in 32-aligned resolutions for the luminance plane
264	and 16-aligned resolutions for the chrominance plane (with 2x2
265	subsampling).
266
267.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
268
269.. _format-flags:
270
271.. flat-table:: Format Flags
272    :header-rows:  0
273    :stub-columns: 0
274    :widths:       3 1 4
275
276    * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA``
277      - 0x00000001
278      - The color values are premultiplied by the alpha channel value. For
279	example, if a light blue pixel with 50% transparency was described
280	by RGBA values (128, 192, 255, 128), the same pixel described with
281	premultiplied colors would be described by RGBA values (64, 96,
282	128, 128)
283