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

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