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         maximum number of bytes required to hold an image.
  93     * - __u32
  94       - ``colorspace``
  95       - Image colorspace, from enum :c:type:`v4l2_colorspace`.
  96         This information supplements the ``pixelformat`` and must be set
  97         by the driver for capture streams and by the application for
  98         output streams, see :ref:`colorspaces`.
  99     * - __u32
 100       - ``priv``
 101       - This field indicates whether the remaining fields of the
 102         struct :c:type:`v4l2_pix_format`, also called the
 103         extended fields, are valid. When set to
 104         ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
 105         have been correctly initialized. When set to any other value it
 106         indicates that the extended fields contain undefined values.
 107
 108         Applications that wish to use the pixel format extended fields
 109         must first ensure that the feature is supported by querying the
 110         device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
 111         capability. If the capability isn't set the pixel format extended
 112         fields are not supported and using the extended fields will lead
 113         to undefined results.
 114
 115         To use the extended fields, applications must set the ``priv``
 116         field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
 117         fields and zero the unused bytes of the
 118         struct :c:type:`v4l2_format` ``raw_data`` field.
 119
 120         When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
 121         drivers must act as if all the extended fields were set to zero.
 122         On return drivers must set the ``priv`` field to
 123         ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
 124         applicable values.
 125     * - __u32
 126       - ``flags``
 127       - Flags set by the application or driver, see :ref:`format-flags`.
 128     * - union {
 129       - (anonymous)
 130       -
 131     * - __u32
 132       - ``ycbcr_enc``
 133       - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
 134         This information supplements the ``colorspace`` and must be set by
 135         the driver for capture streams and by the application for output
 136         streams, see :ref:`colorspaces`.
 137     * - __u32
 138       - ``hsv_enc``
 139       - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
 140         This information supplements the ``colorspace`` and must be set by
 141         the driver for capture streams and by the application for output
 142         streams, see :ref:`colorspaces`.
 143     * - }
 144       -
 145       -
 146     * - __u32
 147       - ``quantization``
 148       - Quantization range, from enum :c:type:`v4l2_quantization`.
 149         This information supplements the ``colorspace`` and must be set by
 150         the driver for capture streams and by the application for output
 151         streams, see :ref:`colorspaces`.
 152     * - __u32
 153       - ``xfer_func``
 154       - Transfer function, from enum :c:type:`v4l2_xfer_func`.
 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`.