pixfmt-v4l2.rst (11335B)
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.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`.