241 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3******************************4Single-planar format structure5******************************6 7.. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7cm}|8 9.. c:type:: v4l2_pix_format10 11.. cssclass:: longtable12 13.. flat-table:: struct v4l2_pix_format14 :header-rows: 015 :stub-columns: 016 :widths: 1 1 217 18 * - __u3219 - ``width``20 - Image width in pixels.21 * - __u3222 - ``height``23 - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,24 ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height25 refers to the number of lines in the field, otherwise it refers to26 the number of lines in the frame (which is twice the field height27 for interlaced formats).28 * - :cspan:`2` Applications set these fields to request an image29 size, drivers return the closest possible values. In case of30 planar formats the ``width`` and ``height`` applies to the largest31 plane. To avoid ambiguities drivers must return values rounded up32 to a multiple of the scale factor of any smaller planes. For33 example when the image format is YUV 4:2:0, ``width`` and34 ``height`` must be multiples of two.35 36 For compressed formats that contain the resolution information encoded37 inside the stream, when fed to a stateful mem2mem decoder, the fields38 may be zero to rely on the decoder to detect the right values. For more39 details see :ref:`decoder` and format descriptions.40 41 For compressed formats on the CAPTURE side of a stateful mem2mem42 encoder, the fields must be zero, since the coded size is expected to43 be calculated internally by the encoder itself, based on the OUTPUT44 side. For more details see :ref:`encoder` and format descriptions.45 * - __u3246 - ``pixelformat``47 - The pixel format or type of compression, set by the application.48 This is a little endian49 :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard50 RGB formats in :ref:`pixfmt-rgb`, YUV formats in51 :ref:`yuv-formats`, and reserved codes in52 :ref:`reserved-formats`53 * - __u3254 - ``field``55 - Field order, from enum :c:type:`v4l2_field`.56 Video images are typically interlaced. Applications can request to57 capture or output only the top or bottom field, or both fields58 interlaced or sequentially stored in one buffer or alternating in59 separate buffers. Drivers return the actual field order selected.60 For more details on fields see :ref:`field-order`.61 * - __u3262 - ``bytesperline``63 - Distance in bytes between the leftmost pixels in two adjacent64 lines.65 * - :cspan:`2`66 67 Both applications and drivers can set this field to request68 padding bytes at the end of each line. Drivers however may ignore69 the value requested by the application, returning ``width`` times70 bytes per pixel or a larger value required by the hardware. That71 implies applications can just set this field to zero to get a72 reasonable default.73 74 Video hardware may access padding bytes, therefore they must75 reside in accessible memory. Consider cases where padding bytes76 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 applies81 to the first plane and is divided by the same factor as the82 ``width`` field for the other planes. For example the Cb and Cr83 planes of a YUV 4:2:0 image have half as many padding bytes84 following each line as the Y plane. To avoid ambiguities drivers85 must return a ``bytesperline`` value rounded up to a multiple of86 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 * - __u3291 - ``sizeimage``92 - Size in bytes of the buffer to hold a complete image, set by the93 driver. Usually this is ``bytesperline`` times ``height``. When94 the image consists of variable length compressed data this is the95 number of bytes required by the codec to support the worst-case96 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 length101 compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at102 :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the103 value itself, or it may modify the provided value based on104 alignment requirements or minimum/maximum size requirements.105 If the client wants to leave this to the driver, then it should106 set sizeimage to 0.107 * - __u32108 - ``colorspace``109 - Image colorspace, from enum :c:type:`v4l2_colorspace`.110 This information supplements the ``pixelformat`` and must be set111 by the driver for capture streams and by the application for112 output streams, see :ref:`colorspaces`. If the application sets the113 flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set114 this field for a capture stream to request a specific colorspace115 for the captured image data. If the driver cannot handle requested116 conversion, it will return another supported colorspace.117 The driver indicates that colorspace conversion is supported by setting118 the flag V4L2_FMT_FLAG_CSC_COLORSPACE in the corresponding struct119 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.120 * - __u32121 - ``priv``122 - This field indicates whether the remaining fields of the123 struct :c:type:`v4l2_pix_format`, also called the124 extended fields, are valid. When set to125 ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields126 have been correctly initialized. When set to any other value it127 indicates that the extended fields contain undefined values.128 129 Applications that wish to use the pixel format extended fields130 must first ensure that the feature is supported by querying the131 device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`132 capability. If the capability isn't set the pixel format extended133 fields are not supported and using the extended fields will lead134 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 extended138 fields and zero the unused bytes of the139 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 to144 ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to145 applicable values.146 * - __u32147 - ``flags``148 - Flags set by the application or driver, see :ref:`format-flags`.149 * - union {150 - (anonymous)151 * - __u32152 - ``ycbcr_enc``153 - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.154 This information supplements the ``colorspace`` and must be set by155 the driver for capture streams and by the application for output156 streams, see :ref:`colorspaces`. If the application sets the157 flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set158 this field for a capture stream to request a specific Y'CbCr encoding159 for the captured image data. If the driver cannot handle requested160 conversion, it will return another supported encoding.161 This field is ignored for HSV pixelformats. The driver indicates that162 ycbcr_enc conversion is supported by setting the flag163 V4L2_FMT_FLAG_CSC_YCBCR_ENC in the corresponding struct164 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.165 * - __u32166 - ``hsv_enc``167 - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.168 This information supplements the ``colorspace`` and must be set by169 the driver for capture streams and by the application for output170 streams, see :ref:`colorspaces`. If the application sets the flag171 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set this172 field for a capture stream to request a specific HSV encoding for the173 captured image data. If the driver cannot handle requested174 conversion, it will return another supported encoding.175 This field is ignored for non-HSV pixelformats. The driver indicates176 that hsv_enc conversion is supported by setting the flag177 V4L2_FMT_FLAG_CSC_HSV_ENC in the corresponding struct178 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.179 * - }180 -181 * - __u32182 - ``quantization``183 - Quantization range, from enum :c:type:`v4l2_quantization`.184 This information supplements the ``colorspace`` and must be set by185 the driver for capture streams and by the application for output186 streams, see :ref:`colorspaces`. If the application sets the flag187 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set188 this field for a capture stream to request a specific quantization189 range for the captured image data. If the driver cannot handle requested190 conversion, it will return another supported quantization.191 The driver indicates that quantization conversion is supported by setting192 the flag V4L2_FMT_FLAG_CSC_QUANTIZATION in the corresponding struct193 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.194 * - __u32195 - ``xfer_func``196 - Transfer function, from enum :c:type:`v4l2_xfer_func`.197 This information supplements the ``colorspace`` and must be set by198 the driver for capture streams and by the application for output199 streams, see :ref:`colorspaces`. If the application sets the flag200 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set201 this field for a capture stream to request a specific transfer function202 for the captured image data. If the driver cannot handle requested203 conversion, it will return another supported transfer function.204 The driver indicates that xfer_func conversion is supported by setting205 the flag V4L2_FMT_FLAG_CSC_XFER_FUNC in the corresponding struct206 :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 Flags213 :header-rows: 0214 :stub-columns: 0215 :widths: 3 1 4216 217 * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA``218 - 0x00000001219 - The color values are premultiplied by the alpha channel value. For220 example, if a light blue pixel with 50% transparency was described221 by RGBA values (128, 192, 255, 128), the same pixel described with222 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 - 0x00000002228 - Set by the application. It is only used for capture and is229 ignored for output streams. If set, then request the device to do230 colorspace conversion from the received colorspace to the requested231 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 shall235 be set to non default value (``V4L2_QUANTIZATION_FULL_RANGE`` or236 ``V4L2_QUANTIZATION_LIM_RANGE``) and all other colorimetry fields shall237 be set to ``*_DEFAULT``.238 239 To check which conversions are supported by the hardware for the current240 pixel format, see :ref:`fmtdesc-flags`.241