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 | |
23 | buffer types are suffixed with an `_MPLANE' string. For a list of | |
24 | available multi-planar buffer types see enum | |
25 | :ref:`v4l2_buf_type <v4l2-buf-type>`. | |
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 | ||
7347081e | 42 | :ref:`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 | ||
4e03cb76 | 47 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, |
af4a4d0d MCC |
48 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, |
49 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` | |
5377d91f MH |
50 | New structures for describing multi-planar formats are added: struct |
51 | :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and | |
52 | struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`. | |
53 | Drivers may define new multi-planar formats, which have distinct | |
54 | FourCC codes from the existing single-planar ones. | |
55 | ||
7347081e | 56 | :ref:`VIDIOC_QBUF`, |
af4a4d0d | 57 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, |
7347081e | 58 | :ref:`VIDIOC_QUERYBUF` |
5377d91f MH |
59 | A new struct :ref:`v4l2_plane <v4l2-plane>` structure for |
60 | describing planes is added. Arrays of this structure are passed in | |
61 | the new ``m.planes`` field of struct | |
62 | :ref:`v4l2_buffer <v4l2-buffer>`. | |
63 | ||
7347081e | 64 | :ref:`VIDIOC_REQBUFS` |
5377d91f MH |
65 | Will allocate multi-planar buffers as requested. |
66 | ||
67 | ||
68 | .. ------------------------------------------------------------------------------ | |
69 | .. This file was automatically converted from DocBook-XML with the dbxml | |
70 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
71 | .. from the linux kernel, refer to: | |
72 | .. | |
73 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
74 | .. ------------------------------------------------------------------------------ |