Doug / smarc-fsl-linux-kernel

Download as
Browse Code ยป

Commit 53b5d5749b6fcca37c7ad60cd40feafadd390b70

Authored by Pawel Osciak
Committed by Mauro Carvalho Chehab
1 parent c4c0a78d45
Exists in master and in 7 other branches imx_3.0.35_4.1.0, imx_3.10.17_1.0.1_ga, imx_3.10.53_1.1.0_ga, imx_3.14.28_1.0.0_ga, smarc-imx_3.10.53_1.1.0_ga, smarc-imx_3.14.28_1.0.0_ga, smarc-l5.0.0_1.0.0-ga

[media] Add multi-planar API documentation 

Add DocBook documentation for the new multi-planar API extensions to the
Video for Linux 2 API DocBook.

Signed-off-by: Pawel Osciak <pawel@osciak.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Showing 16 changed files with 530 additions and 70 deletions Side-by-side Diff

Documentation/DocBook/media-entities.tmpl
Diff comments   View file @ 53b5d57
... ... @@ -129,6 +129,7 @@
129 129 <!ENTITY v4l2-audioout "struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link>">
130 130 <!ENTITY v4l2-bt-timings "struct&nbsp;<link linkend='v4l2-bt-timings'>v4l2_bt_timings</link>">
131 131 <!ENTITY v4l2-buffer "struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link>">
  132 +<!ENTITY v4l2-plane "struct&nbsp;<link linkend='v4l2-plane'>v4l2_plane</link>">
132 133 <!ENTITY v4l2-capability "struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link>">
133 134 <!ENTITY v4l2-captureparm "struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link>">
134 135 <!ENTITY v4l2-clip "struct&nbsp;<link linkend='v4l2-clip'>v4l2_clip</link>">
... ... @@ -167,6 +168,8 @@
167 168 <!ENTITY v4l2-output "struct&nbsp;<link linkend='v4l2-output'>v4l2_output</link>">
168 169 <!ENTITY v4l2-outputparm "struct&nbsp;<link linkend='v4l2-outputparm'>v4l2_outputparm</link>">
169 170 <!ENTITY v4l2-pix-format "struct&nbsp;<link linkend='v4l2-pix-format'>v4l2_pix_format</link>">
  171 +<!ENTITY v4l2-pix-format-mplane "struct&nbsp;<link linkend='v4l2-pix-format-mplane'>v4l2_pix_format_mplane</link>">
  172 +<!ENTITY v4l2-plane-pix-format "struct&nbsp;<link linkend='v4l2-plane-pix-format'>v4l2_plane_pix_format</link>">
170 173 <!ENTITY v4l2-queryctrl "struct&nbsp;<link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>">
171 174 <!ENTITY v4l2-querymenu "struct&nbsp;<link linkend='v4l2-querymenu'>v4l2_querymenu</link>">
172 175 <!ENTITY v4l2-rect "struct&nbsp;<link linkend='v4l2-rect'>v4l2_rect</link>">
... ... @@ -202,6 +205,7 @@
202 205 <!-- Subsections -->
203 206 <!ENTITY sub-biblio SYSTEM "v4l/biblio.xml">
204 207 <!ENTITY sub-common SYSTEM "v4l/common.xml">
  208 +<!ENTITY sub-planar-apis SYSTEM "v4l/planar-apis.xml">
205 209 <!ENTITY sub-compat SYSTEM "v4l/compat.xml">
206 210 <!ENTITY sub-controls SYSTEM "v4l/controls.xml">
207 211 <!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml">
Documentation/DocBook/v4l/common.xml
Diff comments   View file @ 53b5d57
... ... @@ -846,6 +846,8 @@
846 846 </section>
847 847 </section>
848 848  
  849 + &sub-planar-apis;
  850 +
849 851 <section id="crop">
850 852 <title>Image Cropping, Insertion and Scaling</title>
851 853  
Documentation/DocBook/v4l/compat.xml
Diff comments   View file @ 53b5d57
... ... @@ -2353,6 +2353,17 @@
2353 2353 </listitem>
2354 2354 </orderedlist>
2355 2355 </section>
  2356 + <section>
  2357 + <title>V4L2 in Linux 2.6.38</title>
  2358 + <orderedlist>
  2359 + <listitem>
  2360 + <para>Multi-planar API added. Does not affect the compatibility of
  2361 + current drivers and applications. See
  2362 + <link linkend="planar-apis">multi-planar API</link>
  2363 + for details.</para>
  2364 + </listitem>
  2365 + </orderedlist>
  2366 + </section>
2356 2367  
2357 2368 <section id="other">
2358 2369 <title>Relation of V4L2 to other Linux multimedia APIs</title>
Documentation/DocBook/v4l/dev-capture.xml
Diff comments   View file @ 53b5d57
... ... @@ -18,7 +18,8 @@
18 18 <title>Querying Capabilities</title>
19 19  
20 20 <para>Devices supporting the video capture interface set the
21   -<constant>V4L2_CAP_VIDEO_CAPTURE</constant> flag in the
  21 +<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or
  22 +<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the
22 23 <structfield>capabilities</structfield> field of &v4l2-capability;
23 24 returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
24 25 they may also support the <link linkend="overlay">video overlay</link>
25 26  
... ... @@ -64,9 +65,11 @@
64 65  
65 66 <para>To query the current image format applications set the
66 67 <structfield>type</structfield> field of a &v4l2-format; to
67   -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the
  68 +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
  69 +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the
