1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3******************************
4Multi-planar format structures
5******************************
6
7The struct :c:type:`v4l2_plane_pix_format` structures define size
8and layout for each of the planes in a multi-planar format. The
9struct :c:type:`v4l2_pix_format_mplane` structure contains
10information common to all planes (such as image width and height) and an
11array of struct :c:type:`v4l2_plane_pix_format` structures,
12describing 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
124