0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 ******************************
0004 Single-planar format structure
0005 ******************************
0006
0007 .. tabularcolumns:: |p{4.0cm}|p{2.6cm}|p{10.7cm}|
0008
0009 .. c:type:: v4l2_pix_format
0010
0011 .. cssclass:: longtable
0012
0013 .. flat-table:: struct v4l2_pix_format
0014 :header-rows: 0
0015 :stub-columns: 0
0016 :widths: 1 1 2
0017
0018 * - __u32
0019 - ``width``
0020 - Image width in pixels.
0021 * - __u32
0022 - ``height``
0023 - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
0024 ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
0025 refers to the number of lines in the field, otherwise it refers to
0026 the number of lines in the frame (which is twice the field height
0027 for interlaced formats).
0028 * - :cspan:`2` Applications set these fields to request an image
0029 size, drivers return the closest possible values. In case of
0030 planar formats the ``width`` and ``height`` applies to the largest
0031 plane. To avoid ambiguities drivers must return values rounded up
0032 to a multiple of the scale factor of any smaller planes. For
0033 example when the image format is YUV 4:2:0, ``width`` and
0034 ``height`` must be multiples of two.
0035
0036 For compressed formats that contain the resolution information encoded
0037 inside the stream, when fed to a stateful mem2mem decoder, the fields
0038 may be zero to rely on the decoder to detect the right values. For more
0039 details see :ref:`decoder` and format descriptions.
0040
0041 For compressed formats on the CAPTURE side of a stateful mem2mem
0042 encoder, the fields must be zero, since the coded size is expected to
0043 be calculated internally by the encoder itself, based on the OUTPUT
0044 side. For more details see :ref:`encoder` and format descriptions.
0045 * - __u32
0046 - ``pixelformat``
0047 - The pixel format or type of compression, set by the application.
0048 This is a little endian
0049 :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
0050 RGB formats in :ref:`pixfmt-rgb`, YUV formats in
0051 :ref:`yuv-formats`, and reserved codes in
0052 :ref:`reserved-formats`
0053 * - __u32
0054 - ``field``
0055 - Field order, from enum :c:type:`v4l2_field`.
0056 Video images are typically interlaced. Applications can request to
0057 capture or output only the top or bottom field, or both fields
0058 interlaced or sequentially stored in one buffer or alternating in
0059 separate buffers. Drivers return the actual field order selected.
0060 For more details on fields see :ref:`field-order`.
0061 * - __u32
0062 - ``bytesperline``
0063 - Distance in bytes between the leftmost pixels in two adjacent
0064 lines.
0065 * - :cspan:`2`
0066
0067 Both applications and drivers can set this field to request
0068 padding bytes at the end of each line. Drivers however may ignore
0069 the value requested by the application, returning ``width`` times
0070 bytes per pixel or a larger value required by the hardware. That
0071 implies applications can just set this field to zero to get a
0072 reasonable default.
0073
0074 Video hardware may access padding bytes, therefore they must
0075 reside in accessible memory. Consider cases where padding bytes
0076 after the last line of an image cross a system page boundary.
0077 Input devices may write padding bytes, the value is undefined.
0078 Output devices ignore the contents of padding bytes.
0079
0080 When the image format is planar the ``bytesperline`` value applies
0081 to the first plane and is divided by the same factor as the
0082 ``width`` field for the other planes. For example the Cb and Cr
0083 planes of a YUV 4:2:0 image have half as many padding bytes
0084 following each line as the Y plane. To avoid ambiguities drivers
0085 must return a ``bytesperline`` value rounded up to a multiple of
0086 the scale factor.
0087
0088 For compressed formats the ``bytesperline`` value makes no sense.
0089 Applications and drivers must set this to 0 in that case.
0090 * - __u32
0091 - ``sizeimage``
0092 - Size in bytes of the buffer to hold a complete image, set by the
0093 driver. Usually this is ``bytesperline`` times ``height``. When
0094 the image consists of variable length compressed data this is the
0095 number of bytes required by the codec to support the worst-case
0096 compression scenario.
0097
0098 The driver will set the value for uncompressed images.
0099
0100 Clients are allowed to set the sizeimage field for variable length
0101 compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at
0102 :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the
0103 value itself, or it may modify the provided value based on
0104 alignment requirements or minimum/maximum size requirements.
0105 If the client wants to leave this to the driver, then it should
0106 set sizeimage to 0.
0107 * - __u32
0108 - ``colorspace``
0109 - Image colorspace, from enum :c:type:`v4l2_colorspace`.
0110 This information supplements the ``pixelformat`` and must be set
0111 by the driver for capture streams and by the application for
0112 output streams, see :ref:`colorspaces`. If the application sets the
0113 flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
0114 this field for a capture stream to request a specific colorspace
0115 for the captured image data. If the driver cannot handle requested
0116 conversion, it will return another supported colorspace.
0117 The driver indicates that colorspace conversion is supported by setting
0118 the flag V4L2_FMT_FLAG_CSC_COLORSPACE in the corresponding struct
0119 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
0120 * - __u32
0121 - ``priv``
0122 - This field indicates whether the remaining fields of the
0123 struct :c:type:`v4l2_pix_format`, also called the
0124 extended fields, are valid. When set to
0125 ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
0126 have been correctly initialized. When set to any other value it
0127 indicates that the extended fields contain undefined values.
0128
0129 Applications that wish to use the pixel format extended fields
0130 must first ensure that the feature is supported by querying the
0131 device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
0132 capability. If the capability isn't set the pixel format extended
0133 fields are not supported and using the extended fields will lead
0134 to undefined results.
0135
0136 To use the extended fields, applications must set the ``priv``
0137 field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
0138 fields and zero the unused bytes of the
0139 struct :c:type:`v4l2_format` ``raw_data`` field.
0140
0141 When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
0142 drivers must act as if all the extended fields were set to zero.
0143 On return drivers must set the ``priv`` field to
0144 ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
0145 applicable values.
0146 * - __u32
0147 - ``flags``
0148 - Flags set by the application or driver, see :ref:`format-flags`.
0149 * - union {
0150 - (anonymous)
0151 * - __u32
0152 - ``ycbcr_enc``
0153 - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
0154 This information supplements the ``colorspace`` and must be set by
0155 the driver for capture streams and by the application for output
0156 streams, see :ref:`colorspaces`. If the application sets the
0157 flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
0158 this field for a capture stream to request a specific Y'CbCr encoding
0159 for the captured image data. If the driver cannot handle requested
0160 conversion, it will return another supported encoding.
0161 This field is ignored for HSV pixelformats. The driver indicates that
0162 ycbcr_enc conversion is supported by setting the flag
0163 V4L2_FMT_FLAG_CSC_YCBCR_ENC in the corresponding struct
0164 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
0165 * - __u32
0166 - ``hsv_enc``
0167 - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
0168 This information supplements the ``colorspace`` and must be set by
0169 the driver for capture streams and by the application for output
0170 streams, see :ref:`colorspaces`. If the application sets the flag
0171 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set this
0172 field for a capture stream to request a specific HSV encoding for the
0173 captured image data. If the driver cannot handle requested
0174 conversion, it will return another supported encoding.
0175 This field is ignored for non-HSV pixelformats. The driver indicates
0176 that hsv_enc conversion is supported by setting the flag
0177 V4L2_FMT_FLAG_CSC_HSV_ENC in the corresponding struct
0178 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
0179 * - }
0180 -
0181 * - __u32
0182 - ``quantization``
0183 - Quantization range, from enum :c:type:`v4l2_quantization`.
0184 This information supplements the ``colorspace`` and must be set by
0185 the driver for capture streams and by the application for output
0186 streams, see :ref:`colorspaces`. If the application sets the flag
0187 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
0188 this field for a capture stream to request a specific quantization
0189 range for the captured image data. If the driver cannot handle requested
0190 conversion, it will return another supported quantization.
0191 The driver indicates that quantization conversion is supported by setting
0192 the flag V4L2_FMT_FLAG_CSC_QUANTIZATION in the corresponding struct
0193 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
0194 * - __u32
0195 - ``xfer_func``
0196 - Transfer function, from enum :c:type:`v4l2_xfer_func`.
0197 This information supplements the ``colorspace`` and must be set by
0198 the driver for capture streams and by the application for output
0199 streams, see :ref:`colorspaces`. If the application sets the flag
0200 ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
0201 this field for a capture stream to request a specific transfer function
0202 for the captured image data. If the driver cannot handle requested
0203 conversion, it will return another supported transfer function.
0204 The driver indicates that xfer_func conversion is supported by setting
0205 the flag V4L2_FMT_FLAG_CSC_XFER_FUNC in the corresponding struct
0206 :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
0207
0208 .. tabularcolumns:: |p{6.8cm}|p{2.3cm}|p{8.2cm}|
0209
0210 .. _format-flags:
0211
0212 .. flat-table:: Format Flags
0213 :header-rows: 0
0214 :stub-columns: 0
0215 :widths: 3 1 4
0216
0217 * - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA``
0218 - 0x00000001
0219 - The color values are premultiplied by the alpha channel value. For
0220 example, if a light blue pixel with 50% transparency was described
0221 by RGBA values (128, 192, 255, 128), the same pixel described with
0222 premultiplied colors would be described by RGBA values (64, 96,
0223 128, 128)
0224 * .. _`v4l2-pix-fmt-flag-set-csc`:
0225
0226 - ``V4L2_PIX_FMT_FLAG_SET_CSC``
0227 - 0x00000002
0228 - Set by the application. It is only used for capture and is
0229 ignored for output streams. If set, then request the device to do
0230 colorspace conversion from the received colorspace to the requested
0231 colorspace values. If the colorimetry field (``colorspace``, ``xfer_func``,
0232 ``ycbcr_enc``, ``hsv_enc`` or ``quantization``) is set to ``*_DEFAULT``,
0233 then that colorimetry setting will remain unchanged from what was received.
0234 So in order to change the quantization, only the ``quantization`` field shall
0235 be set to non default value (``V4L2_QUANTIZATION_FULL_RANGE`` or
0236 ``V4L2_QUANTIZATION_LIM_RANGE``) and all other colorimetry fields shall
0237 be set to ``*_DEFAULT``.
0238
0239 To check which conversions are supported by the hardware for the current
0240 pixel format, see :ref:`fmtdesc-flags`.