68 70 &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
69   -the &v4l2-pix-format; <structfield>pix</structfield> member of the
  71 +the &v4l2-pix-format; <structfield>pix</structfield> or the
  72 +&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
70 73 <structfield>fmt</structfield> union.</para>
71 74  
72 75 <para>To request different parameters applications set the
... ... @@ -84,8 +87,8 @@
84 87 without disabling I/O or possibly time consuming hardware
85 88 preparations.</para>
86 89  
87   - <para>The contents of &v4l2-pix-format; are discussed in <xref
88   -linkend="pixfmt" />. See also the specification of the
  90 + <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
  91 +are discussed in <xref linkend="pixfmt" />. See also the specification of the
89 92 <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
90 93 and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
91 94 capture devices must implement both the
Documentation/DocBook/v4l/dev-output.xml
Diff comments   View file @ 53b5d57
... ... @@ -17,7 +17,8 @@
17 17 <title>Querying Capabilities</title>
18 18  
19 19 <para>Devices supporting the video output interface set the
20   -<constant>V4L2_CAP_VIDEO_OUTPUT</constant> flag in the
  20 +<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
  21 +<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
21 22 <structfield>capabilities</structfield> field of &v4l2-capability;
22 23 returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
23 24 they may also support the <link linkend="raw-vbi">raw VBI
24 25  
... ... @@ -60,9 +61,11 @@
60 61  
61 62 <para>To query the current image format applications set the
62 63 <structfield>type</structfield> field of a &v4l2-format; to
63   -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and call the
  64 +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
  65 +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
64 66 &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
65   -the &v4l2-pix-format; <structfield>pix</structfield> member of the
  67 +the &v4l2-pix-format; <structfield>pix</structfield> or the
  68 +&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
66 69 <structfield>fmt</structfield> union.</para>
67 70  
68 71 <para>To request different parameters applications set the
... ... @@ -80,8 +83,8 @@
80 83 without disabling I/O or possibly time consuming hardware
81 84 preparations.</para>
82 85  
83   - <para>The contents of &v4l2-pix-format; are discussed in <xref
84   -linkend="pixfmt" />. See also the specification of the
  86 + <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
  87 +are discussed in <xref linkend="pixfmt" />. See also the specification of the
85 88 <constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
86 89 and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
87 90 output devices must implement both the
Documentation/DocBook/v4l/func-mmap.xml
Diff comments   View file @ 53b5d57
... ... @@ -45,7 +45,10 @@
45 45 <listitem>
46 46 <para>Length of the memory area to map. This must be the
47 47 same value as returned by the driver in the &v4l2-buffer;
48   -<structfield>length</structfield> field.</para>
  48 +<structfield>length</structfield> field for the
  49 +single-planar API, and the same value as returned by the driver
  50 +in the &v4l2-plane; <structfield>length</structfield> field for the
  51 +multi-planar API.</para>
49 52 </listitem>
50 53 </varlistentry>
51 54 <varlistentry>
... ... @@ -106,7 +109,10 @@
106 109 <listitem>
107 110 <para>Offset of the buffer in device memory. This must be the
108 111 same value as returned by the driver in the &v4l2-buffer;
109   -<structfield>m</structfield> union <structfield>offset</structfield> field.</para>
  112 +<structfield>m</structfield> union <structfield>offset</structfield> field for
  113 +the single-planar API, and the same value as returned by the driver
  114 +in the &v4l2-plane; <structfield>m</structfield> union
  115 +<structfield>mem_offset</structfield> field for the multi-planar API.</para>
110 116 </listitem>
111 117 </varlistentry>
112 118 </variablelist>
Documentation/DocBook/v4l/func-munmap.xml
Diff comments   View file @ 53b5d57
... ... @@ -37,7 +37,8 @@
37 37 <para>Length of the mapped buffer. This must be the same
38 38 value as given to <function>mmap()</function> and returned by the
39 39 driver in the &v4l2-buffer; <structfield>length</structfield>
40   -field.</para>
  40 +field for the single-planar API and in the &v4l2-plane;
  41 +<structfield>length</structfield> field for the multi-planar API.</para>
41 42 </listitem>
42 43 </varlistentry>
43 44 </variablelist>
Documentation/DocBook/v4l/io.xml
Diff comments   View file @ 53b5d57
... ... @@ -121,18 +121,22 @@
121 121 <para>Before applications can access the buffers they must map
122 122 them into their address space with the &func-mmap; function. The
123 123 location of the buffers in device memory can be determined with the
124   -&VIDIOC-QUERYBUF; ioctl. The <structfield>m.offset</structfield> and
125   -<structfield>length</structfield> returned in a &v4l2-buffer; are
126   -passed as sixth and second parameter to the
127   -<function>mmap()</function> function. The offset and length values
128   -must not be modified. Remember the buffers are allocated in physical
129   -memory, as opposed to virtual memory which can be swapped out to disk.
130   -Applications should free the buffers as soon as possible with the
131   -&func-munmap; function.</para>
  124 +&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
  125 +<structfield>m.offset</structfield> and <structfield>length</structfield>
  126 +returned in a &v4l2-buffer; are passed as sixth and second parameter to the
  127 +<function>mmap()</function> function. When using the multi-planar API,
  128 +struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
  129 +containing its own <structfield>m.offset</structfield> and
  130 +<structfield>length</structfield>. When using the multi-planar API, every
  131 +plane of every buffer has to be mapped separately, so the number of
  132 +calls to &func-mmap; should be equal to number of buffers times number of
  133 +planes in each buffer. The offset and length values must not be modified.
  134 +Remember, the buffers are allocated in physical memory, as opposed to virtual
  135 +memory, which can be swapped out to disk. Applications should free the buffers
  136 +as soon as possible with the &func-munmap; function.</para>
