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