Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2
   3 ******************************
   4 Single-planar format structure
   5 ******************************
   6
   7 .. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}|
   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.6cm}|p{2.2cm}|p{8.7cm}|
 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`.