1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 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
2 9
3 ****************************** 10 ******************************
4 Single-planar format structure 11 Single-planar format structure
5 ****************************** 12 ******************************
6 13
7 .. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7c !! 14 .. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}|
8 15
9 .. c:type:: v4l2_pix_format 16 .. c:type:: v4l2_pix_format
10 17
11 .. cssclass:: longtable 18 .. cssclass:: longtable
12 19
13 .. flat-table:: struct v4l2_pix_format 20 .. flat-table:: struct v4l2_pix_format
14 :header-rows: 0 21 :header-rows: 0
15 :stub-columns: 0 22 :stub-columns: 0
16 :widths: 1 1 2 23 :widths: 1 1 2
17 24
18 * - __u32 25 * - __u32
19 - ``width`` 26 - ``width``
20 - Image width in pixels. 27 - Image width in pixels.
21 * - __u32 28 * - __u32
22 - ``height`` 29 - ``height``
23 - Image height in pixels. If ``field`` i 30 - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
24 ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ 31 ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
25 refers to the number of lines in the f 32 refers to the number of lines in the field, otherwise it refers to
26 the number of lines in the frame (whic 33 the number of lines in the frame (which is twice the field height
27 for interlaced formats). 34 for interlaced formats).
28 * - :cspan:`2` Applications set these fiel 35 * - :cspan:`2` Applications set these fields to request an image
29 size, drivers return the closest possi 36 size, drivers return the closest possible values. In case of
30 planar formats the ``width`` and ``hei 37 planar formats the ``width`` and ``height`` applies to the largest
31 plane. To avoid ambiguities drivers mu 38 plane. To avoid ambiguities drivers must return values rounded up
32 to a multiple of the scale factor of a 39 to a multiple of the scale factor of any smaller planes. For
33 example when the image format is YUV 4 40 example when the image format is YUV 4:2:0, ``width`` and
34 ``height`` must be multiples of two. 41 ``height`` must be multiples of two.
35 42
36 For compressed formats that contain th 43 For compressed formats that contain the resolution information encoded
37 inside the stream, when fed to a state 44 inside the stream, when fed to a stateful mem2mem decoder, the fields
38 may be zero to rely on the decoder to 45 may be zero to rely on the decoder to detect the right values. For more
39 details see :ref:`decoder` and format 46 details see :ref:`decoder` and format descriptions.
40 47
41 For compressed formats on the CAPTURE 48 For compressed formats on the CAPTURE side of a stateful mem2mem
42 encoder, the fields must be zero, sinc 49 encoder, the fields must be zero, since the coded size is expected to
43 be calculated internally by the encode 50 be calculated internally by the encoder itself, based on the OUTPUT
44 side. For more details see :ref:`encod 51 side. For more details see :ref:`encoder` and format descriptions.
45 * - __u32 52 * - __u32
46 - ``pixelformat`` 53 - ``pixelformat``
47 - The pixel format or type of compressio 54 - The pixel format or type of compression, set by the application.
48 This is a little endian 55 This is a little endian
49 :ref:`four character code <v4l2-fourcc 56 :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
50 RGB formats in :ref:`pixfmt-rgb`, YUV 57 RGB formats in :ref:`pixfmt-rgb`, YUV formats in
51 :ref:`yuv-formats`, and reserved codes 58 :ref:`yuv-formats`, and reserved codes in
52 :ref:`reserved-formats` 59 :ref:`reserved-formats`
53 * - __u32 60 * - __u32
54 - ``field`` 61 - ``field``
55 - Field order, from enum :c:type:`v4l2_f 62 - Field order, from enum :c:type:`v4l2_field`.
56 Video images are typically interlaced. 63 Video images are typically interlaced. Applications can request to
57 capture or output only the top or bott 64 capture or output only the top or bottom field, or both fields
58 interlaced or sequentially stored in o 65 interlaced or sequentially stored in one buffer or alternating in
59 separate buffers. Drivers return the a 66 separate buffers. Drivers return the actual field order selected.
60 For more details on fields see :ref:`f 67 For more details on fields see :ref:`field-order`.
61 * - __u32 68 * - __u32
62 - ``bytesperline`` 69 - ``bytesperline``
63 - Distance in bytes between the leftmost 70 - Distance in bytes between the leftmost pixels in two adjacent
64 lines. 71 lines.
65 * - :cspan:`2` 72 * - :cspan:`2`
66 73
67 Both applications and drivers can set 74 Both applications and drivers can set this field to request
68 padding bytes at the end of each line. 75 padding bytes at the end of each line. Drivers however may ignore
69 the value requested by the application 76 the value requested by the application, returning ``width`` times
70 bytes per pixel or a larger value requ 77 bytes per pixel or a larger value required by the hardware. That
71 implies applications can just set this 78 implies applications can just set this field to zero to get a
72 reasonable default. 79 reasonable default.
73 80
74 Video hardware may access padding byte 81 Video hardware may access padding bytes, therefore they must
75 reside in accessible memory. Consider 82 reside in accessible memory. Consider cases where padding bytes
76 after the last line of an image cross 83 after the last line of an image cross a system page boundary.
77 Input devices may write padding bytes, 84 Input devices may write padding bytes, the value is undefined.
78 Output devices ignore the contents of 85 Output devices ignore the contents of padding bytes.
79 86
80 When the image format is planar the `` 87 When the image format is planar the ``bytesperline`` value applies
81 to the first plane and is divided by t 88 to the first plane and is divided by the same factor as the
82 ``width`` field for the other planes. 89 ``width`` field for the other planes. For example the Cb and Cr
83 planes of a YUV 4:2:0 image have half 90 planes of a YUV 4:2:0 image have half as many padding bytes
84 following each line as the Y plane. To 91 following each line as the Y plane. To avoid ambiguities drivers
85 must return a ``bytesperline`` value r 92 must return a ``bytesperline`` value rounded up to a multiple of
86 the scale factor. 93 the scale factor.
87 94
88 For compressed formats the ``bytesperl 95 For compressed formats the ``bytesperline`` value makes no sense.
89 Applications and drivers must set this 96 Applications and drivers must set this to 0 in that case.
90 * - __u32 97 * - __u32
91 - ``sizeimage`` 98 - ``sizeimage``
92 - Size in bytes of the buffer to hold a 99 - Size in bytes of the buffer to hold a complete image, set by the
93 driver. Usually this is ``bytesperline 100 driver. Usually this is ``bytesperline`` times ``height``. When
94 the image consists of variable length 101 the image consists of variable length compressed data this is the
95 number of bytes required by the codec 102 number of bytes required by the codec to support the worst-case
96 compression scenario. 103 compression scenario.
97 104
98 The driver will set the value for unco 105 The driver will set the value for uncompressed images.
99 106
100 Clients are allowed to set the sizeima 107 Clients are allowed to set the sizeimage field for variable length
101 compressed data flagged with ``V4L2_FM 108 compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at
102 :ref:`VIDIOC_ENUM_FMT`, but the driver 109 :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the
103 value itself, or it may modify the pro 110 value itself, or it may modify the provided value based on
104 alignment requirements or minimum/maxi 111 alignment requirements or minimum/maximum size requirements.
105 If the client wants to leave this to t 112 If the client wants to leave this to the driver, then it should
106 set sizeimage to 0. 113 set sizeimage to 0.
107 * - __u32 114 * - __u32
108 - ``colorspace`` 115 - ``colorspace``
109 - Image colorspace, from enum :c:type:`v 116 - Image colorspace, from enum :c:type:`v4l2_colorspace`.
110 This information supplements the ``pix 117 This information supplements the ``pixelformat`` and must be set
111 by the driver for capture streams and 118 by the driver for capture streams and by the application for
112 output streams, see :ref:`colorspaces` !! 119 output streams, see :ref:`colorspaces`.
113 flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` the <<
114 this field for a capture stream to req <<
115 for the captured image data. If the dr <<
116 conversion, it will return another sup <<
117 The driver indicates that colorspace c <<
118 the flag V4L2_FMT_FLAG_CSC_COLORSPACE <<
119 :c:type:`v4l2_fmtdesc` during enumerat <<
120 * - __u32 120 * - __u32
121 - ``priv`` 121 - ``priv``
122 - This field indicates whether the remai 122 - This field indicates whether the remaining fields of the
123 struct :c:type:`v4l2_pix_format`, also 123 struct :c:type:`v4l2_pix_format`, also called the
124 extended fields, are valid. When set t 124 extended fields, are valid. When set to
125 ``V4L2_PIX_FMT_PRIV_MAGIC``, it indica 125 ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
126 have been correctly initialized. When 126 have been correctly initialized. When set to any other value it
127 indicates that the extended fields con 127 indicates that the extended fields contain undefined values.
128 128
129 Applications that wish to use the pixe 129 Applications that wish to use the pixel format extended fields
130 must first ensure that the feature is 130 must first ensure that the feature is supported by querying the
131 device for the :ref:`V4L2_CAP_EXT_PIX_ 131 device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
132 capability. If the capability isn't se 132 capability. If the capability isn't set the pixel format extended
133 fields are not supported and using the 133 fields are not supported and using the extended fields will lead
134 to undefined results. 134 to undefined results.
135 135
136 To use the extended fields, applicatio 136 To use the extended fields, applications must set the ``priv``
137 field to ``V4L2_PIX_FMT_PRIV_MAGIC``, 137 field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
138 fields and zero the unused bytes of th 138 fields and zero the unused bytes of the
139 struct :c:type:`v4l2_format` ``raw_dat 139 struct :c:type:`v4l2_format` ``raw_data`` field.
140 140
141 When the ``priv`` field isn't set to ` 141 When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
142 drivers must act as if all the extende 142 drivers must act as if all the extended fields were set to zero.
143 On return drivers must set the ``priv` 143 On return drivers must set the ``priv`` field to
144 ``V4L2_PIX_FMT_PRIV_MAGIC`` and all th 144 ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
145 applicable values. 145 applicable values.
146 * - __u32 146 * - __u32
147 - ``flags`` 147 - ``flags``
148 - Flags set by the application or driver 148 - Flags set by the application or driver, see :ref:`format-flags`.
149 * - union { 149 * - union {
150 - (anonymous) 150 - (anonymous)
151 * - __u32 151 * - __u32
152 - ``ycbcr_enc`` 152 - ``ycbcr_enc``
153 - Y'CbCr encoding, from enum :c:type:`v4 153 - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
154 This information supplements the ``col 154 This information supplements the ``colorspace`` and must be set by
155 the driver for capture streams and by 155 the driver for capture streams and by the application for output
156 streams, see :ref:`colorspaces`. If th !! 156 streams, see :ref:`colorspaces`.
157 flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` the <<
158 this field for a capture stream to req <<
159 for the captured image data. If the dr <<
160 conversion, it will return another sup <<
161 This field is ignored for HSV pixelfor <<
162 ycbcr_enc conversion is supported by s <<
163 V4L2_FMT_FLAG_CSC_YCBCR_ENC in the cor <<
164 :c:type:`v4l2_fmtdesc` during enumerat <<
165 * - __u32 157 * - __u32
166 - ``hsv_enc`` 158 - ``hsv_enc``
167 - HSV encoding, from enum :c:type:`v4l2_ 159 - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
168 This information supplements the ``col 160 This information supplements the ``colorspace`` and must be set by
169 the driver for capture streams and by 161 the driver for capture streams and by the application for output
170 streams, see :ref:`colorspaces`. If th !! 162 streams, see :ref:`colorspaces`.
171 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the <<
172 field for a capture stream to request <<
173 captured image data. If the driver can <<
174 conversion, it will return another sup <<
175 This field is ignored for non-HSV pixe <<
176 that hsv_enc conversion is supported b <<
177 V4L2_FMT_FLAG_CSC_HSV_ENC in the corre <<
178 :c:type:`v4l2_fmtdesc` during enumerat <<
179 * - } 163 * - }
180 - 164 -
181 * - __u32 165 * - __u32
182 - ``quantization`` 166 - ``quantization``
183 - Quantization range, from enum :c:type: 167 - Quantization range, from enum :c:type:`v4l2_quantization`.
184 This information supplements the ``col 168 This information supplements the ``colorspace`` and must be set by
185 the driver for capture streams and by 169 the driver for capture streams and by the application for output
186 streams, see :ref:`colorspaces`. If th !! 170 streams, see :ref:`colorspaces`.
187 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the <<
188 this field for a capture stream to req <<
189 range for the captured image data. If <<
190 conversion, it will return another sup <<
191 The driver indicates that quantization <<
192 the flag V4L2_FMT_FLAG_CSC_QUANTIZATIO <<
193 :c:type:`v4l2_fmtdesc` during enumerat <<
194 * - __u32 171 * - __u32
195 - ``xfer_func`` 172 - ``xfer_func``
196 - Transfer function, from enum :c:type:` 173 - Transfer function, from enum :c:type:`v4l2_xfer_func`.
197 This information supplements the ``col 174 This information supplements the ``colorspace`` and must be set by
198 the driver for capture streams and by 175 the driver for capture streams and by the application for output
199 streams, see :ref:`colorspaces`. If th !! 176 streams, see :ref:`colorspaces`.
200 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the <<
201 this field for a capture stream to req <<
202 for the captured image data. If the dr <<
203 conversion, it will return another sup <<
204 The driver indicates that xfer_func co <<
205 the flag V4L2_FMT_FLAG_CSC_XFER_FUNC i <<
206 :c:type:`v4l2_fmtdesc` during enumerat <<
207 <<
208 .. tabularcolumns:: |p{6.8cm}|p{2.3cm}|p{8.2cm <<
209 <<
210 .. _format-flags: <<
211 <<
212 .. flat-table:: Format Flags <<
213 :header-rows: 0 <<
214 :stub-columns: 0 <<
215 :widths: 3 1 4 <<
216 <<
217 * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA`` <<
218 - 0x00000001 <<
219 - The color values are premultiplied by <<
220 example, if a light blue pixel with 50 <<
221 by RGBA values (128, 192, 255, 128), t <<
222 premultiplied colors would be describe <<
223 128, 128) <<
224 * .. _`v4l2-pix-fmt-flag-set-csc`: <<
225 <<
226 - ``V4L2_PIX_FMT_FLAG_SET_CSC`` <<
227 - 0x00000002 <<
228 - Set by the application. It is only use <<
229 ignored for output streams. If set, th <<
230 colorspace conversion from the receive <<
231 colorspace values. If the colorimetry <<
232 ``ycbcr_enc``, ``hsv_enc`` or ``quanti <<
233 then that colorimetry setting will rem <<
234 So in order to change the quantization <<
235 be set to non default value (``V4L2_QU <<
236 ``V4L2_QUANTIZATION_LIM_RANGE``) and a <<
237 be set to ``*_DEFAULT``. <<
238 <<
239 To check which conversions are support <<
240 pixel format, see :ref:`fmtdesc-flags` <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.