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 <<
41 For compressed formats on the CAPTURE <<
42 encoder, the fields must be zero, sinc <<
43 be calculated internally by the encode <<
44 side. For more details see :ref:`encod <<
45 * - __u32 47 * - __u32
46 - ``pixelformat`` 48 - ``pixelformat``
47 - The pixel format or type of compressio 49 - The pixel format or type of compression, set by the application.
48 This is a little endian 50 This is a little endian
49 :ref:`four character code <v4l2-fourcc 51 :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
50 RGB formats in :ref:`pixfmt-rgb`, YUV 52 RGB formats in :ref:`pixfmt-rgb`, YUV formats in
51 :ref:`yuv-formats`, and reserved codes 53 :ref:`yuv-formats`, and reserved codes in
52 :ref:`reserved-formats` 54 :ref:`reserved-formats`
53 * - __u32 55 * - __u32
54 - ``field`` 56 - ``field``
55 - Field order, from enum :c:type:`v4l2_f 57 - Field order, from enum :c:type:`v4l2_field`.
56 Video images are typically interlaced. 58 Video images are typically interlaced. Applications can request to
57 capture or output only the top or bott 59 capture or output only the top or bottom field, or both fields
58 interlaced or sequentially stored in o 60 interlaced or sequentially stored in one buffer or alternating in
59 separate buffers. Drivers return the a 61 separate buffers. Drivers return the actual field order selected.
60 For more details on fields see :ref:`f 62 For more details on fields see :ref:`field-order`.
61 * - __u32 63 * - __u32
62 - ``bytesperline`` 64 - ``bytesperline``
63 - Distance in bytes between the leftmost 65 - Distance in bytes between the leftmost pixels in two adjacent
64 lines. 66 lines.
65 * - :cspan:`2` 67 * - :cspan:`2`
66 68
67 Both applications and drivers can set 69 Both applications and drivers can set this field to request
68 padding bytes at the end of each line. 70 padding bytes at the end of each line. Drivers however may ignore
69 the value requested by the application 71 the value requested by the application, returning ``width`` times
70 bytes per pixel or a larger value requ 72 bytes per pixel or a larger value required by the hardware. That
71 implies applications can just set this 73 implies applications can just set this field to zero to get a
72 reasonable default. 74 reasonable default.
73 75
74 Video hardware may access padding byte 76 Video hardware may access padding bytes, therefore they must
75 reside in accessible memory. Consider 77 reside in accessible memory. Consider cases where padding bytes
76 after the last line of an image cross 78 after the last line of an image cross a system page boundary.
77 Input devices may write padding bytes, 79 Input devices may write padding bytes, the value is undefined.
78 Output devices ignore the contents of 80 Output devices ignore the contents of padding bytes.
79 81
80 When the image format is planar the `` 82 When the image format is planar the ``bytesperline`` value applies
81 to the first plane and is divided by t 83 to the first plane and is divided by the same factor as the
82 ``width`` field for the other planes. 84 ``width`` field for the other planes. For example the Cb and Cr
83 planes of a YUV 4:2:0 image have half 85 planes of a YUV 4:2:0 image have half as many padding bytes
84 following each line as the Y plane. To 86 following each line as the Y plane. To avoid ambiguities drivers
85 must return a ``bytesperline`` value r 87 must return a ``bytesperline`` value rounded up to a multiple of
86 the scale factor. 88 the scale factor.
87 89
88 For compressed formats the ``bytesperl 90 For compressed formats the ``bytesperline`` value makes no sense.
89 Applications and drivers must set this 91 Applications and drivers must set this to 0 in that case.
90 * - __u32 92 * - __u32
91 - ``sizeimage`` 93 - ``sizeimage``
92 - Size in bytes of the buffer to hold a 94 - Size in bytes of the buffer to hold a complete image, set by the
93 driver. Usually this is ``bytesperline 95 driver. Usually this is ``bytesperline`` times ``height``. When
94 the image consists of variable length 96 the image consists of variable length compressed data this is the
95 number of bytes required by the codec 97 number of bytes required by the codec to support the worst-case
96 compression scenario. 98 compression scenario.
97 99
98 The driver will set the value for unco 100 The driver will set the value for uncompressed images.
99 101
100 Clients are allowed to set the sizeima 102 Clients are allowed to set the sizeimage field for variable length
101 compressed data flagged with ``V4L2_FM 103 compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at
102 :ref:`VIDIOC_ENUM_FMT`, but the driver 104 :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the
103 value itself, or it may modify the pro 105 value itself, or it may modify the provided value based on
104 alignment requirements or minimum/maxi 106 alignment requirements or minimum/maximum size requirements.
105 If the client wants to leave this to t 107 If the client wants to leave this to the driver, then it should
106 set sizeimage to 0. 108 set sizeimage to 0.
107 * - __u32 109 * - __u32
108 - ``colorspace`` 110 - ``colorspace``
109 - Image colorspace, from enum :c:type:`v 111 - Image colorspace, from enum :c:type:`v4l2_colorspace`.
110 This information supplements the ``pix 112 This information supplements the ``pixelformat`` and must be set
111 by the driver for capture streams and 113 by the driver for capture streams and by the application for
112 output streams, see :ref:`colorspaces` !! 114 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 115 * - __u32
121 - ``priv`` 116 - ``priv``
122 - This field indicates whether the remai 117 - This field indicates whether the remaining fields of the
123 struct :c:type:`v4l2_pix_format`, also 118 struct :c:type:`v4l2_pix_format`, also called the
124 extended fields, are valid. When set t 119 extended fields, are valid. When set to
125 ``V4L2_PIX_FMT_PRIV_MAGIC``, it indica 120 ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
126 have been correctly initialized. When 121 have been correctly initialized. When set to any other value it
127 indicates that the extended fields con 122 indicates that the extended fields contain undefined values.
128 123
129 Applications that wish to use the pixe 124 Applications that wish to use the pixel format extended fields
130 must first ensure that the feature is 125 must first ensure that the feature is supported by querying the
131 device for the :ref:`V4L2_CAP_EXT_PIX_ 126 device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
132 capability. If the capability isn't se 127 capability. If the capability isn't set the pixel format extended
133 fields are not supported and using the 128 fields are not supported and using the extended fields will lead
134 to undefined results. 129 to undefined results.
135 130
136 To use the extended fields, applicatio 131 To use the extended fields, applications must set the ``priv``
137 field to ``V4L2_PIX_FMT_PRIV_MAGIC``, 132 field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
138 fields and zero the unused bytes of th 133 fields and zero the unused bytes of the
139 struct :c:type:`v4l2_format` ``raw_dat 134 struct :c:type:`v4l2_format` ``raw_data`` field.
140 135
141 When the ``priv`` field isn't set to ` 136 When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
142 drivers must act as if all the extende 137 drivers must act as if all the extended fields were set to zero.
143 On return drivers must set the ``priv` 138 On return drivers must set the ``priv`` field to
144 ``V4L2_PIX_FMT_PRIV_MAGIC`` and all th 139 ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
145 applicable values. 140 applicable values.
146 * - __u32 141 * - __u32
147 - ``flags`` 142 - ``flags``
148 - Flags set by the application or driver 143 - Flags set by the application or driver, see :ref:`format-flags`.
149 * - union { 144 * - union {
150 - (anonymous) 145 - (anonymous)
151 * - __u32 146 * - __u32
152 - ``ycbcr_enc`` 147 - ``ycbcr_enc``
153 - Y'CbCr encoding, from enum :c:type:`v4 148 - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
154 This information supplements the ``col 149 This information supplements the ``colorspace`` and must be set by
155 the driver for capture streams and by 150 the driver for capture streams and by the application for output
156 streams, see :ref:`colorspaces`. If th !! 151 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 152 * - __u32
166 - ``hsv_enc`` 153 - ``hsv_enc``
167 - HSV encoding, from enum :c:type:`v4l2_ 154 - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
168 This information supplements the ``col 155 This information supplements the ``colorspace`` and must be set by
169 the driver for capture streams and by 156 the driver for capture streams and by the application for output
170 streams, see :ref:`colorspaces`. If th !! 157 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 * - } 158 * - }
180 - 159 -
181 * - __u32 160 * - __u32
182 - ``quantization`` 161 - ``quantization``
183 - Quantization range, from enum :c:type: 162 - Quantization range, from enum :c:type:`v4l2_quantization`.
184 This information supplements the ``col 163 This information supplements the ``colorspace`` and must be set by
185 the driver for capture streams and by 164 the driver for capture streams and by the application for output
186 streams, see :ref:`colorspaces`. If th !! 165 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 166 * - __u32
195 - ``xfer_func`` 167 - ``xfer_func``
196 - Transfer function, from enum :c:type:` 168 - Transfer function, from enum :c:type:`v4l2_xfer_func`.
197 This information supplements the ``col 169 This information supplements the ``colorspace`` and must be set by
198 the driver for capture streams and by 170 the driver for capture streams and by the application for output
199 streams, see :ref:`colorspaces`. If th !! 171 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.