diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l')
74 files changed, 868 insertions, 573 deletions
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index afc8a0dd260..cea6fd3ed42 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -178,11 +178,3 @@ in the frequency range from 87,5 to 108,0 MHz</title> </biblioentry> </bibliography> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index a86f7a04552..c79278acfb0 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -1168,6 +1168,8 @@ dheight = format.fmt.pix.height; </section> </section> + &sub-selection-api; + <section id="streaming-par"> <title>Streaming Parameters</title> @@ -1195,11 +1197,3 @@ separate parameters for input and output devices.</para> <para>These ioctls are optional, drivers need not implement them. If so, they return the &EINVAL;.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index b68698f96e7..c736380b464 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -1082,7 +1082,7 @@ until the time in the timestamp field has arrived. I would like to follow SGI's lead, and adopt a multimedia timestamping system like their UST (Unadjusted System Time). See http://web.archive.org/web/*/http://reality.sgi.com -/cpirazzi_engr/lg/time/intro.html. +/cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are 64-bit signed integers (not struct timeval's) and given in nanosecond units. The UST clock starts at zero when the system is booted and runs continuously and @@ -2376,6 +2376,23 @@ that used it. It was originally scheduled for removal in 2.6.35. <listitem> <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para> </listitem> + <listitem> + <para>Add selection API for extended control over cropping and +composing. Does not affect the compatibility of current drivers and +applications. See <link linkend="selection-api"> selection API </link> for +details.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.3</title> + <orderedlist> + <listitem> + <para>Added <constant>V4L2_CID_ALPHA_COMPONENT</constant> control + to the <link linkend="control">User controls class</link>. + </para> + </listitem> </orderedlist> </section> @@ -2489,6 +2506,9 @@ ioctls.</para> <listitem> <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para> </listitem> + <listitem> + <para>Selection API. <xref linkend="selection-api" /></para> + </listitem> </itemizedlist> </section> @@ -2507,11 +2527,3 @@ interfaces and should not be implemented in new drivers.</para> </itemizedlist> </section> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 3bc5ee8b2c7..a1be37897ad 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -324,12 +324,6 @@ minimum value disables backlight compensation.</entry> (usually a microscope).</entry> </row> <row> - <entry><constant>V4L2_CID_LASTP1</constant></entry> - <entry></entry> - <entry>End of the predefined control IDs (currently -<constant>V4L2_CID_ILLUMINATORS_2</constant> + 1).</entry> - </row> - <row> <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_CAPTURE</constant></entry> <entry>integer</entry> <entry>This is a read-only control that can be read by the application @@ -345,6 +339,25 @@ and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS. The value is the minimum number of OUTPUT buffers that is necessary for hardware to work.</entry> </row> + <row id="v4l2-alpha-component"> + <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry> + <entry>integer</entry> + <entry> Sets the alpha color component on the capture device or on + the capture buffer queue of a mem-to-mem device. When a mem-to-mem + device produces frame format that includes an alpha component + (e.g. <link linkend="rgb-formats">packed RGB image formats</link>) + and the alpha value is not defined by the mem-to-mem input data + this control lets you select the alpha component value of all + pixels. It is applicable to any pixel format that contains an alpha + component. + </entry> + </row> + <row> + <entry><constant>V4L2_CID_LASTP1</constant></entry> + <entry></entry> + <entry>End of the predefined control IDs (currently + <constant>V4L2_CID_ALPHA_COMPONENT</constant> + 1).</entry> + </row> <row> <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry> <entry></entry> @@ -3329,6 +3342,16 @@ interface and may change in the future.</para> <entry>The short circuit protection of the flash controller has been triggered.</entry> </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry> + <entry>Current in the LED power supply has exceeded the limit + specific to the flash controller.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry> + <entry>The flash controller has detected a short or open + circuit condition on the indicator LED.</entry> + </row> </tbody> </entrytbl> </row> @@ -3357,11 +3380,3 @@ interface and may change in the future.</para> </section> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "common.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-capture.xml b/Documentation/DocBook/media/v4l/dev-capture.xml index 2237c661f26..e1c5f9406d6 100644 --- a/Documentation/DocBook/media/v4l/dev-capture.xml +++ b/Documentation/DocBook/media/v4l/dev-capture.xml @@ -108,11 +108,3 @@ linkend="mmap">memory mapping</link> or <link linkend="userp">user pointer</link>) I/O. See <xref linkend="io" /> for details.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-codec.xml b/Documentation/DocBook/media/v4l/dev-codec.xml index 6e156dc45b9..dca0ecd54dc 100644 --- a/Documentation/DocBook/media/v4l/dev-codec.xml +++ b/Documentation/DocBook/media/v4l/dev-codec.xml @@ -16,11 +16,3 @@ Applications send data to be converted to the driver through a I/O.</para> <para>[to do]</para> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-effect.xml b/Documentation/DocBook/media/v4l/dev-effect.xml index 9c243beba0e..2350a67c071 100644 --- a/Documentation/DocBook/media/v4l/dev-effect.xml +++ b/Documentation/DocBook/media/v4l/dev-effect.xml @@ -15,11 +15,3 @@ receive the result data either with &func-read; and &func-write; functions, or through the streaming I/O mechanism.</para> <para>[to do]</para> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-event.xml b/Documentation/DocBook/media/v4l/dev-event.xml index f14ae3fe107..19f4becfae3 100644 --- a/Documentation/DocBook/media/v4l/dev-event.xml +++ b/Documentation/DocBook/media/v4l/dev-event.xml @@ -41,11 +41,3 @@ intermediate step leading up to that information. See the documentation for the event you want to subscribe to whether this is applicable for that event or not.</para> </listitem> </orderedlist></para> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml index c9a68a2ccd3..479d9433869 100644 --- a/Documentation/DocBook/media/v4l/dev-osd.xml +++ b/Documentation/DocBook/media/v4l/dev-osd.xml @@ -154,11 +154,3 @@ data flow. For more information see <xref linkend="crop" />.</para> however the framebuffer interface of the driver may support the <constant>FBIOBLANK</constant> ioctl.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-output.xml b/Documentation/DocBook/media/v4l/dev-output.xml index 919e22c5385..9130a3dc788 100644 --- a/Documentation/DocBook/media/v4l/dev-output.xml +++ b/Documentation/DocBook/media/v4l/dev-output.xml @@ -104,11 +104,3 @@ linkend="mmap">memory mapping</link> or <link linkend="userp">user pointer</link>) I/O. See <xref linkend="io" /> for details.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-overlay.xml b/Documentation/DocBook/media/v4l/dev-overlay.xml index 92513cf7915..40d1d768143 100644 --- a/Documentation/DocBook/media/v4l/dev-overlay.xml +++ b/Documentation/DocBook/media/v4l/dev-overlay.xml @@ -369,11 +369,3 @@ reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject <para>To start or stop the frame buffer overlay applications call the &VIDIOC-OVERLAY; ioctl.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-radio.xml b/Documentation/DocBook/media/v4l/dev-radio.xml index 73aa90b45b3..3e6ac73b36a 100644 --- a/Documentation/DocBook/media/v4l/dev-radio.xml +++ b/Documentation/DocBook/media/v4l/dev-radio.xml @@ -47,11 +47,3 @@ depending on the selected frequency. The &VIDIOC-G-TUNER; or &VIDIOC-G-MODULATOR; ioctl reports the supported frequency range.</para> </section> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml index c5a70bdfaf2..b788c72c885 100644 --- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml @@ -337,11 +337,3 @@ an &EBUSY; if the required hardware resources are temporarily unavailable, for example the device is already in use by another process.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml index 2427f54397e..38883a419e6 100644 --- a/Documentation/DocBook/media/v4l/dev-rds.xml +++ b/Documentation/DocBook/media/v4l/dev-rds.xml @@ -29,10 +29,10 @@ returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> field of &v4l2-tuner;. If the driver only passes RDS blocks without interpreting the data -the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be +the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set, see <link linkend="reading-rds-data">Reading RDS data</link>. For future use the -flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> has also been +flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> has also been defined. However, a driver for a radio tuner with this capability does not yet exist, so if you are planning to write such a driver you should discuss this on the linux-media mailing list: &v4l-ml;.</para> @@ -52,9 +52,9 @@ field of &v4l2-modulator;. In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant> bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;. If the driver only passes RDS blocks without interpreting the data -the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be set. If the +the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set. If the tuner is capable of handling RDS entities like program identification codes and radio -text, the flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> should be set, +text, the flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> should be set, see <link linkend="writing-rds-data">Writing RDS data</link> and <link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para> </section> @@ -194,11 +194,3 @@ as follows:</para> </tgroup> </table> </section> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml index 69e789fa7f7..548f8ea28de 100644 --- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml @@ -697,12 +697,3 @@ Sliced VBI services</link> for a description of the line payload.</entry> </section> </section> - - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-teletext.xml b/Documentation/DocBook/media/v4l/dev-teletext.xml index 414b1cfff9f..bd21c64d70f 100644 --- a/Documentation/DocBook/media/v4l/dev-teletext.xml +++ b/Documentation/DocBook/media/v4l/dev-teletext.xml @@ -27,11 +27,3 @@ kernel 2.6.37.</para> <para>Modern devices all use the <link linkend="raw-vbi">raw</link> or <link linkend="sliced">sliced</link> VBI API.</para> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/driver.xml b/Documentation/DocBook/media/v4l/driver.xml index 1f7eea5c4ec..eacafe312cd 100644 --- a/Documentation/DocBook/media/v4l/driver.xml +++ b/Documentation/DocBook/media/v4l/driver.xml @@ -198,11 +198,3 @@ devices with the videodev module.</para> <para>to do</para> </section> --> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-close.xml b/Documentation/DocBook/media/v4l/func-close.xml index dfb41cbbbec..232920d2f3c 100644 --- a/Documentation/DocBook/media/v4l/func-close.xml +++ b/Documentation/DocBook/media/v4l/func-close.xml @@ -60,11 +60,3 @@ descriptor.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-ioctl.xml b/Documentation/DocBook/media/v4l/func-ioctl.xml index 2de64be706f..4394184a1a6 100644 --- a/Documentation/DocBook/media/v4l/func-ioctl.xml +++ b/Documentation/DocBook/media/v4l/func-ioctl.xml @@ -69,11 +69,3 @@ their respective function and parameters are specified in <xref the parameter remains unmodified.</para> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-mmap.xml b/Documentation/DocBook/media/v4l/func-mmap.xml index 786732b64bb..f31ad71bf30 100644 --- a/Documentation/DocBook/media/v4l/func-mmap.xml +++ b/Documentation/DocBook/media/v4l/func-mmap.xml @@ -181,11 +181,3 @@ complete the request.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-munmap.xml b/Documentation/DocBook/media/v4l/func-munmap.xml index e2c4190f9bb..860d49ca54a 100644 --- a/Documentation/DocBook/media/v4l/func-munmap.xml +++ b/Documentation/DocBook/media/v4l/func-munmap.xml @@ -74,11 +74,3 @@ mapped yet.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-open.xml b/Documentation/DocBook/media/v4l/func-open.xml index 7595d07a8c7..cf64e207c3e 100644 --- a/Documentation/DocBook/media/v4l/func-open.xml +++ b/Documentation/DocBook/media/v4l/func-open.xml @@ -111,11 +111,3 @@ system has been reached.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml index ec3c718f596..85cad8bff5b 100644 --- a/Documentation/DocBook/media/v4l/func-poll.xml +++ b/Documentation/DocBook/media/v4l/func-poll.xml @@ -117,11 +117,3 @@ than <constant>OPEN_MAX</constant>.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml index a5089bf8873..e218bbfbd36 100644 --- a/Documentation/DocBook/media/v4l/func-read.xml +++ b/Documentation/DocBook/media/v4l/func-read.xml @@ -179,11 +179,3 @@ type of device.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-select.xml b/Documentation/DocBook/media/v4l/func-select.xml index b6713623181..e12a60d9bd8 100644 --- a/Documentation/DocBook/media/v4l/func-select.xml +++ b/Documentation/DocBook/media/v4l/func-select.xml @@ -128,11 +128,3 @@ zero or greater than <constant>FD_SETSIZE</constant>.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-write.xml b/Documentation/DocBook/media/v4l/func-write.xml index 2c09c09371c..57520788572 100644 --- a/Documentation/DocBook/media/v4l/func-write.xml +++ b/Documentation/DocBook/media/v4l/func-write.xml @@ -126,11 +126,3 @@ type of device.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 3f47df1aa54..b815929b5bb 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -1282,11 +1282,3 @@ line, top field first. The bottom field is transmitted first.</entry> </mediaobject> </figure> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/libv4l.xml b/Documentation/DocBook/media/v4l/libv4l.xml index 3cb10ec5192..d3b71e20003 100644 --- a/Documentation/DocBook/media/v4l/libv4l.xml +++ b/Documentation/DocBook/media/v4l/libv4l.xml @@ -158,10 +158,3 @@ still don't use libv4l.</para> </section> </section> -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/pixfmt-grey.xml b/Documentation/DocBook/media/v4l/pixfmt-grey.xml index 3b72bc6b2de..bee970d3f76 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-grey.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-grey.xml @@ -60,11 +60,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-m420.xml b/Documentation/DocBook/media/v4l/pixfmt-m420.xml index ce4bc019e5c..aadae92c5d0 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-m420.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-m420.xml @@ -137,11 +137,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml index 873f6703518..84dd4fd7cb8 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml @@ -141,11 +141,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml index c9e166d9ded..3fd3ce5df27 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml @@ -144,11 +144,3 @@ CbCr plane has as many pad bytes after its rows.</para> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml index 7a2855a526c..2f82b1da8df 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml @@ -64,11 +64,3 @@ layout of macroblocks</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml index 26094035fc0..8ae1f8a810d 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml @@ -164,11 +164,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv24.xml b/Documentation/DocBook/media/v4l/pixfmt-nv24.xml new file mode 100644 index 00000000000..fb255f2ca9d --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-nv24.xml @@ -0,0 +1,121 @@ + <refentry> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname id="V4L2-PIX-FMT-NV24"><constant>V4L2_PIX_FMT_NV24</constant></refname> + <refname id="V4L2-PIX-FMT-NV42"><constant>V4L2_PIX_FMT_NV42</constant></refname> + <refpurpose>Formats with full horizontal and vertical +chroma resolutions, also known as YUV 4:4:4. One luminance and one +chrominance plane with alternating chroma samples as opposed to +<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>These are two-plane versions of the YUV 4:4:4 format. The three + components are separated into two sub-images or planes. The Y plane is + first, with each Y sample stored in one byte per pixel. For + <constant>V4L2_PIX_FMT_NV24</constant>, a combined CbCr plane + immediately follows the Y plane in memory. The CbCr plane has the same + width and height, in pixels, as the Y plane (and the image). Each line + contains one CbCr pair per pixel, with each Cb and Cr sample stored in + one byte. <constant>V4L2_PIX_FMT_NV42</constant> is the same except that + the Cb and Cr samples are swapped, the CrCb plane starts with a Cr + sample.</para> + + <para>If the Y plane has pad bytes after each row, then the CbCr plane + has twice as many pad bytes after its rows.</para> + + <example> + <title><constant>V4L2_PIX_FMT_NV24</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="9" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>Y'<subscript>00</subscript></entry> + <entry>Y'<subscript>01</subscript></entry> + <entry>Y'<subscript>02</subscript></entry> + <entry>Y'<subscript>03</subscript></entry> + </row> + <row> + <entry>start + 4:</entry> + <entry>Y'<subscript>10</subscript></entry> + <entry>Y'<subscript>11</subscript></entry> + <entry>Y'<subscript>12</subscript></entry> + <entry>Y'<subscript>13</subscript></entry> + </row> + <row> + <entry>start + 8:</entry> + <entry>Y'<subscript>20</subscript></entry> + <entry>Y'<subscript>21</subscript></entry> + <entry>Y'<subscript>22</subscript></entry> + <entry>Y'<subscript>23</subscript></entry> + </row> + <row> + <entry>start + 12:</entry> + <entry>Y'<subscript>30</subscript></entry> + <entry>Y'<subscript>31</subscript></entry> + <entry>Y'<subscript>32</subscript></entry> + <entry>Y'<subscript>33</subscript></entry> + </row> + <row> + <entry>start + 16:</entry> + <entry>Cb<subscript>00</subscript></entry> + <entry>Cr<subscript>00</subscript></entry> + <entry>Cb<subscript>01</subscript></entry> + <entry>Cr<subscript>01</subscript></entry> + <entry>Cb<subscript>02</subscript></entry> + <entry>Cr<subscript>02</subscript></entry> + <entry>Cb<subscript>03</subscript></entry> + <entry>Cr<subscript>03</subscript></entry> + </row> + <row> + <entry>start + 24:</entry> + <entry>Cb<subscript>10</subscript></entry> + <entry>Cr<subscript>10</subscript></entry> + <entry>Cb<subscript>11</subscript></entry> + <entry>Cr<subscript>11</subscript></entry> + <entry>Cb<subscript>12</subscript></entry> + <entry>Cr<subscript>12</subscript></entry> + <entry>Cb<subscript>13</subscript></entry> + <entry>Cr<subscript>13</subscript></entry> + </row> + <row> + <entry>start + 32:</entry> + <entry>Cb<subscript>20</subscript></entry> + <entry>Cr<subscript>20</subscript></entry> + <entry>Cb<subscript>21</subscript></entry> + <entry>Cr<subscript>21</subscript></entry> + <entry>Cb<subscript>22</subscript></entry> + <entry>Cr<subscript>22</subscript></entry> + <entry>Cb<subscript>23</subscript></entry> + <entry>Cr<subscript>23</subscript></entry> + </row> + <row> + <entry>start + 40:</entry> + <entry>Cb<subscript>30</subscript></entry> + <entry>Cr<subscript>30</subscript></entry> + <entry>Cb<subscript>31</subscript></entry> + <entry>Cr<subscript>31</subscript></entry> + <entry>Cb<subscript>32</subscript></entry> + <entry>Cr<subscript>32</subscript></entry> + <entry>Cb<subscript>33</subscript></entry> + <entry>Cr<subscript>33</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> + </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml index 4db272b8a0d..166c8d65e4f 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml @@ -428,8 +428,11 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <para>Bit 7 is the most significant bit. The value of a = alpha bits is undefined when reading from the driver, ignored when writing to the driver, except when alpha blending has been negotiated for a -<link linkend="overlay">Video Overlay</link> or <link -linkend="osd">Video Output Overlay</link>.</para> +<link linkend="overlay">Video Overlay</link> or <link linkend="osd"> +Video Output Overlay</link> or when alpha component has been configured +for a <link linkend="capture">Video Capture</link> by means of <link +linkend="v4l2-alpha-component"> <constant>V4L2_CID_ALPHA_COMPONENT +</constant> </link> control.</para> <example> <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 × 4 pixel @@ -930,11 +933,3 @@ See &v4l-dvb; for access instructions.</para> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml index 3cab5d0ca75..33fa5a47a86 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml @@ -234,11 +234,3 @@ linkend="osd">Video Output Overlay</link>.</para> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml index 519a9efbac1..6494b05d84a 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml @@ -81,11 +81,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml index 5fe84ecc2eb..5eaf2b42d3f 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml @@ -65,11 +65,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml index d67a472b088..fee65dca79c 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml @@ -65,11 +65,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml index 0cdf13b8ac1..19727ab4c75 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml @@ -65,11 +65,3 @@ columns and rows.</para> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml b/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml index 816c8d467c1..b1f6801a17f 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml @@ -118,11 +118,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml b/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml index 61f12a5e68d..82803408b38 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml @@ -118,11 +118,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y16.xml b/Documentation/DocBook/media/v4l/pixfmt-y16.xml index d5840401507..ff4f727d562 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-y16.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-y16.xml @@ -79,11 +79,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y41p.xml b/Documentation/DocBook/media/v4l/pixfmt-y41p.xml index 73c8536efb0..98dcb91d291 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-y41p.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-y41p.xml @@ -147,11 +147,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml index 8eb4a193d77..0869dce5f92 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml @@ -131,11 +131,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml index 00e0960a986..086dc731bf0 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml @@ -145,11 +145,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml index 42d7de5e456..48649fac159 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml @@ -147,11 +147,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml index f5d8f57495c..9957863daf1 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml @@ -152,11 +152,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml index 4348bd9f0d0..4ce6463fe0a 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml @@ -151,11 +151,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml b/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml index bdb2ffacbbc..58384092251 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml @@ -118,11 +118,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml b/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml index 40d17ae39dd..bfffdc76d3d 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml @@ -118,11 +118,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 2ff6b7776d7..31eaae2469f 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -714,6 +714,7 @@ information.</para> &sub-nv12m; &sub-nv12mt; &sub-nv16; + &sub-nv24; &sub-m420; </section> @@ -890,6 +891,11 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm <entry>'M310'</entry> <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> </row> + <row id="V4L2-PIX-FMT-JL2005BCD"> + <entry><constant>V4L2_PIX_FMT_JL2005BCD</constant></entry> + <entry>'JL20'</entry> + <entry>JPEG compressed RGGB Bayer format used by the gspca driver.</entry> + </row> <row id="V4L2-PIX-FMT-OV511"> <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> <entry>'O511'</entry> @@ -997,11 +1003,3 @@ the other bits are set to 0.</entry> </tgroup> </table> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml new file mode 100644 index 00000000000..2f0bdb4d555 --- /dev/null +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -0,0 +1,321 @@ +<section id="selection-api"> + + <title>Experimental API for cropping, composing and scaling</title> + + <note> + <title>Experimental</title> + + <para>This is an <link linkend="experimental">experimental</link> +interface and may change in the future.</para> + </note> + + <section> + <title>Introduction</title> + +<para>Some video capture devices can sample a subsection of a picture and +shrink or enlarge it to an image of arbitrary size. Next, the devices can +insert the image into larger one. Some video output devices can crop part of an +input image, scale it up or down and insert it at an arbitrary scan line and +horizontal offset into a video signal. We call these abilities cropping, +scaling and composing.</para> + +<para>On a video <emphasis>capture</emphasis> device the source is a video +signal, and the cropping target determine the area actually sampled. The sink +is an image stored in a memory buffer. The composing area specifies which part +of the buffer is actually written to by the hardware. </para> + +<para>On a video <emphasis>output</emphasis> device the source is an image in a +memory buffer, and the cropping target is a part of an image to be shown on a +display. The sink is the display or the graphics screen. The application may +select the part of display where the image should be displayed. The size and +position of such a window is controlled by the compose target.</para> + +<para>Rectangles for all cropping and composing targets are defined even if the +device does supports neither cropping nor composing. Their size and position +will be fixed in such a case. If the device does not support scaling then the +cropping and composing rectangles have the same size.</para> + + </section> + + <section> + <title>Selection targets</title> + + <figure id="sel-targets-capture"> + <title>Cropping and composing targets</title> + <mediaobject> + <imageobject> + <imagedata fileref="selection.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Targets used by a cropping, composing and scaling + process</phrase> + </textobject> + </mediaobject> + </figure> + </section> + + <section> + + <title>Configuration</title> + +<para>Applications can use the <link linkend="vidioc-g-selection">selection +API</link> to select an area in a video signal or a buffer, and to query for +default settings and hardware limits.</para> + +<para>Video hardware can have various cropping, composing and scaling +limitations. It may only scale up or down, support only discrete scaling +factors, or have different scaling abilities in the horizontal and vertical +directions. Also it may not support scaling at all. At the same time the +cropping/composing rectangles may have to be aligned, and both the source and +the sink may have arbitrary upper and lower size limits. Therefore, as usual, +drivers are expected to adjust the requested parameters and return the actual +values selected. An application can control the rounding behaviour using <link +linkend="v4l2-sel-flags"> constraint flags </link>.</para> + + <section> + + <title>Configuration of video capture</title> + +<para>See figure <xref linkend="sel-targets-capture" /> for examples of the +selection targets available for a video capture device. It is recommended to +configure the cropping targets before to the composing targets.</para> + +<para>The range of coordinates of the top left corner, width and height of +areas that can be sampled is given by the <constant> V4L2_SEL_TGT_CROP_BOUNDS +</constant> target. It is recommended for the driver developers to put the +top/left corner at position <constant> (0,0) </constant>. The rectangle's +coordinates are expressed in pixels.</para> + +<para>The top left corner, width and height of the source rectangle, that is +the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP_ACTIVE +</constant> target. It uses the same coordinate system as <constant> +V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie +completely inside the capture boundaries. The driver may further adjust the +requested size and/or position according to hardware limitations.</para> + +<para>Each capture device has a default source rectangle, given by the +<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant> target. This rectangle shall +over what the driver writer considers the complete picture. Drivers shall set +the active crop rectangle to the default when the driver is first loaded, but +not later.</para> + +<para>The composing targets refer to a memory buffer. The limits of composing +coordinates are obtained using <constant> V4L2_SEL_TGT_COMPOSE_BOUNDS +</constant>. All coordinates are expressed in pixels. The rectangle's top/left +corner must be located at position <constant> (0,0) </constant>. The width and +height are equal to the image size set by <constant> VIDIOC_S_FMT </constant>. +</para> + +<para>The part of a buffer into which the image is inserted by the hardware is +controlled by the <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target. +The rectangle's coordinates are also expressed in the same coordinate system as +the bounds rectangle. The composing rectangle must lie completely inside bounds +rectangle. The driver must adjust the composing rectangle to fit to the +bounding limits. Moreover, the driver can perform other adjustments according +to hardware limitations. The application can control rounding behaviour using +<link linkend="v4l2-sel-flags"> constraint flags </link>.</para> + +<para>For capture devices the default composing rectangle is queried using +<constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the +bounding rectangle.</para> + +<para>The part of a buffer that is modified by the hardware is given by +<constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels +defined using <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> plus all +padding data modified by hardware during insertion process. All pixels outside +this rectangle <emphasis>must not</emphasis> be changed by the hardware. The +content of pixels that lie inside the padded area but outside active area is +undefined. The application can use the padded and active rectangles to detect +where the rubbish pixels are located and remove them if needed.</para> + + </section> + + <section> + + <title>Configuration of video output</title> + +<para>For output devices targets and ioctls are used similarly to the video +capture case. The <emphasis> composing </emphasis> rectangle refers to the +insertion of an image into a video signal. The cropping rectangles refer to a +memory buffer. It is recommended to configure the composing targets before to +the cropping targets.</para> + +<para>The cropping targets refer to the memory buffer that contains an image to +be inserted into a video signal or graphical screen. The limits of cropping +coordinates are obtained using <constant> V4L2_SEL_TGT_CROP_BOUNDS </constant>. +All coordinates are expressed in pixels. The top/left corner is always point +<constant> (0,0) </constant>. The width and height is equal to the image size +specified using <constant> VIDIOC_S_FMT </constant> ioctl.</para> + +<para>The top left corner, width and height of the source rectangle, that is +the area from which image date are processed by the hardware, is given by the +<constant> V4L2_SEL_TGT_CROP_ACTIVE </constant>. Its coordinates are expressed +in in the same coordinate system as the bounds rectangle. The active cropping +area must lie completely inside the crop boundaries and the driver may further +adjust the requested size and/or position according to hardware +limitations.</para> + +<para>For output devices the default cropping rectangle is queried using +<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant>. It is usually equal to the +bounding rectangle.</para> + +<para>The part of a video signal or graphics display where the image is +inserted by the hardware is controlled by <constant> +V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target. The rectangle's coordinates +are expressed in pixels. The composing rectangle must lie completely inside the +bounds rectangle. The driver must adjust the area to fit to the bounding +limits. Moreover, the driver can perform other adjustments according to +hardware limitations. </para> + +<para>The device has a default composing rectangle, given by the <constant> +V4L2_SEL_TGT_COMPOSE_DEFAULT </constant> target. This rectangle shall cover what +the driver writer considers the complete picture. It is recommended for the +driver developers to put the top/left corner at position <constant> (0,0) +</constant>. Drivers shall set the active composing rectangle to the default +one when the driver is first loaded.</para> + +<para>The devices may introduce additional content to video signal other than +an image from memory buffers. It includes borders around an image. However, +such a padded area is driver-dependent feature not covered by this document. +Driver developers are encouraged to keep padded rectangle equal to active one. +The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED +</constant> identifier. It must contain all pixels from the <constant> +V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> target.</para> + + </section> + + <section> + + <title>Scaling control.</title> + +<para>An application can detect if scaling is performed by comparing the width +and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP_ACTIVE +</constant> and <constant> V4L2_SEL_TGT_COMPOSE_ACTIVE </constant> targets. If +these are not equal then the scaling is applied. The application can compute +the scaling ratios using these values.</para> + + </section> + + </section> + + <section> + + <title>Comparison with old cropping API.</title> + +<para>The selection API was introduced to cope with deficiencies of previous +<link linkend="crop"> API </link>, that was designed to control simple capture +devices. Later the cropping API was adopted by video output drivers. The ioctls +are used to select a part of the display were the video signal is inserted. It +should be considered as an API abuse because the described operation is +actually the composing. The selection API makes a clear distinction between +composing and cropping operations by setting the appropriate targets. The V4L2 +API lacks any support for composing to and cropping from an image inside a +memory buffer. The application could configure a capture device to fill only a +part of an image by abusing V4L2 API. Cropping a smaller image from a larger +one is achieved by setting the field <structfield> +&v4l2-pix-format;::bytesperline </structfield>. Introducing an image offsets +could be done by modifying field <structfield> &v4l2-buffer;::m:userptr +</structfield> before calling <constant> VIDIOC_QBUF </constant>. Those +operations should be avoided because they are not portable (endianness), and do +not work for macroblock and Bayer formats and mmap buffers. The selection API +deals with configuration of buffer cropping/composing in a clear, intuitive and +portable way. Next, with the selection API the concepts of the padded target +and constraints flags are introduced. Finally, <structname> &v4l2-crop; +</structname> and <structname> &v4l2-cropcap; </structname> have no reserved +fields. Therefore there is no way to extend their functionality. The new +<structname> &v4l2-selection; </structname> provides a lot of place for future +extensions. Driver developers are encouraged to implement only selection API. +The former cropping API would be simulated using the new one. </para> + + </section> + + <section> + <title>Examples</title> + <example> + <title>Resetting the cropping parameters</title> + + <para>(A video capture device is assumed; change <constant> +V4L2_BUF_TYPE_VIDEO_CAPTURE </constant> for other devices; change target to +<constant> V4L2_SEL_TGT_COMPOSE_* </constant> family to configure composing +area)</para> + + <programlisting> + + &v4l2-selection; sel = { + .type = V4L2_BUF_TYPE_VIDEO_CAPTURE, + .target = V4L2_SEL_TGT_CROP_DEFAULT, + }; + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); + if (ret) + exit(-1); + sel.target = V4L2_SEL_TGT_CROP_ACTIVE; + ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); + if (ret) + exit(-1); + + </programlisting> + </example> + + <example> + <title>Simple downscaling</title> + <para>Setting a composing area on output of size of <emphasis> at most +</emphasis> half of limit placed at a center of a display.</para> + <programlisting> + + &v4l2-selection; sel = { + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, + .target = V4L2_SEL_TGT_COMPOSE_BOUNDS, + }; + struct v4l2_rect r; + + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &sel); + if (ret) + exit(-1); + /* setting smaller compose rectangle */ + r.width = sel.r.width / 2; + r.height = sel.r.height / 2; + r.left = sel.r.width / 4; + r.top = sel.r.height / 4; + sel.r = r; + sel.target = V4L2_SEL_TGT_COMPOSE_ACTIVE; + sel.flags = V4L2_SEL_FLAG_LE; + ret = ioctl(fd, &VIDIOC-S-SELECTION;, &sel); + if (ret) + exit(-1); + + </programlisting> + </example> + + <example> + <title>Querying for scaling factors</title> + <para>A video output device is assumed; change <constant> +V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para> + <programlisting> + + &v4l2-selection; compose = { + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, + .target = V4L2_SEL_TGT_COMPOSE_ACTIVE, + }; + &v4l2-selection; crop = { + .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, + .target = V4L2_SEL_TGT_CROP_ACTIVE, + }; + double hscale, vscale; + + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &compose); + if (ret) + exit(-1); + ret = ioctl(fd, &VIDIOC-G-SELECTION;, &crop); + if (ret) + exit(-1); + + /* computing scaling factors */ + hscale = (double)compose.r.width / crop.r.width; + vscale = (double)compose.r.height / crop.r.height; + + </programlisting> + </example> + + </section> + +</section> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 2ab365c10fb..e97c512861b 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -501,6 +501,7 @@ and discussions on the V4L mailing list.</revremark> &sub-g-output; &sub-g-parm; &sub-g-priority; + &sub-g-selection; &sub-g-sliced-vbi-cap; &sub-g-std; &sub-g-tuner; diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml index 1d31427edd1..0be17c232d3 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml @@ -228,11 +228,3 @@ is out of bounds.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml index 71d373b6d36..347d142e743 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml @@ -156,11 +156,3 @@ bounds.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml index 476fe1d2bba..9b8efcd6e94 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml @@ -311,11 +311,3 @@ out of bounds.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml index a281d26a195..a64d5ef103f 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml @@ -196,11 +196,3 @@ is out of bounds.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml index 95803fe2c8e..3a5fc5405f9 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml @@ -381,11 +381,3 @@ is out of bounds.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml b/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml index 5146d00782e..12b1d0503e2 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml @@ -127,11 +127,3 @@ this control belongs to.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index 5122ce87e0b..b17a7aac699 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -183,7 +183,12 @@ applications must set the array to zero.</entry> <entry>__u32</entry> <entry><structfield>ctrl_class</structfield></entry> <entry>The control class to which all controls belong, see -<xref linkend="ctrl-class" />.</entry> +<xref linkend="ctrl-class" />. Drivers that use a kernel framework for handling +controls will also accept a value of 0 here, meaning that the controls can +belong to any control class. Whether drivers support this can be tested by setting +<structfield>ctrl_class</structfield> to 0 and calling <constant>VIDIOC_TRY_EXT_CTRLS</constant> +with a <structfield>count</structfield> of 0. If that succeeds, then the driver +supports this feature.</entry> </row> <row> <entry>__u32</entry> @@ -194,10 +199,13 @@ also be zero.</entry> <row> <entry>__u32</entry> <entry><structfield>error_idx</structfield></entry> - <entry>Set by the driver in case of an error. It is the -index of the control causing the error or equal to 'count' when the -error is not associated with a particular control. Undefined when the -ioctl returns 0 (success).</entry> + <entry>Set by the driver in case of an error. If it is equal +to <structfield>count</structfield>, then no actual changes were made to +controls. In other words, the error was not associated with setting a particular +control. If it is another value, then only the controls up to <structfield>error_idx-1</structfield> +were modified and control <structfield>error_idx</structfield> is the one that +caused the error. The <structfield>error_idx</structfield> value is undefined +if the ioctl returned 0 (success).</entry> </row> <row> <entry>__u32</entry> @@ -312,10 +320,3 @@ to store the payload and this error code is returned.</para> </refsect1> </refentry> -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml index 055718231bc..7c63815e7af 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml @@ -295,7 +295,8 @@ set this field to zero.</entry> <entry>The device is capable of non-destructive overlays. When the driver clears this flag, only destructive overlays are supported. There are no drivers yet which support both destructive and -non-destructive overlays.</entry> +non-destructive overlays. Video Output Overlays are in practice always +non-destructive.</entry> </row> <row> <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> @@ -339,8 +340,8 @@ blending makes no sense for destructive overlays.</entry> <row> <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry> <entry>0x0080</entry> - <entry>The device supports Source Chroma-keying. Framebuffer pixels -with the chroma-key colors are replaced by video pixels, which is exactly opposite of + <entry>The device supports Source Chroma-keying. Video pixels +with the chroma-key colors are replaced by framebuffer pixels, which is exactly opposite of <constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry> </row> </tbody> @@ -356,21 +357,27 @@ with the chroma-key colors are replaced by video pixels, which is exactly opposi <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry> <entry>0x0001</entry> <entry>The framebuffer is the primary graphics surface. -In other words, the overlay is destructive. [?]</entry> +In other words, the overlay is destructive. This flag is typically set by any +driver that doesn't have the <constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant> +capability and it is cleared otherwise.</entry> </row> <row> <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry> <entry>0x0002</entry> - <entry>The frame buffer is an overlay surface the same -size as the capture. [?]</entry> - </row> - <row> - <entry spanname="hspan">The purpose of -<constant>V4L2_FBUF_FLAG_PRIMARY</constant> and -<constant>V4L2_FBUF_FLAG_OVERLAY</constant> was never quite clear. -Most drivers seem to ignore these flags. For compatibility with the -<wordasword>bttv</wordasword> driver applications should set the -<constant>V4L2_FBUF_FLAG_OVERLAY</constant> flag.</entry> + <entry>If this flag is set for a video capture device, then the +driver will set the initial overlay size to cover the full framebuffer size, +otherwise the existing overlay size (as set by &VIDIOC-S-FMT;) will be used. + +Only one video capture driver (bttv) supports this flag. The use of this flag +for capture devices is deprecated. There is no way to detect which drivers +support this flag, so the only reliable method of setting the overlay size is +through &VIDIOC-S-FMT;. + +If this flag is set for a video output device, then the video output overlay +window is relative to the top-left corner of the framebuffer and restricted +to the size of the framebuffer. If it is cleared, then the video output +overlay window is relative to the video output display. + </entry> </row> <row> <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml index 062d7206909..66e9a525786 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml @@ -98,8 +98,11 @@ the &v4l2-output; <structfield>modulator</structfield> field and the <entry>&v4l2-tuner-type;</entry> <entry><structfield>type</structfield></entry> <entry>The tuner type. This is the same value as in the -&v4l2-tuner; <structfield>type</structfield> field. The field is not -applicable to modulators, &ie; ignored by drivers.</entry> +&v4l2-tuner; <structfield>type</structfield> field. The type must be set +to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename> +device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant> +for all others. The field is not applicable to modulators, &ie; ignored +by drivers.</entry> </row> <row> <entry>__u32</entry> @@ -135,11 +138,3 @@ wrong.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-input.xml b/Documentation/DocBook/media/v4l/vidioc-g-input.xml index 08ae82f131f..1d43065090d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-input.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-input.xml @@ -61,8 +61,8 @@ desired input in an integer and call the <constant>VIDIOC_S_INPUT</constant> ioctl with a pointer to this integer. Side effects are possible. For example inputs may support different video standards, so the driver may implicitly switch the -current standard. It is good practice to select an input before -querying or negotiating any other parameters.</para> +current standard. Because of these possible side effects applications +must select an input before querying or negotiating any other parameters.</para> <para>Information about video inputs is available using the &VIDIOC-ENUMINPUT; ioctl.</para> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml index 15ce660f0f5..7f4ac7e41fa 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml @@ -236,11 +236,3 @@ mode.</entry> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-output.xml b/Documentation/DocBook/media/v4l/vidioc-g-output.xml index fd45f1c13cc..4533068ecb8 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-output.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-output.xml @@ -61,8 +61,9 @@ desired output in an integer and call the <constant>VIDIOC_S_OUTPUT</constant> ioctl with a pointer to this integer. Side effects are possible. For example outputs may support different video standards, so the driver may implicitly switch the current -standard. It is good practice to select an output before querying or -negotiating any other parameters.</para> +standard. +standard. Because of these possible side effects applications +must select an output before querying or negotiating any other parameters.</para> <para>Information about video outputs is available using the &VIDIOC-ENUMOUTPUT; ioctl.</para> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-priority.xml b/Documentation/DocBook/media/v4l/vidioc-g-priority.xml index 8f5e3da7002..6a81b4fe953 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-priority.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-priority.xml @@ -133,11 +133,3 @@ priority.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml new file mode 100644 index 00000000000..a9d36e0c090 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -0,0 +1,304 @@ +<refentry id="vidioc-g-selection"> + + <refmeta> + <refentrytitle>ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_G_SELECTION</refname> + <refname>VIDIOC_S_SELECTION</refname> + <refpurpose>Get or set one of the selection rectangles</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_selection *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_G_SELECTION, VIDIOC_S_SELECTION</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <note> + <title>Experimental</title> + <para>This is an <link linkend="experimental"> experimental </link> + interface and may change in the future.</para> + </note> + + <para>The ioctls are used to query and configure selection rectangles.</para> + +<para> To query the cropping (composing) rectangle set <structfield> +&v4l2-selection;::type </structfield> to the respective buffer type. Do not +use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE +</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE +</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of +<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is +setting <structfield> &v4l2-selection;::target </structfield> to value +<constant> V4L2_SEL_TGT_CROP_ACTIVE </constant> (<constant> +V4L2_SEL_TGT_COMPOSE_ACTIVE </constant>). Please refer to table <xref +linkend="v4l2-sel-target" /> or <xref linkend="selection-api" /> for additional +targets. Fields <structfield> &v4l2-selection;::flags </structfield> and +<structfield> &v4l2-selection;::reserved </structfield> are ignored and they +must be filled with zeros. The driver fills the rest of the structure or +returns &EINVAL; if incorrect buffer type or target was used. If cropping +(composing) is not supported then the active rectangle is not mutable and it is +always equal to the bounds rectangle. Finally, structure <structfield> +&v4l2-selection;::r </structfield> is filled with the current cropping +(composing) coordinates. The coordinates are expressed in driver-dependent +units. The only exception are rectangles for images in raw formats, whose +coordinates are always expressed in pixels. </para> + +<para> To change the cropping (composing) rectangle set <structfield> +&v4l2-selection;::type </structfield> to the respective buffer type. Do not +use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE +</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE +</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of +<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is +setting <structfield> &v4l2-selection;::target </structfield> to value +<constant> V4L2_SEL_TGT_CROP_ACTIVE </constant> (<constant> +V4L2_SEL_TGT_COMPOSE_ACTIVE </constant>). Please refer to table <xref +linkend="v4l2-sel-target" /> or <xref linkend="selection-api" /> for additional +targets. Set desired active area into the field <structfield> +&v4l2-selection;::r </structfield>. Field <structfield> +&v4l2-selection;::reserved </structfield> is ignored and must be filled with +zeros. The driver may adjust the rectangle coordinates. An application may +introduce constraints to control rounding behaviour. Set the field +<structfield> &v4l2-selection;::flags </structfield> to one of values: + +<itemizedlist> + <listitem> +<para><constant>0</constant> - The driver can adjust the rectangle size freely +and shall choose a crop/compose rectangle as close as possible to the requested +one.</para> + </listitem> + <listitem> +<para><constant>V4L2_SEL_FLAG_GE</constant> - The driver is not allowed to +shrink the rectangle. The original rectangle must lay inside the adjusted +one.</para> + </listitem> + <listitem> +<para><constant>V4L2_SEL_FLAG_LE</constant> - The driver is not allowed to +enlarge the rectangle. The adjusted rectangle must lay inside the original +one.</para> + </listitem> + <listitem> +<para><constant>V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE</constant> - The driver +must choose the size exactly the same as in the requested rectangle.</para> + </listitem> +</itemizedlist> + +Please refer to <xref linkend="sel-const-adjust" />. + +</para> + +<para> The driver may have to adjusts the requested dimensions against hardware +limits and other parts as the pipeline, i.e. the bounds given by the +capture/output window or TV display. The closest possible values of horizontal +and vertical offset and sizes are chosen according to following priority: + +<orderedlist> + <listitem> + <para>Satisfy constraints from <structfield>&v4l2-selection;::flags</structfield>.</para> + </listitem> + <listitem> + <para>Adjust width, height, left, and top to hardware limits and alignments.</para> + </listitem> + <listitem> + <para>Keep center of adjusted rectangle as close as possible to the original one.</para> + </listitem> + <listitem> + <para>Keep width and height as close as possible to original ones.</para> + </listitem> + <listitem> + <para>Keep horizontal and vertical offset as close as possible to original ones.</para> + </listitem> +</orderedlist> + +On success the field <structfield> &v4l2-selection;::r </structfield> contains +the adjusted rectangle. When the parameters are unsuitable the application may +modify the cropping (composing) or image parameters and repeat the cycle until +satisfactory parameters have been negotiated. If constraints flags have to be +violated at then ERANGE is returned. The error indicates that <emphasis> there +exist no rectangle </emphasis> that satisfies the constraints.</para> + + </refsect1> + + <refsect1> + <table frame="none" pgwide="1" id="v4l2-sel-target"> + <title>Selection targets.</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>V4L2_SEL_TGT_CROP_ACTIVE</constant></entry> + <entry>0</entry> + <entry>area that is currently cropped by hardware</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry> + <entry>1</entry> + <entry>suggested cropping rectangle that covers the "whole picture"</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry> + <entry>2</entry> + <entry>limits for the cropping rectangle</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE_ACTIVE</constant></entry> + <entry>256</entry> + <entry>area to which data are composed by hardware</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry> + <entry>257</entry> + <entry>suggested composing rectangle that covers the "whole picture"</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry> + <entry>258</entry> + <entry>limits for the composing rectangle</entry> + </row> + <row> + <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry> + <entry>259</entry> + <entry>the active area and all padding pixels that are inserted or modified by the hardware</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <table frame="none" pgwide="1" id="v4l2-sel-flags"> + <title>Selection constraint flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>V4L2_SEL_FLAG_GE</constant></entry> + <entry>0x00000001</entry> + <entry>indicate that adjusted rectangle must contain a rectangle from <structfield>&v4l2-selection;::r</structfield></entry> + </row> + <row> + <entry><constant>V4L2_SEL_FLAG_LE</constant></entry> + <entry>0x00000002</entry> + <entry>indicate that adjusted rectangle must be inside a rectangle from <structfield>&v4l2-selection;::r</structfield></entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <section> + <figure id="sel-const-adjust"> + <title>Size adjustments with constraint flags.</title> + <mediaobject> + <imageobject> + <imagedata fileref="constraints.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Behaviour of rectangle adjustment for different constraint + flags.</phrase> + </textobject> + </mediaobject> + </figure> + </section> + + <refsect1> + <table pgwide="1" frame="none" id="v4l2-selection"> + <title>struct <structname>v4l2_selection</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>type</structfield></entry> + <entry>Type of the buffer (from &v4l2-buf-type;)</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>target</structfield></entry> + <entry>used to select between <link linkend="v4l2-sel-target"> cropping and composing rectangles </link></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>control over coordinates adjustments, refer to <link linkend="v4l2-sel-flags">selection flags</link></entry> + </row> + <row> + <entry>&v4l2-rect;</entry> + <entry><structfield>r</structfield></entry> + <entry>selection rectangle</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved[9]</structfield></entry> + <entry>Reserved fields for future use</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + <variablelist> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The buffer <structfield> &v4l2-selection;::type </structfield> +or <structfield> &v4l2-selection;::target </structfield> is not supported, or +the <structfield> &v4l2-selection;::flags </structfield> are invalid.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ERANGE</errorcode></term> + <listitem> + <para>it is not possible to adjust a rectangle <structfield> +&v4l2-selection;::r </structfield> that satisfies all contraints from +<structfield> &v4l2-selection;::flags </structfield>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>it is not possible to apply change of selection rectangle at the moment. +Usually because streaming is in progress.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + +</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-std.xml b/Documentation/DocBook/media/v4l/vidioc-g-std.xml index 37996f25b5d..99ff1a01622 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-std.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-std.xml @@ -88,11 +88,3 @@ standards.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index bd98c734c06..91ec2fb658f 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -318,6 +318,16 @@ standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry> <entry>RDS capture is supported. This capability is only valid for radio tuners.</entry> </row> + <row> + <entry><constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant></entry> + <entry>0x0100</entry> + <entry>The RDS data is passed as unparsed RDS blocks.</entry> + </row> + <row> + <entry><constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant></entry> + <entry>0x0200</entry> + <entry>The RDS data is parsed by the hardware and set via controls.</entry> + </row> </tbody> </tgroup> </table> @@ -525,11 +535,3 @@ out of bounds.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml index 5c104d42d31..6e414d7b6df 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml @@ -100,11 +100,3 @@ supported, or the <structfield>index</structfield> is out of bounds.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index 0ac0057a51c..36660d311b5 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -443,11 +443,3 @@ or this particular menu item is not supported by the driver.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml index c30dcc4232c..e013da845b1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -125,11 +125,3 @@ wrong.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> |