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/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10******************************
11Multi-planar format structures
12******************************
13
14The struct :c:type:`v4l2_plane_pix_format` structures define size
15and layout for each of the planes in a multi-planar format. The
16struct :c:type:`v4l2_pix_format_mplane` structure contains
17information common to all planes (such as image width and height) and an
18array of struct :c:type:`v4l2_plane_pix_format` structures,
19describing 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    * - union {
104      - (anonymous)
105    * - __u8
106      - ``ycbcr_enc``
107      - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
108        This information supplements the ``colorspace`` and must be set by
109	the driver for capture streams and by the application for output
110	streams, see :ref:`colorspaces`.
111    * - __u8
112      - ``hsv_enc``
113      - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
114        This information supplements the ``colorspace`` and must be set by
115	the driver for capture streams and by the application for output
116	streams, see :ref:`colorspaces`.
117    * - }
118      -
119    * - __u8
120      - ``quantization``
121      - Quantization range, from enum :c:type:`v4l2_quantization`.
122        This information supplements the ``colorspace`` and must be set by
123	the driver for capture streams and by the application for output
124	streams, see :ref:`colorspaces`.
125    * - __u8
126      - ``xfer_func``
127      - Transfer function, from enum :c:type:`v4l2_xfer_func`.
128        This information supplements the ``colorspace`` and must be set by
129	the driver for capture streams and by the application for output
130	streams, see :ref:`colorspaces`.
131    * - __u8
132      - ``reserved[7]``
133      - Reserved for future extensions. Should be zeroed by drivers and
134	applications.
135
136.. raw:: latex
137
138    \normalsize
139