Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.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 Multi-planar format structures
  12 ******************************
  13
  14 The struct :c:type:`v4l2_plane_pix_format` structures define size
  15 and layout for each of the planes in a multi-planar format. The
  16 struct :c:type:`v4l2_pix_format_mplane` structure contains
  17 information common to all planes (such as image width and height) and an
  18 array of struct :c:type:`v4l2_plane_pix_format` structures,
  19 describing all planes of that format.
  20
  21
  22
  23 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  24
  25 .. c:type:: v4l2_plane_pix_format
  26
  27 .. flat-table:: struct v4l2_plane_pix_format
  28     :header-rows:  0
  29     :stub-columns: 0
  30     :widths:       1 1 2
  31
  32     * - __u32
  33       - ``sizeimage``
  34       - Maximum size in bytes required for image data in this plane,
  35         set by the driver. When the image consists of variable length
  36         compressed data this is the number of bytes required by the
  37         codec to support the worst-case compression scenario.
  38
  39         The driver will set the value for uncompressed images.
  40
  41         Clients are allowed to set the sizeimage field for variable length
  42         compressed data flagged with ``V4L2_FMT_FLAG_COMPRESSED`` at
  43         :ref:`VIDIOC_ENUM_FMT`, but the driver may ignore it and set the
  44         value itself, or it may modify the provided value based on
  45         alignment requirements or minimum/maximum size requirements.
  46         If the client wants to leave this to the driver, then it should
  47         set sizeimage to 0.
  48     * - __u32
  49       - ``bytesperline``
  50       - Distance in bytes between the leftmost pixels in two adjacent
  51         lines. See struct :c:type:`v4l2_pix_format`.
  52     * - __u16
  53       - ``reserved[6]``
  54       - Reserved for future extensions. Should be zeroed by drivers and
  55         applications.
  56
  57
  58 .. raw:: latex
  59
  60     \small
  61
  62 .. tabularcolumns:: |p{4.4cm}|p{5.6cm}|p{7.5cm}|
  63
  64 .. c:type:: v4l2_pix_format_mplane
  65
  66 .. flat-table:: struct v4l2_pix_format_mplane
  67     :header-rows:  0
  68     :stub-columns: 0
  69     :widths:       1 1 2
  70
  71     * - __u32
  72       - ``width``
  73       - Image width in pixels. See struct
  74         :c:type:`v4l2_pix_format`.
  75     * - __u32
  76       - ``height``
  77       - Image height in pixels. See struct
  78         :c:type:`v4l2_pix_format`.
  79     * - __u32
  80       - ``pixelformat``
  81       - The pixel format. Both single- and multi-planar four character
  82         codes can be used.
  83     * - __u32
  84       - ``field``
  85       - Field order, from enum :c:type:`v4l2_field`.
  86         See struct :c:type:`v4l2_pix_format`.
  87     * - __u32
  88       - ``colorspace``
  89       - Colorspace encoding, from enum :c:type:`v4l2_colorspace`.
  90         See struct :c:type:`v4l2_pix_format`.
  91     * - struct :c:type:`v4l2_plane_pix_format`
  92       - ``plane_fmt[VIDEO_MAX_PLANES]``
  93       - An array of structures describing format of each plane this pixel
  94         format consists of. The number of valid entries in this array has
  95         to be put in the ``num_planes`` field.
  96     * - __u8
  97       - ``num_planes``
  98       - Number of planes (i.e. separate memory buffers) for this format
  99         and the number of valid entries in the ``plane_fmt`` array.
 100     * - __u8
 101       - ``flags``
 102       - Flags set by the application or driver, see :ref:`format-flags`.
 103     * - :cspan:`2` union { (anonymous)
 104     * - __u8
 105       - ``ycbcr_enc``
 106       - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
 107         This information supplements the ``colorspace`` and must be set by
 108         the driver for capture streams and by the application for output
 109         streams, see :ref:`colorspaces`.
 110     * - __u8
 111       - ``hsv_enc``
 112       - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
 113         This information supplements the ``colorspace`` and must be set by
 114         the driver for capture streams and by the application for output
 115         streams, see :ref:`colorspaces`.
 116     * - :cspan:`2` }
 117     * - __u8
 118       - ``quantization``
 119       - Quantization range, from enum :c:type:`v4l2_quantization`.
 120         This information supplements the ``colorspace`` and must be set by
 121         the driver for capture streams and by the application for output
 122         streams, see :ref:`colorspaces`.
 123     * - __u8
 124       - ``xfer_func``
 125       - Transfer function, from enum :c:type:`v4l2_xfer_func`.
 126         This information supplements the ``colorspace`` and must be set by
 127         the driver for capture streams and by the application for output
 128         streams, see :ref:`colorspaces`.
 129     * - __u8
 130       - ``reserved[7]``
 131       - Reserved for future extensions. Should be zeroed by drivers and
 132         applications.
 133
 134 .. raw:: latex
 135
 136     \normalsize