1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3******************************
4Single-planar format structure
5******************************
6
7.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}|
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.6cm}|p{2.2cm}|p{8.7cm}|
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`.
241