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