132 137  
133 138 <example>
134   - <title>Mapping buffers</title>
135   -
  139 + <title>Mapping buffers in the single-planar API</title>
136 140 <programlisting>
137 141 &v4l2-requestbuffers; reqbuf;
138 142 struct {
... ... @@ -201,6 +205,88 @@
201 205 </programlisting>
202 206 </example>
203 207  
  208 + <example>
  209 + <title>Mapping buffers in the multi-planar API</title>
  210 + <programlisting>
  211 +&v4l2-requestbuffers; reqbuf;
  212 +/* Our current format uses 3 planes per buffer */
  213 +#define FMT_NUM_PLANES = 3;
  214 +
  215 +struct {
  216 + void *start[FMT_NUM_PLANES];
  217 + size_t length[FMT_NUM_PLANES];
  218 +} *buffers;
  219 +unsigned int i, j;
  220 +
  221 +memset(&amp;reqbuf, 0, sizeof(reqbuf));
  222 +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
  223 +reqbuf.memory = V4L2_MEMORY_MMAP;
  224 +reqbuf.count = 20;
  225 +
  226 +if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) &lt; 0) {
  227 + if (errno == EINVAL)
  228 + printf("Video capturing or mmap-streaming is not supported\n");
  229 + else
  230 + perror("VIDIOC_REQBUFS");
  231 +
  232 + exit(EXIT_FAILURE);
  233 +}
  234 +
  235 +/* We want at least five buffers. */
  236 +
  237 +if (reqbuf.count &lt; 5) {
  238 + /* You may need to free the buffers here. */
  239 + printf("Not enough buffer memory\n");
  240 + exit(EXIT_FAILURE);
  241 +}
  242 +
  243 +buffers = calloc(reqbuf.count, sizeof(*buffers));
  244 +assert(buffers != NULL);
  245 +
  246 +for (i = 0; i &lt; reqbuf.count; i++) {
  247 + &v4l2-buffer; buffer;
  248 + &v4l2-plane; planes[FMT_NUM_PLANES];
  249 +
  250 + memset(&amp;buffer, 0, sizeof(buffer));
  251 + buffer.type = reqbuf.type;
  252 + buffer.memory = V4L2_MEMORY_MMAP;
  253 + buffer.index = i;
  254 + /* length in struct v4l2_buffer in multi-planar API stores the size
  255 + * of planes array. */
  256 + buffer.length = FMT_NUM_PLANES;
  257 + buffer.m.planes = planes;
  258 +
  259 + if (ioctl(fd, &VIDIOC-QUERYBUF;, &amp;buffer) &lt; 0) {
  260 + perror("VIDIOC_QUERYBUF");
  261 + exit(EXIT_FAILURE);
  262 + }
  263 +
  264 + /* Every plane has to be mapped separately */
  265 + for (j = 0; j &lt; FMT_NUM_PLANES; j++) {
  266 + buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
  267 +
  268 + buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
  269 + PROT_READ | PROT_WRITE, /* recommended */
  270 + MAP_SHARED, /* recommended */
  271 + fd, buffer.m.planes[j].m.offset);
  272 +
  273 + if (MAP_FAILED == buffers[i].start[j]) {
  274 + /* If you do not exit here you should unmap() and free()
  275 + the buffers and planes mapped so far. */
  276 + perror("mmap");
  277 + exit(EXIT_FAILURE);
  278 + }
  279 + }
  280 +}
  281 +
  282 +/* Cleanup. */
  283 +
  284 +for (i = 0; i &lt; reqbuf.count; i++)
  285 + for (j = 0; j &lt; FMT_NUM_PLANES; j++)
  286 + munmap(buffers[i].start[j], buffers[i].length[j]);
  287 + </programlisting>
  288 + </example>
  289 +
204 290 <para>Conceptually streaming drivers maintain two buffer queues, an incoming
205 291 and an outgoing queue. They separate the synchronous capture or output
206 292 operation locked to a video clock from the application which is
207 293  
... ... @@ -286,13 +372,13 @@
286 372 determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
287 373  
288 374 <para>This I/O method combines advantages of the read/write and
289   -memory mapping methods. Buffers are allocated by the application
  375 +memory mapping methods. Buffers (planes) are allocated by the application
290 376 itself, and can reside for example in virtual or shared memory. Only
291 377 pointers to data are exchanged, these pointers and meta-information
292   -are passed in &v4l2-buffer;. The driver must be switched
293   -into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the
294   -desired buffer type. No buffers are allocated beforehands,
295   -consequently they are not indexed and cannot be queried like mapped
  378 +are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
  379 +The driver must be switched into user pointer I/O mode by calling the
  380 +&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
  381 +beforehand, consequently they are not indexed and cannot be queried like mapped
296 382 buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
297 383  
298 384 <example>
... ... @@ -316,7 +402,7 @@
316 402 </programlisting>
317 403 </example>
318 404  
319   - <para>Buffer addresses and sizes are passed on the fly with the
  405 + <para>Buffer (plane) addresses and sizes are passed on the fly with the
