Documentation/media/uapi/v4l/pixfmt-v4l2.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 ******************************
  11 Single-planar format structure
  12 ******************************
  13
  14 .. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}|
  15
  16 .. c:type:: v4l2_pix_format
  17
  18 .. cssclass:: longtable
  19
  20 .. flat-table:: struct v4l2_pix_format
  21     :header-rows:  0
  22     :stub-columns: 0
  23     :widths:       1 1 2
  24
  25     * - __u32
  26       - ``width``
  27       - Image width in pixels.
  28     * - __u32
  29       - ``height``
  30       - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
  31         ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
  32         refers to the number of lines in the field, otherwise it refers to
  33         the number of lines in the frame (which is twice the field height
  34         for interlaced formats).
  35     * - :cspan:`2` Applications set these fields to request an image
  36         size, drivers return the closest possible values. In case of
  37         planar formats the ``width`` and ``height`` applies to the largest
  38         plane. To avoid ambiguities drivers must return values rounded up
  39         to a multiple of the scale factor of any smaller planes. For
  40         example when the image format is YUV 4:2:0, ``width`` and
  41         ``height`` must be multiples of two.
  42     * - __u32
  43       - ``pixelformat``
  44       - The pixel format or type of compression, set by the application.
  45         This is a little endian
  46         :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
  47         RGB formats in :ref:`rgb-formats`, YUV formats in
  48         :ref:`yuv-formats`, and reserved codes in
  49         :ref:`reserved-formats`
  50     * - __u32
  51       - ``field``
  52       - Field order, from enum :c:type:`v4l2_field`.
  53         Video images are typically interlaced. Applications can request to
  54         capture or output only the top or bottom field, or both fields
  55         interlaced or sequentially stored in one buffer or alternating in
  56         separate buffers. Drivers return the actual field order selected.
  57         For more details on fields see :ref:`field-order`.
  58     * - __u32
  59       - ``bytesperline``
  60       - Distance in bytes between the leftmost pixels in two adjacent
  61         lines.
  62     * - :cspan:`2`
  63
  64         Both applications and drivers can set this field to request
  65         padding bytes at the end of each line. Drivers however may ignore
  66         the value requested by the application, returning ``width`` times
  67         bytes per pixel or a larger value required by the hardware. That
  68         implies applications can just set this field to zero to get a
  69         reasonable default.
  70
  71         Video hardware may access padding bytes, therefore they must
  72         reside in accessible memory. Consider cases where padding bytes
  73         after the last line of an image cross a system page boundary.
  74         Input devices may write padding bytes, the value is undefined.
  75         Output devices ignore the contents of padding bytes.
  76
  77         When the image format is planar the ``bytesperline`` value applies
  78         to the first plane and is divided by the same factor as the
  79         ``width`` field for the other planes. For example the Cb and Cr
  80         planes of a YUV 4:2:0 image have half as many padding bytes
  81         following each line as the Y plane. To avoid ambiguities drivers
  82         must return a ``bytesperline`` value rounded up to a multiple of
  83         the scale factor.
  84
  85         For compressed formats the ``bytesperline`` value makes no sense.
  86         Applications and drivers must set this to 0 in that case.
  87     * - __u32
  88       - ``sizeimage``
  89       - Size in bytes of the buffer to hold a complete image, set by the
  90         driver. Usually this is ``bytesperline`` times ``height``. When
  91         the image consists of variable length compressed data this is the
  92         number of bytes required by the codec to support the worst-case
  93         compression scenario.
  94
  95         The driver will set the value for uncompressed images.
  96
  97         Clients are allowed to set the sizeimage field for variable length
  98         compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at
  99         :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the
 100         value itself, or it may modify the provided value based on
 101         alignment requirements or minimum/maximum size requirements.
 102         If the client wants to leave this to the driver, then it should
 103         set sizeimage to 0.
 104     * - __u32
 105       - ``colorspace``
 106       - Image colorspace, from enum :c:type:`v4l2_colorspace`.
 107         This information supplements the ``pixelformat`` and must be set
 108         by the driver for capture streams and by the application for
 109         output streams, see :ref:`colorspaces`.
 110     * - __u32
 111       - ``priv``
 112       - This field indicates whether the remaining fields of the
 113         struct :c:type:`v4l2_pix_format`, also called the
 114         extended fields, are valid. When set to
 115         ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
 116         have been correctly initialized. When set to any other value it
 117         indicates that the extended fields contain undefined values.
 118
 119         Applications that wish to use the pixel format extended fields
 120         must first ensure that the feature is supported by querying the
 121         device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
 122         capability. If the capability isn't set the pixel format extended
 123         fields are not supported and using the extended fields will lead
 124         to undefined results.
 125
 126         To use the extended fields, applications must set the ``priv``
 127         field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
 128         fields and zero the unused bytes of the
 129         struct :c:type:`v4l2_format` ``raw_data`` field.
 130
 131         When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
 132         drivers must act as if all the extended fields were set to zero.
 133         On return drivers must set the ``priv`` field to
 134         ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
 135         applicable values.
 136     * - __u32
 137       - ``flags``
 138       - Flags set by the application or driver, see :ref:`format-flags`.
 139     * - union {
 140       - (anonymous)
 141       -
 142     * - __u32
 143       - ``ycbcr_enc``
 144       - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
 145         This information supplements the ``colorspace`` and must be set by
 146         the driver for capture streams and by the application for output
 147         streams, see :ref:`colorspaces`.
 148     * - __u32
 149       - ``hsv_enc``
 150       - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
 151         This information supplements the ``colorspace`` and must be set by
 152         the driver for capture streams and by the application for output
 153         streams, see :ref:`colorspaces`.
 154     * - }
 155       -
 156       -
 157     * - __u32
 158       - ``quantization``
 159       - Quantization range, from enum :c:type:`v4l2_quantization`.
 160         This information supplements the ``colorspace`` and must be set by
 161         the driver for capture streams and by the application for output
 162         streams, see :ref:`colorspaces`.
 163     * - __u32
 164       - ``xfer_func``
 165       - Transfer function, from enum :c:type:`v4l2_xfer_func`.
 166         This information supplements the ``colorspace`` and must be set by
 167         the driver for capture streams and by the application for output
 168         streams, see :ref:`colorspaces`.