1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4****************************** 5Single-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`. 242