320 406 &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
321 407 applications can pass different addresses and sizes at each
322 408 <constant>VIDIOC_QBUF</constant> call. If required by the hardware the
... ... @@ -396,11 +482,18 @@
396 482 <title>Buffers</title>
397 483  
398 484 <para>A buffer contains data exchanged by application and
399   -driver using one of the Streaming I/O methods. Only pointers to
400   -buffers are exchanged, the data itself is not copied. These pointers,
401   -together with meta-information like timestamps or field parity, are
402   -stored in a struct <structname>v4l2_buffer</structname>, argument to
403   -the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para>
  485 +driver using one of the Streaming I/O methods. In the multi-planar API, the
  486 +data is held in planes, while the buffer structure acts as a container
  487 +for the planes. Only pointers to buffers (planes) are exchanged, the data
  488 +itself is not copied. These pointers, together with meta-information like
  489 +timestamps or field parity, are stored in a struct
  490 +<structname>v4l2_buffer</structname>, argument to
  491 +the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
  492 +In the multi-planar API, some plane-specific members of struct
  493 +<structname>v4l2_buffer</structname>, such as pointers and sizes for each
  494 +plane, are stored in struct <structname>v4l2_plane</structname> instead.
  495 +In that case, struct <structname>v4l2_buffer</structname> contains an array of
  496 +plane structures.</para>
404 497  
405 498 <para>Nominally timestamps refer to the first data byte transmitted.
406 499 In practice however the wide range of hardware covered by the V4L2 API
407 500  
408 501  
409 502  
... ... @@ -551,26 +644,40 @@
551 644 <entry></entry>
552 645 <entry>__u32</entry>
553 646 <entry><structfield>offset</structfield></entry>
554   - <entry>When <structfield>memory</structfield> is
555   -<constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer
556   -from the start of the device memory. The value is returned by the
557   -driver and apart of serving as parameter to the &func-mmap; function
558   -not useful for applications. See <xref linkend="mmap" /> for details.</entry>
  647 + <entry>For the single-planar API and when
  648 +<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
  649 +is the offset of the buffer from the start of the device memory. The value is
  650 +returned by the driver and apart of serving as parameter to the &func-mmap;
  651 +function not useful for applications. See <xref linkend="mmap" /> for details
  652 + </entry>
559 653 </row>
560 654 <row>
561 655 <entry></entry>
562 656 <entry>unsigned long</entry>
563 657 <entry><structfield>userptr</structfield></entry>
564   - <entry>When <structfield>memory</structfield> is
565   -<constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the
566   -buffer (casted to unsigned long type) in virtual memory, set by the
567   -application. See <xref linkend="userp" /> for details.</entry>
  658 + <entry>For the single-planar API and when
  659 +<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
  660 +this is a pointer to the buffer (casted to unsigned long type) in virtual
  661 +memory, set by the application. See <xref linkend="userp" /> for details.
  662 + </entry>
568 663 </row>
569 664 <row>
  665 + <entry></entry>
  666 + <entry>struct v4l2_plane</entry>
  667 + <entry><structfield>*planes</structfield></entry>
  668 + <entry>When using the multi-planar API, contains a userspace pointer
  669 + to an array of &v4l2-plane;. The size of the array should be put
  670 + in the <structfield>length</structfield> field of this
  671 + <structname>v4l2_buffer</structname> structure.</entry>
  672 + </row>
  673 + <row>
570 674 <entry>__u32</entry>
571 675 <entry><structfield>length</structfield></entry>
572 676 <entry></entry>
573   - <entry>Size of the buffer (not the payload) in bytes.</entry>
  677 + <entry>Size of the buffer (not the payload) in bytes for the
  678 + single-planar API. For the multi-planar API should contain the
  679 + number of elements in the <structfield>planes</structfield> array.
  680 + </entry>
574 681 </row>
575 682 <row>
576 683 <entry>__u32</entry>
... ... @@ -596,6 +703,66 @@
596 703 </tgroup>
597 704 </table>
598 705  
  706 + <table frame="none" pgwide="1" id="v4l2-plane">
  707 + <title>struct <structname>v4l2_plane</structname></title>
  708 + <tgroup cols="4">
  709 + &cs-ustr;
  710 + <tbody valign="top">
  711 + <row>
  712 + <entry>__u32</entry>
  713 + <entry><structfield>bytesused</structfield></entry>
  714 + <entry></entry>
  715 + <entry>The number of bytes occupied by data in the plane
  716 + (its payload).</entry>
  717 + </row>
  718 + <row>
  719 + <entry>__u32</entry>
  720 + <entry><structfield>length</structfield></entry>
  721 + <entry></entry>
  722 + <entry>Size in bytes of the plane (not its payload).</entry>
  723 + </row>
  724 + <row>
  725 + <entry>union</entry>
  726 + <entry><structfield>m</structfield></entry>
  727 + <entry></entry>
  728 + <entry></entry>
  729 + </row>
  730 + <row>
  731 + <entry></entry>
  732 + <entry>__u32</entry>
  733 + <entry><structfield>mem_offset</structfield></entry>
  734 + <entry>When the memory type in the containing &v4l2-buffer; is
  735 + <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
  736 + should be passed to &func-mmap;, similar to the
  737 + <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
  738 + </row>
  739 + <row>
  740 + <entry></entry>
  741 + <entry>__unsigned long</entry>
  742 + <entry><structfield>userptr</structfield></entry>
  743 + <entry>When the memory type in the containing &v4l2-buffer; is
  744 + <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
  745 + pointer to the memory allocated for this plane by an application.
  746 + </entry>
  747 + </row>
  748 + <row>
  749 + <entry>__u32</entry>
  750 + <entry><structfield>data_offset</structfield></entry>
  751 + <entry></entry>
  752 + <entry>Offset in bytes to video data in the plane, if applicable.
  753 + </entry>
  754 + </row>
  755 + <row>
  756 + <entry>__u32</entry>
  757 + <entry><structfield>reserved[11]</structfield></entry>
  758 + <entry></entry>
  759 + <entry>Reserved for future use. Should be zeroed by an
  760 + application.</entry>
  761 + </row>
  762 + </tbody>
  763 + </tgroup>
  764 + </table>
  765 +
