1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 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
2 9
3 .. _planar-apis: 10 .. _planar-apis:
4 11
5 ***************************** 12 *****************************
6 Single- and multi-planar APIs 13 Single- and multi-planar APIs
7 ***************************** 14 *****************************
8 15
9 Some devices require data for each input or ou 16 Some devices require data for each input or output video frame to be
10 placed in discontiguous memory buffers. In suc 17 placed in discontiguous memory buffers. In such cases, one video frame
11 has to be addressed using more than one memory 18 has to be addressed using more than one memory address, i.e. one pointer
12 per "plane". A plane is a sub-buffer of the cu 19 per "plane". A plane is a sub-buffer of the current frame. For examples
13 of such formats see :ref:`pixfmt`. 20 of such formats see :ref:`pixfmt`.
14 21
15 Initially, V4L2 API did not support multi-plan 22 Initially, V4L2 API did not support multi-planar buffers and a set of
16 extensions has been introduced to handle them. 23 extensions has been introduced to handle them. Those extensions
17 constitute what is being referred to as the "m 24 constitute what is being referred to as the "multi-planar API".
18 25
19 Some of the V4L2 API calls and structures are 26 Some of the V4L2 API calls and structures are interpreted differently,
20 depending on whether single- or multi-planar A 27 depending on whether single- or multi-planar API is being used. An
21 application can choose whether to use one or t 28 application can choose whether to use one or the other by passing a
22 corresponding buffer type to its ioctl calls. 29 corresponding buffer type to its ioctl calls. Multi-planar versions of
23 buffer types are suffixed with an ``_MPLANE`` 30 buffer types are suffixed with an ``_MPLANE`` string. For a list of
24 available multi-planar buffer types see enum 31 available multi-planar buffer types see enum
25 :c:type:`v4l2_buf_type`. 32 :c:type:`v4l2_buf_type`.
26 33
27 34
28 Multi-planar formats 35 Multi-planar formats
29 ==================== 36 ====================
30 37
31 Multi-planar API introduces new multi-planar f 38 Multi-planar API introduces new multi-planar formats. Those formats use
32 a separate set of FourCC codes. It is importan 39 a separate set of FourCC codes. It is important to distinguish between
33 the multi-planar API and a multi-planar format 40 the multi-planar API and a multi-planar format. Multi-planar API calls
34 can handle all single-planar formats as well ( 41 can handle all single-planar formats as well (as long as they are passed
35 in multi-planar API structures), while the sin 42 in multi-planar API structures), while the single-planar API cannot
36 handle multi-planar formats. 43 handle multi-planar formats.
37 44
38 45
39 Calls that distinguish between single and mult 46 Calls that distinguish between single and multi-planar APIs
40 ============================================== 47 ===========================================================
41 48
42 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` 49 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
43 Two additional multi-planar capabilities a 50 Two additional multi-planar capabilities are added. They can be set
44 together with non-multi-planar ones for de 51 together with non-multi-planar ones for devices that handle both
45 single- and multi-planar formats. 52 single- and multi-planar formats.
46 53
47 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDI 54 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
48 New structures for describing multi-planar 55 New structures for describing multi-planar formats are added: struct
49 :c:type:`v4l2_pix_format_mplane` and 56 :c:type:`v4l2_pix_format_mplane` and
50 struct :c:type:`v4l2_plane_pix_format`. 57 struct :c:type:`v4l2_plane_pix_format`.
51 Drivers may define new multi-planar format 58 Drivers may define new multi-planar formats, which have distinct
52 FourCC codes from the existing single-plan 59 FourCC codes from the existing single-planar ones.
53 60
54 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC 61 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
55 A new struct :c:type:`v4l2_plane` structur 62 A new struct :c:type:`v4l2_plane` structure for
56 describing planes is added. Arrays of this 63 describing planes is added. Arrays of this structure are passed in
57 the new ``m.planes`` field of struct 64 the new ``m.planes`` field of struct
58 :c:type:`v4l2_buffer`. 65 :c:type:`v4l2_buffer`.
59 66
60 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` 67 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
61 Will allocate multi-planar buffers as requ 68 Will allocate multi-planar buffers as requested.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.