1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2
3 ******************************
4 Single-planar format structure
5 ******************************
6
7 .. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7c
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`` i
24 ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_
25 refers to the number of lines in the f
26 the number of lines in the frame (whic
27 for interlaced formats).
28 * - :cspan:`2` Applications set these fiel
29 size, drivers return the closest possi
30 planar formats the ``width`` and ``hei
31 plane. To avoid ambiguities drivers mu
32 to a multiple of the scale factor of a
33 example when the image format is YUV 4
34 ``height`` must be multiples of two.
35
36 For compressed formats that contain th
37 inside the stream, when fed to a state
38 may be zero to rely on the decoder to
39 details see :ref:`decoder` and format
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
46 - ``pixelformat``
47 - The pixel format or type of compressio
48 This is a little endian
49 :ref:`four character code <v4l2-fourcc
50 RGB formats in :ref:`pixfmt-rgb`, YUV
51 :ref:`yuv-formats`, and reserved codes
52 :ref:`reserved-formats`
53 * - __u32
54 - ``field``
55 - Field order, from enum :c:type:`v4l2_f
56 Video images are typically interlaced.
57 capture or output only the top or bott
58 interlaced or sequentially stored in o
59 separate buffers. Drivers return the a
60 For more details on fields see :ref:`f
61 * - __u32
62 - ``bytesperline``
63 - Distance in bytes between the leftmost
64 lines.
65 * - :cspan:`2`
66
67 Both applications and drivers can set
68 padding bytes at the end of each line.
69 the value requested by the application
70 bytes per pixel or a larger value requ
71 implies applications can just set this
72 reasonable default.
73
74 Video hardware may access padding byte
75 reside in accessible memory. Consider
76 after the last line of an image cross
77 Input devices may write padding bytes,
78 Output devices ignore the contents of
79
80 When the image format is planar the ``
81 to the first plane and is divided by t
82 ``width`` field for the other planes.
83 planes of a YUV 4:2:0 image have half
84 following each line as the Y plane. To
85 must return a ``bytesperline`` value r
86 the scale factor.
87
88 For compressed formats the ``bytesperl
89 Applications and drivers must set this
90 * - __u32
91 - ``sizeimage``
92 - Size in bytes of the buffer to hold a
93 driver. Usually this is ``bytesperline
94 the image consists of variable length
95 number of bytes required by the codec
96 compression scenario.
97
98 The driver will set the value for unco
99
100 Clients are allowed to set the sizeima
101 compressed data flagged with ``V4L2_FM
102 :ref:`VIDIOC_ENUM_FMT`, but the driver
103 value itself, or it may modify the pro
104 alignment requirements or minimum/maxi
105 If the client wants to leave this to t
106 set sizeimage to 0.
107 * - __u32
108 - ``colorspace``
109 - Image colorspace, from enum :c:type:`v
110 This information supplements the ``pix
111 by the driver for capture streams and
112 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
121 - ``priv``
122 - This field indicates whether the remai
123 struct :c:type:`v4l2_pix_format`, also
124 extended fields, are valid. When set t
125 ``V4L2_PIX_FMT_PRIV_MAGIC``, it indica
126 have been correctly initialized. When
127 indicates that the extended fields con
128
129 Applications that wish to use the pixe
130 must first ensure that the feature is
131 device for the :ref:`V4L2_CAP_EXT_PIX_
132 capability. If the capability isn't se
133 fields are not supported and using the
134 to undefined results.
135
136 To use the extended fields, applicatio
137 field to ``V4L2_PIX_FMT_PRIV_MAGIC``,
138 fields and zero the unused bytes of th
139 struct :c:type:`v4l2_format` ``raw_dat
140
141 When the ``priv`` field isn't set to `
142 drivers must act as if all the extende
143 On return drivers must set the ``priv`
144 ``V4L2_PIX_FMT_PRIV_MAGIC`` and all th
145 applicable values.
146 * - __u32
147 - ``flags``
148 - Flags set by the application or driver
149 * - union {
150 - (anonymous)
151 * - __u32
152 - ``ycbcr_enc``
153 - Y'CbCr encoding, from enum :c:type:`v4
154 This information supplements the ``col
155 the driver for capture streams and by
156 streams, see :ref:`colorspaces`. If th
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
166 - ``hsv_enc``
167 - HSV encoding, from enum :c:type:`v4l2_
168 This information supplements the ``col
169 the driver for capture streams and by
170 streams, see :ref:`colorspaces`. If th
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 * - }
180 -
181 * - __u32
182 - ``quantization``
183 - Quantization range, from enum :c:type:
184 This information supplements the ``col
185 the driver for capture streams and by
186 streams, see :ref:`colorspaces`. If th
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
195 - ``xfer_func``
196 - Transfer function, from enum :c:type:`
197 This information supplements the ``col
198 the driver for capture streams and by
199 streams, see :ref:`colorspaces`. If th
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.