599 766 <table frame="none" pgwide="1" id="v4l2-buf-type">
600 767 <title>enum v4l2_buf_type</title>
601 768 <tgroup cols="3">
602 769  
603 770  
... ... @@ -604,13 +771,27 @@
604 771 <row>
605 772 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
606 773 <entry>1</entry>
607   - <entry>Buffer of a video capture stream, see <xref
  774 + <entry>Buffer of a single-planar video capture stream, see <xref
608 775 linkend="capture" />.</entry>
609 776 </row>
610 777 <row>
  778 + <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
  779 + </entry>
  780 + <entry>9</entry>
  781 + <entry>Buffer of a multi-planar video capture stream, see <xref
  782 + linkend="capture" />.</entry>
  783 + </row>
  784 + <row>
611 785 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
612 786 <entry>2</entry>
613   - <entry>Buffer of a video output stream, see <xref
  787 + <entry>Buffer of a single-planar video output stream, see <xref
  788 + linkend="output" />.</entry>
  789 + </row>
  790 + <row>
  791 + <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
  792 + </entry>
  793 + <entry>10</entry>
  794 + <entry>Buffer of a multi-planar video output stream, see <xref
614 795 linkend="output" />.</entry>
615 796 </row>
616 797 <row>
Documentation/DocBook/v4l/pixfmt.xml
Diff comments   View file @ 53b5d57
... ... @@ -2,12 +2,16 @@
2 2  
3 3 <para>The V4L2 API was primarily designed for devices exchanging
4 4 image data with applications. The
5   -<structname>v4l2_pix_format</structname> structure defines the format
6   -and layout of an image in memory. Image formats are negotiated with
7   -the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
  5 +<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane
  6 +</structname> structures define the format and layout of an image in memory.
  7 +The former is used with the single-planar API, while the latter is used with the
  8 +multi-planar version (see <xref linkend="planar-apis"/>). Image formats are
  9 +negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
8 10 capturing and output, for overlay frame buffer formats see also
9 11 &VIDIOC-G-FBUF;.)</para>
10 12  
  13 +<section>
  14 + <title>Single-planar format structure</title>
11 15 <table pgwide="1" frame="none" id="v4l2-pix-format">
12 16 <title>struct <structname>v4l2_pix_format</structname></title>
13 17 <tgroup cols="3">
14 18  
... ... @@ -106,7 +110,99 @@
106 110 </tbody>
107 111 </tgroup>
108 112 </table>
  113 +</section>
109 114  
  115 +<section>
  116 + <title>Multi-planar format structures</title>
  117 + <para>The <structname>v4l2_plane_pix_format</structname> structures define
  118 + size and layout for each of the planes in a multi-planar format.
  119 + The <structname>v4l2_pix_format_mplane</structname> structure contains
  120 + information common to all planes (such as image width and height) and
  121 + an array of <structname>v4l2_plane_pix_format</structname> structures,
  122 + describing all planes of that format.</para>
  123 + <table pgwide="1" frame="none" id="v4l2-plane-pix-format">
  124 + <title>struct <structname>vl42_plane_pix_format</structname></title>
  125 + <tgroup cols="3">
  126 + &cs-str;
  127 + <tbody valign="top">
  128 + <row>
  129 + <entry>__u32</entry>
  130 + <entry><structfield>sizeimage</structfield></entry>
  131 + <entry>Maximum size in bytes required for image data in this plane.
  132 + </entry>
  133 + </row>
  134 + <row>
  135 + <entry>__u16</entry>
  136 + <entry><structfield>bytesperline</structfield></entry>
  137 + <entry>Distance in bytes between the leftmost pixels in two adjacent
  138 + lines.</entry>
  139 + </row>
  140 + <row>
  141 + <entry>__u16</entry>
  142 + <entry><structfield>reserved[7]</structfield></entry>
  143 + <entry>Reserved for future extensions. Should be zeroed by the
  144 + application.</entry>
  145 + </row>
  146 + </tbody>
  147 + </tgroup>
  148 + </table>
  149 + <table pgwide="1" frame="none" id="v4l2-pix-format-mplane">
  150 + <title>struct <structname>v4l2_pix_format_mplane</structname></title>
  151 + <tgroup cols="3">
  152 + &cs-str;
  153 + <tbody valign="top">
  154 + <row>
  155 + <entry>__u32</entry>
  156 + <entry><structfield>width</structfield></entry>
  157 + <entry>Image width in pixels.</entry>
  158 + </row>
  159 + <row>
  160 + <entry>__u32</entry>
  161 + <entry><structfield>height</structfield></entry>
  162 + <entry>Image height in pixels.</entry>
  163 + </row>
  164 + <row>
  165 + <entry>__u32</entry>
  166 + <entry><structfield>pixelformat</structfield></entry>
  167 + <entry>The pixel format. Both single- and multi-planar four character
  168 +codes can be used.</entry>
  169 + </row>
  170 + <row>
  171 + <entry>&v4l2-field;</entry>
  172 + <entry><structfield>field</structfield></entry>
  173 + <entry>See &v4l2-pix-format;.</entry>
  174 + </row>
  175 + <row>
  176 + <entry>&v4l2-colorspace;</entry>
  177 + <entry><structfield>colorspace</structfield></entry>
  178 + <entry>See &v4l2-pix-format;.</entry>
  179 + </row>
  180 + <row>
  181 + <entry>&v4l2-plane-pix-format;</entry>
  182 + <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry>
  183 + <entry>An array of structures describing format of each plane this
  184 + pixel format consists of. The number of valid entries in this array
  185 + has to be put in the <structfield>num_planes</structfield>
  186 + field.</entry>
  187 + </row>
  188 + <row>
  189 + <entry>__u8</entry>
  190 + <entry><structfield>num_planes</structfield></entry>
  191 + <entry>Number of planes (i.e. separate memory buffers) for this format
  192 + and the number of valid entries in the
  193 + <structfield>plane_fmt</structfield> array.</entry>
  194 + </row>
  195 + <row>
  196 + <entry>__u8</entry>
  197 + <entry><structfield>reserved[11]</structfield></entry>
  198 + <entry>Reserved for future extensions. Should be zeroed by the
  199 + application.</entry>
  200 + </row>
  201 + </tbody>
  202 + </tgroup>
  203 + </table>
  204 +</section>
  205 +
