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