[linux-block.git] / Documentation / media / uapi / v4l / pixfmt-reserved.rst

.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/media/uapi/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections

.. _pixfmt-reserved:

***************************
Reserved Format Identifiers
***************************

These formats are not defined by this specification, they are just
listed for reference and to avoid naming conflicts. If you want to
register your own format, send an e-mail to the linux-media mailing list
`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__
for inclusion in the ``videodev2.h`` file. If you want to share your
format with other developers add a link to your documentation and send a
copy to the linux-media mailing list for inclusion in this section. If
you think your format should be listed in a standard format section
please make a proposal on the linux-media mailing list.


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

.. _reserved-formats:

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

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

      - ``V4L2_PIX_FMT_DV``
      - 'dvsd'
      - unknown
    * .. _V4L2-PIX-FMT-ET61X251:

      - ``V4L2_PIX_FMT_ET61X251``
      - 'E625'
      - Compressed format of the ET61X251 driver.
    * .. _V4L2-PIX-FMT-HI240:

      - ``V4L2_PIX_FMT_HI240``
      - 'HI24'
      - 8 bit RGB format used by the BTTV driver.
    * .. _V4L2-PIX-FMT-HM12:

      - ``V4L2_PIX_FMT_HM12``
      - 'HM12'
      - YUV 4:2:0 format used by the IVTV driver.

	The format is documented in the kernel sources in the file
	``Documentation/media/v4l-drivers/cx2341x.rst``
    * .. _V4L2-PIX-FMT-CPIA1:

      - ``V4L2_PIX_FMT_CPIA1``
      - 'CPIA'
      - YUV format used by the gspca cpia1 driver.
    * .. _V4L2-PIX-FMT-JPGL:

      - ``V4L2_PIX_FMT_JPGL``
      - 'JPGL'
      - JPEG-Light format (Pegasus Lossless JPEG) used in Divio webcams NW
	80x.
    * .. _V4L2-PIX-FMT-SPCA501:

      - ``V4L2_PIX_FMT_SPCA501``
      - 'S501'
      - YUYV per line used by the gspca driver.
    * .. _V4L2-PIX-FMT-SPCA505:

      - ``V4L2_PIX_FMT_SPCA505``
      - 'S505'
      - YYUV per line used by the gspca driver.
    * .. _V4L2-PIX-FMT-SPCA508:

      - ``V4L2_PIX_FMT_SPCA508``
      - 'S508'
      - YUVY per line used by the gspca driver.
    * .. _V4L2-PIX-FMT-SPCA561:

      - ``V4L2_PIX_FMT_SPCA561``
      - 'S561'
      - Compressed GBRG Bayer format used by the gspca driver.
    * .. _V4L2-PIX-FMT-PAC207:

      - ``V4L2_PIX_FMT_PAC207``
      - 'P207'
      - Compressed BGGR Bayer format used by the gspca driver.
    * .. _V4L2-PIX-FMT-MR97310A:

      - ``V4L2_PIX_FMT_MR97310A``
      - 'M310'
      - Compressed BGGR Bayer format used by the gspca driver.
    * .. _V4L2-PIX-FMT-JL2005BCD:

      - ``V4L2_PIX_FMT_JL2005BCD``
      - 'JL20'
      - JPEG compressed RGGB Bayer format used by the gspca driver.
    * .. _V4L2-PIX-FMT-OV511:

      - ``V4L2_PIX_FMT_OV511``
      - 'O511'
      - OV511 JPEG format used by the gspca driver.
    * .. _V4L2-PIX-FMT-OV518:

      - ``V4L2_PIX_FMT_OV518``
      - 'O518'
      - OV518 JPEG format used by the gspca driver.
    * .. _V4L2-PIX-FMT-PJPG:

      - ``V4L2_PIX_FMT_PJPG``
      - 'PJPG'
      - Pixart 73xx JPEG format used by the gspca driver.
    * .. _V4L2-PIX-FMT-SE401:

      - ``V4L2_PIX_FMT_SE401``
      - 'S401'
      - Compressed RGB format used by the gspca se401 driver
    * .. _V4L2-PIX-FMT-SQ905C:

      - ``V4L2_PIX_FMT_SQ905C``
      - '905C'
      - Compressed RGGB bayer format used by the gspca driver.
    * .. _V4L2-PIX-FMT-MJPEG:

      - ``V4L2_PIX_FMT_MJPEG``
      - 'MJPG'
      - Compressed format used by the Zoran driver
    * .. _V4L2-PIX-FMT-PWC1:

      - ``V4L2_PIX_FMT_PWC1``
      - 'PWC1'
      - Compressed format of the PWC driver.
    * .. _V4L2-PIX-FMT-PWC2:

      - ``V4L2_PIX_FMT_PWC2``
      - 'PWC2'
      - Compressed format of the PWC driver.
    * .. _V4L2-PIX-FMT-SN9C10X:

      - ``V4L2_PIX_FMT_SN9C10X``
      - 'S910'
      - Compressed format of the SN9C102 driver.
    * .. _V4L2-PIX-FMT-SN9C20X-I420:

      - ``V4L2_PIX_FMT_SN9C20X_I420``
      - 'S920'
      - YUV 4:2:0 format of the gspca sn9c20x driver.
    * .. _V4L2-PIX-FMT-SN9C2028:

      - ``V4L2_PIX_FMT_SN9C2028``
      - 'SONX'
      - Compressed GBRG bayer format of the gspca sn9c2028 driver.
    * .. _V4L2-PIX-FMT-STV0680:

      - ``V4L2_PIX_FMT_STV0680``
      - 'S680'
      - Bayer format of the gspca stv0680 driver.
    * .. _V4L2-PIX-FMT-WNVA:

      - ``V4L2_PIX_FMT_WNVA``
      - 'WNVA'
      - Used by the Winnov Videum driver,
	`http://www.thedirks.org/winnov/ <http://www.thedirks.org/winnov/>`__
    * .. _V4L2-PIX-FMT-TM6000:

      - ``V4L2_PIX_FMT_TM6000``
      - 'TM60'
      - Used by Trident tm6000
    * .. _V4L2-PIX-FMT-CIT-YYVYUY:

      - ``V4L2_PIX_FMT_CIT_YYVYUY``
      - 'CITV'
      - Used by xirlink CIT, found at IBM webcams.

	Uses one line of Y then 1 line of VYUY
    * .. _V4L2-PIX-FMT-KONICA420:

      - ``V4L2_PIX_FMT_KONICA420``
      - 'KONI'
      - Used by Konica webcams.

	YUV420 planar in blocks of 256 pixels.
    * .. _V4L2-PIX-FMT-YYUV:

      - ``V4L2_PIX_FMT_YYUV``
      - 'YYUV'
      - unknown
    * .. _V4L2-PIX-FMT-Y4:

      - ``V4L2_PIX_FMT_Y4``
      - 'Y04 '
      - Old 4-bit greyscale format. Only the most significant 4 bits of
	each byte are used, the other bits are set to 0.
    * .. _V4L2-PIX-FMT-Y6:

      - ``V4L2_PIX_FMT_Y6``
      - 'Y06 '
      - Old 6-bit greyscale format. Only the most significant 6 bits of
	each byte are used, the other bits are set to 0.
    * .. _V4L2-PIX-FMT-S5C-UYVY-JPG:

      - ``V4L2_PIX_FMT_S5C_UYVY_JPG``
      - 'S5CI'
      - Two-planar format used by Samsung S5C73MX cameras. The first plane
	contains interleaved JPEG and UYVY image data, followed by meta
	data in form of an array of offsets to the UYVY data blocks. The
	actual pointer array follows immediately the interleaved JPEG/UYVY
	data, the number of entries in this array equals the height of the
	UYVY image. Each entry is a 4-byte unsigned integer in big endian
	order and it's an offset to a single pixel line of the UYVY image.
	The first plane can start either with JPEG or UYVY data chunk. The
	size of a single UYVY block equals the UYVY image's width
	multiplied by 2. The size of a JPEG chunk depends on the image and
	can vary with each line.

	The second plane, at an offset of 4084 bytes, contains a 4-byte
	offset to the pointer array in the first plane. This offset is
	followed by a 4-byte value indicating size of the pointer array.
	All numbers in the second plane are also in big endian order.
	Remaining data in the second plane is undefined. The information
	in the second plane allows to easily find location of the pointer
	array, which can be different for each frame. The size of the
	pointer array is constant for given UYVY image height.

	In order to extract UYVY and JPEG frames an application can
	initially set a data pointer to the start of first plane and then
	add an offset from the first entry of the pointers table. Such a
	pointer indicates start of an UYVY image pixel line. Whole UYVY
	line can be copied to a separate buffer. These steps should be
	repeated for each line, i.e. the number of entries in the pointer
	array. Anything what's in between the UYVY lines is JPEG data and
	should be concatenated to form the JPEG stream.
    * .. _V4L2-PIX-FMT-MT21C:

      - ``V4L2_PIX_FMT_MT21C``
      - 'MT21'
      - Compressed two-planar YVU420 format used by Mediatek MT8173.
	The compression is lossless.
	It is an opaque intermediate format and the MDP hardware must be
	used to convert ``V4L2_PIX_FMT_MT21C`` to ``V4L2_PIX_FMT_NV12M``,
	``V4L2_PIX_FMT_YUV420M`` or ``V4L2_PIX_FMT_YVU420``.
    * .. _V4L2-PIX-FMT-SUNXI-TILED-NV12:

      - ``V4L2_PIX_FMT_SUNXI_TILED_NV12``
      - 'ST12'
      - Two-planar NV12-based format used by the video engine found on Allwinner
	(codenamed sunxi) platforms, with 32x32 tiles for the luminance plane
	and 32x64 tiles for the chrominance plane. The data in each tile is
	stored in linear order, within the tile bounds. Each tile follows the
	previous one linearly in memory (from left to right, top to bottom).

	The associated buffer dimensions are aligned to match an integer number
	of tiles, resulting in 32-aligned resolutions for the luminance plane
	and 16-aligned resolutions for the chrominance plane (with 2x2
	subsampling).

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