110 206 <section>
111 207 <title>Standard Image Formats</title>
112 208  
113 209  
... ... @@ -142,11 +238,19 @@
142 238 has just as many pad bytes after it as the other rows.</para>
143 239  
144 240 <para>In V4L2 each format has an identifier which looks like
145   -<constant>PIX_FMT_XXX</constant>, defined in the <filename>videodev2.h</filename>
146   -header file. These identifiers
147   -represent <link linkend="v4l2-fourcc">four character codes</link>
  241 +<constant>PIX_FMT_XXX</constant>, defined in the <link
  242 +linkend="videodev">videodev.h</link> header file. These identifiers
  243 +represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
148 244 which are also listed below, however they are not the same as those
149 245 used in the Windows world.</para>
  246 +
  247 + <para>For some formats, data is stored in separate, discontiguous
  248 +memory buffers. Those formats are identified by a separate set of FourCC codes
  249 +and are referred to as "multi-planar formats". For example, a YUV422 frame is
  250 +normally stored in one memory buffer, but it can also be placed in two or three
  251 +separate buffers, with Y component in one buffer and CbCr components in another
  252 +in the 2-planar version or with each component in its own buffer in the
  253 +3-planar case. Those sub-buffers are referred to as "planes".</para>
150 254 </section>
151 255  
152 256 <section id="colorspaces">
Documentation/DocBook/v4l/planar-apis.xml
Diff comments   View file @ 53b5d57
  1 +<section id="planar-apis">
  2 + <title>Single- and multi-planar APIs</title>
  3 +
  4 + <para>Some devices require data for each input or output video frame
  5 + to be placed in discontiguous memory buffers. In such cases one
  6 + video frame has to be addressed using more than one memory address, i.e. one
  7 + pointer per "plane". A plane is a sub-buffer of current frame. For examples
  8 + of such formats see <xref linkend="pixfmt" />.</para>
  9 +
  10 + <para>Initially, V4L2 API did not support multi-planar buffers and a set of
  11 + extensions has been introduced to handle them. Those extensions constitute
  12 + what is being referred to as the "multi-planar API".</para>
  13 +
  14 + <para>Some of the V4L2 API calls and structures are interpreted differently,
  15 + depending on whether single- or multi-planar API is being used. An application
  16 + can choose whether to use one or the other by passing a corresponding buffer
  17 + type to its ioctl calls. Multi-planar versions of buffer types are suffixed with
  18 + an `_MPLANE' string. For a list of available multi-planar buffer types
  19 + see &v4l2-buf-type;.
  20 + </para>
  21 +
  22 + <section>
  23 + <title>Multi-planar formats</title>
  24 + <para>Multi-planar API introduces new multi-planar formats. Those formats
  25 + use a separate set of FourCC codes. It is important to distinguish between
  26 + the multi-planar API and a multi-planar format. Multi-planar API calls can
  27 + handle all single-planar formats as well, while the single-planar API cannot
  28 + handle multi-planar formats. Applications do not have to switch between APIs
  29 + when handling both single- and multi-planar devices and should use the
  30 + multi-planar API version for both single- and multi-planar formats.
  31 + Drivers that do not support multi-planar API can still be handled with it,
  32 + utilizing a compatibility layer built into standard V4L2 ioctl handling.
  33 + </para>
  34 + </section>
  35 +
  36 + <section>
  37 + <title>Single and multi-planar API compatibility layer</title>
  38 + <para>In most cases<footnote><para>The compatibility layer does not cover
  39 + drivers that do not use video_ioctl2() call.</para></footnote>, applications
  40 + can use the multi-planar API with older drivers that support
  41 + only its single-planar version and vice versa. Appropriate conversion is
  42 + done seamlessly for both applications and drivers in the V4L2 core. The
  43 + general rule of thumb is: as long as an application uses formats that
  44 + a driver supports, it can use either API (although use of multi-planar
  45 + formats is only possible with the multi-planar API). The list of formats
  46 + supported by a driver can be obtained using the &VIDIOC-ENUM-FMT; call.
  47 + It is possible, but discouraged, for a driver or an application to support
  48 + and use both versions of the API.</para>
  49 + </section>
  50 +
  51 + <section>
  52 + <title>Calls that distinguish between single and multi-planar APIs</title>
  53 + <variablelist>
  54 + <varlistentry>
  55 + <term>&VIDIOC-QUERYCAP;</term>
  56 + <listitem>Two additional multi-planar capabilities are added. They can
  57 + be set together with non-multi-planar ones for devices that handle
  58 + both single- and multi-planar formats.</listitem>
  59 + </varlistentry>
  60 + <varlistentry>
  61 + <term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term>
  62 + <listitem>New structures for describing multi-planar formats are added:
  63 + &v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may
  64 + define new multi-planar formats, which have distinct FourCC codes from
  65 + the existing single-planar ones.
  66 + </listitem>
  67 + </varlistentry>
  68 + <varlistentry>
  69 + <term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term>
  70 + <listitem>A new &v4l2-plane; structure for describing planes is added.
  71 + Arrays of this structure are passed in the new
  72 + <structfield>m.planes</structfield> field of &v4l2-buffer;.
  73 + </listitem>
  74 + </varlistentry>
  75 + <varlistentry>
  76 + <term>&VIDIOC-REQBUFS;</term>
  77 + <listitem>Will allocate multi-planar buffers as requested.</listitem>
  78 + </varlistentry>
  79 + </variablelist>
  80 + </section>
  81 +</section>
Documentation/DocBook/v4l/v4l2.xml
Diff comments   View file @ 53b5d57
... ... @@ -85,6 +85,17 @@
85 85 </address>
86 86 </affiliation>
87 87 </author>
  88 +
  89 + <author>
  90 + <firstname>Pawel</firstname>
  91 + <surname>Osciak</surname>
  92 + <contrib>Designed and documented the multi-planar API.</contrib>
  93 + <affiliation>
  94 + <address>
  95 + <email>pawel AT osciak.com</email>
  96 + </address>
  97 + </affiliation>
  98 + </author>
88 99 </authorgroup>
89 100  
90 101 <copyright>
... ... @@ -102,7 +113,8 @@
102 113 <year>2010</year>
103 114 <year>2011</year>
104 115 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
105   -Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab</holder>
  116 +Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
  117 + Pawel Osciak</holder>
106 118 </copyright>
107 119 <legalnotice>
108 120 <para>Except when explicitly stated as GPL, programming examples within
... ... @@ -114,6 +126,13 @@
114 126 structs, ioctls) must be noted in more detail in the history chapter
115 127 (compat.xml), along with the possible impact on existing drivers and
116 128 applications. -->
  129 +
  130 + <revision>
  131 + <revnumber>2.6.38</revnumber>
  132 + <authorinitials>po</authorinitials>
  133 + <revremark>Added the <link linkend="planar-apis">multi-planar API</link>.
  134 + </revremark>
  135 + </revision>
117 136  
118 137 <revision>
119 138 <revnumber>2.6.37</revnumber>
Documentation/DocBook/v4l/vidioc-enum-fmt.xml
Diff comments   View file @ 53b5d57
... ... @@ -76,7 +76,9 @@
76 76 <entry>Type of the data stream, set by the application.
77 77 Only these types are valid here:
78 78 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
  79 +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
79 80 <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
  81 +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>,
80 82 <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
81 83 defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
82 84 and higher.</entry>
Documentation/DocBook/v4l/vidioc-g-fmt.xml
Diff comments   View file @ 53b5d57
... ... @@ -60,11 +60,13 @@
60 60 <structfield>type</structfield> field of a struct
61 61 <structname>v4l2_format</structname> to the respective buffer (stream)
62 62 type. For example video capture devices use
63   -<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application
  63 +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
  64 +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
64 65 calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
65 66 this structure the driver fills the respective member of the
66 67 <structfield>fmt</structfield> union. In case of video capture devices
67   -that is the &v4l2-pix-format; <structfield>pix</structfield> member.
  68 +that is either the &v4l2-pix-format; <structfield>pix</structfield> or
  69 +the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
68 70 When the requested buffer type is not supported drivers return an
69 71 &EINVAL;.</para>
70 72  
... ... @@ -131,6 +133,15 @@
131 133 <entry>Definition of an image format, see <xref
132 134 linkend="pixfmt" />, used by video capture and output
133 135 devices.</entry>
  136 + </row>
  137 + <row>
  138 + <entry></entry>
  139 + <entry>&v4l2-pix-format-mplane;</entry>
  140 + <entry><structfield>pix_mp</structfield></entry>
  141 + <entry>Definition of an image format, see <xref
  142 + linkend="pixfmt" />, used by video capture and output
  143 +devices that support the <link linkend="planar-apis">multi-planar
  144 +version of the API</link>.</entry>
134 145 </row>
135 146 <row>
136 147 <entry></entry>
Documentation/DocBook/v4l/vidioc-qbuf.xml
Diff comments   View file @ 53b5d57
... ... @@ -64,7 +64,8 @@
64 64 contents of the struct <structname>v4l2_buffer</structname> returned
65 65 by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
66 66 intended for output (<structfield>type</structfield> is
67   -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
  67 +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
  68 +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or
68 69 <constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
69 70 initialize the <structfield>bytesused</structfield>,
70 71 <structfield>field</structfield> and
... ... @@ -75,7 +76,11 @@
75 76 input, then <structfield>flags</structfield> should be set to
76 77 <constant>V4L2_BUF_FLAG_INPUT</constant> and the field
77 78 <structfield>input</structfield> must be initialized to the desired input.
78   -The <structfield>reserved</structfield> field must be set to 0.
  79 +The <structfield>reserved</structfield> field must be set to 0. When using
  80 +the <link linkend="planar-apis">multi-planar API</link>, the
  81 +<structfield>m.planes</structfield> field must contain a userspace pointer
  82 +to a filled-in array of &v4l2-plane; and the <structfield>length</structfield>
  83 +field must be set to the number of elements in that array.
79 84 </para>
80 85  
81 86 <para>To enqueue a <link linkend="mmap">memory mapped</link>
... ... @@ -93,10 +98,13 @@
93 98 buffer applications set the <structfield>memory</structfield>
94 99 field to <constant>V4L2_MEMORY_USERPTR</constant>, the
95 100 <structfield>m.userptr</structfield> field to the address of the
96   -buffer and <structfield>length</structfield> to its size.
97   -When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
98   -structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
99   -flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and
  101 +buffer and <structfield>length</structfield> to its size. When the multi-planar
  102 +API is used, <structfield>m.userptr</structfield> and
  103 +<structfield>length</structfield> members of the passed array of &v4l2-plane;
  104 +have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with
  105 +a pointer to this structure the driver sets the
  106 +<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
  107 +<constant>V4L2_BUF_FLAG_MAPPED</constant> and
100 108 <constant>V4L2_BUF_FLAG_DONE</constant> flags in the
101 109 <structfield>flags</structfield> field, or it returns an error code.
102 110 This ioctl locks the memory pages of the buffer in physical memory,
... ... @@ -115,7 +123,9 @@
115 123 <constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
116 124 field. It indicates a non-critical (recoverable) streaming error. In such case
117 125 the application may continue as normal, but should be aware that data in the
118   -dequeued buffer might be corrupted.</para>
  126 +dequeued buffer might be corrupted. When using the multi-planar API, the
  127 +planes array does not have to be passed; the <structfield>m.planes</structfield>
  128 +member must be set to NULL in that case.</para>
119 129  
120 130 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
121 131 buffer is in the outgoing queue. When the
Documentation/DocBook/v4l/vidioc-querybuf.xml
Diff comments   View file @ 53b5d57
... ... @@ -61,6 +61,10 @@
61 61 to the number of buffers allocated with &VIDIOC-REQBUFS;
62 62 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
63 63 The <structfield>reserved</structfield> field should to set to 0.
  64 +When using the <link linkend="planar-apis">multi-planar API</link>, the
  65 +<structfield>m.planes</structfield> field must contain a userspace pointer to an
  66 +array of &v4l2-plane; and the <structfield>length</structfield> field has
  67 +to be set to the number of elements in that array.
64 68 After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
65 69 this structure drivers return an error code or fill the rest of
66 70 the structure.</para>
67 71  
... ... @@ -70,11 +74,13 @@
70 74 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
71 75 <constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The
72 76 <structfield>memory</structfield> field will be set to the current
73   -I/O method, the <structfield>m.offset</structfield>
  77 +I/O method. For the single-planar API, the <structfield>m.offset</structfield>
74 78 contains the offset of the buffer from the start of the device memory,
75   -the <structfield>length</structfield> field its size. The driver may
76   -or may not set the remaining fields and flags, they are meaningless in
77   -this context.</para>
  79 +the <structfield>length</structfield> field its size. For the multi-planar API,
  80 +fields <structfield>m.mem_offset</structfield> and
  81 +<structfield>length</structfield> in the <structfield>m.planes</structfield>
  82 +array elements will be used instead. The driver may or may not set the remaining
  83 +fields and flags, they are meaningless in this context.</para>
78 84  
79 85 <para>The <structname>v4l2_buffer</structname> structure is
80 86 specified in <xref linkend="buffer" />.</para>
Documentation/DocBook/v4l/vidioc-querycap.xml
Diff comments   View file @ 53b5d57
... ... @@ -142,14 +142,30 @@
142 142 <row>
143 143 <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
144 144 <entry>0x00000001</entry>
145   - <entry>The device supports the <link
146   -linkend="capture">Video Capture</link> interface.</entry>
  145 + <entry>The device supports single-planar formats through the <link
  146 +linkend="capture">Video Capture</link> interface. An application can use either
  147 +<link linkend="planar-apis">the single or the multi-planar API</link>.</entry>
147 148 </row>
148 149 <row>
  150 + <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry>
  151 + <entry>0x00001000</entry>
  152 + <entry>The device supports multi-planar formats through the <link
  153 +linkend="capture">Video Capture</link> interface. An application has to use the
  154 +<link linkend="planar-apis">multi-planar API</link>.</entry>
  155 + </row>
  156 + <row>
149 157 <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry>
150 158 <entry>0x00000002</entry>
151   - <entry>The device supports the <link
152   -linkend="output">Video Output</link> interface.</entry>
  159 + <entry>The device supports single-planar formats through the <link
  160 +linkend="output">Video Output</link> interface. An application can use either
  161 +<link linkend="planar-apis">the single or the multi-planar API</link>.</entry>
  162 + </row>
  163 + <row>
  164 + <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry>
  165 + <entry>0x00002000</entry>
  166 + <entry>The device supports multi-planar formats through the <link
  167 +linkend="output">Video Output</link> interface. An application has to use the
  168 +<link linkend="planar-apis">multi-planar API</link>.</entry>
153 169 </row>
154 170 <row>
155 171 <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>