Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _planar-apis: | |
4 | ||
5 | ***************************** | |
6 | Single- and multi-planar APIs | |
7 | ***************************** | |
8 | ||
9 | Some devices require data for each input or output video frame to be | |
10 | placed in discontiguous memory buffers. In such cases, one video frame | |
11 | 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 current frame. For examples | |
13 | of such formats see :ref:`pixfmt`. | |
14 | ||
15 | Initially, V4L2 API did not support multi-planar buffers and a set of | |
16 | extensions has been introduced to handle them. Those extensions | |
17 | constitute what is being referred to as the "multi-planar API". | |
18 | ||
19 | Some of the V4L2 API calls and structures are interpreted differently, | |
20 | depending on whether single- or multi-planar API is being used. An | |
21 | application can choose whether to use one or the other by passing a | |
22 | corresponding buffer type to its ioctl calls. Multi-planar versions of | |
c32940a6 | 23 | buffer types are suffixed with an ``_MPLANE`` string. For a list of |
5377d91f | 24 | available multi-planar buffer types see enum |
56683d7d | 25 | :c:type:`v4l2_buf_type`. |
5377d91f MH |
26 | |
27 | ||
28 | Multi-planar formats | |
29 | ==================== | |
30 | ||
31 | Multi-planar API introduces new multi-planar formats. Those formats use | |
32 | a separate set of FourCC codes. It is important to distinguish between | |
33 | the multi-planar API and a multi-planar format. Multi-planar API calls | |
34 | can handle all single-planar formats as well (as long as they are passed | |
35 | in multi-planar API structures), while the single-planar API cannot | |
36 | handle multi-planar formats. | |
37 | ||
38 | ||
39 | Calls that distinguish between single and multi-planar APIs | |
40 | =========================================================== | |
41 | ||
c32940a6 | 42 | :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` |
5377d91f MH |
43 | Two additional multi-planar capabilities are added. They can be set |
44 | together with non-multi-planar ones for devices that handle both | |
45 | single- and multi-planar formats. | |
46 | ||
c32940a6 | 47 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` |
5377d91f | 48 | New structures for describing multi-planar formats are added: struct |
e8be7e97 MCC |
49 | :c:type:`v4l2_pix_format_mplane` and |
50 | struct :c:type:`v4l2_plane_pix_format`. | |
5377d91f MH |
51 | Drivers may define new multi-planar formats, which have distinct |
52 | FourCC codes from the existing single-planar ones. | |
53 | ||
c32940a6 | 54 | :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` |
e8be7e97 | 55 | A new struct :c:type:`v4l2_plane` structure for |
5377d91f MH |
56 | describing planes is added. Arrays of this structure are passed in |
57 | the new ``m.planes`` field of struct | |
e8be7e97 | 58 | :c:type:`v4l2_buffer`. |
5377d91f | 59 | |
c32940a6 | 60 | :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` |
5377d91f | 61 | Will allocate multi-planar buffers as requested. |