.. _format-flags:

.. flat-table:: Format Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA``
      - 0x00000001
      - The color values are premultiplied by the alpha channel value. For
	example, if a light blue pixel with 50% transparency was described
	by RGBA values (128, 192, 255, 128), the same pixel described with
	premultiplied colors would be described by RGBA values (64, 96,
	128, 128)
Commit	Line	Data
82559ac0 MCC	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/media/uapi/fdl-appendix.rst.
	7	..
	8	.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
	9
5377d91f MH	10	.. _pixfmt-reserved:
	11
	12	***************************
	13	Reserved Format Identifiers
	14	***************************
	15
	16	These formats are not defined by this specification, they are just
	17	listed for reference and to avoid naming conflicts. If you want to
	18	register your own format, send an e-mail to the linux-media mailing list
	19	`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__
	20	for inclusion in the ``videodev2.h`` file. If you want to share your
	21	format with other developers add a link to your documentation and send a
	22	copy to the linux-media mailing list for inclusion in this section. If
	23	you think your format should be listed in a standard format section
	24	please make a proposal on the linux-media mailing list.
	25
	26
5bd4bb78 MCC	27	.. tabularcolumns:: \|p{6.6cm}\|p{2.2cm}\|p{8.7cm}\|
5bd4bb78 MCC	28
fa92b04d MCC	29	.. _reserved-formats:
fa92b04d MCC	30
5377d91f MH	31	.. flat-table:: Reserved Image Formats
	32	:header-rows: 1
	33	:stub-columns: 0
	34	:widths: 3 1 4
	35
c2b66caf LP	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'
55f240a2	58	- YUV 4:2:0 format used by the IVTV driver.
c2b66caf LP	59
c2b66caf LP	60	The format is documented in the kernel sources in the file
a405ed85	61	``Documentation/media/v4l-drivers/cx2341x.rst``
c2b66caf LP	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.
a38b7ce9 TL	243	* .. _V4L2-PIX-FMT-MT21C:
	244
	245	- ``V4L2_PIX_FMT_MT21C``
a0345caf	246	- 'MT21'
a38b7ce9	247	- Compressed two-planar YVU420 format used by Mediatek MT8173.
a0345caf HV	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``.
36cf35b7 PK	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).
5377d91f	266
5bd4bb78 MCC	267	.. tabularcolumns:: \|p{6.6cm}\|p{2.2cm}\|p{8.7cm}\|
5bd4bb78 MCC	268
fa92b04d MCC	269	.. _format-flags:
fa92b04d MCC	270
5377d91f MH	271	.. flat-table:: Format Flags
	272	:header-rows: 0
	273	:stub-columns: 0
	274	:widths: 3 1 4
	275
c2b66caf LP	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)