[media] v4l: Common documentation for selection targets

Both V4L2 and V4L2 subdev interface have very similar selection APIs with
differences foremost related to in-memory and media bus formats. However,
the selection targets are the same for both. Most targets are and in the
future will likely continue to be more the same than with any differences.
Thus it makes sense to unify the documentation of the targets.

Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
Acked-by: Sylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

1 files changed, 92 insertions, 0 deletions

diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml
new file mode 100644
index 00000000000..6728688d28d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/selections-common.xml
@@ -0,0 +1,92 @@
+<section id="v4l2-selections-common">
+
+  <title>Selection targets</title>
+
+  <para>While the <link linkend="selection-api">V4L2 selection
+  API</link> and <link linkend="v4l2-subdev-selections">V4L2 subdev
+  selection APIs</link> are very similar, there's one fundamental
+  difference between the two. On sub-device API, the selection
+  rectangle refers to the media bus format, and is bound to a
+  sub-device's pad. On the V4L2 interface the selection rectangles
+  refer to the in-memory pixel format.</para>
+
+  <para>The precise meaning of the selection targets may thus be
+  affected on which of the two interfaces they are used.</para>
+
+  <table pgwide="1" frame="none" id="v4l2-selection-targets-table">
+  <title>Selection target definitions</title>
+    <tgroup cols="5">
+      <colspec colname="c1" />
+      <colspec colname="c2" />
+      <colspec colname="c3" />
+      <colspec colname="c4" />
+      <colspec colname="c5" />
+      &cs-def;
+      <thead>
+	<row rowsep="1">
+	  <entry align="left">Target name</entry>
+	  <entry align="left">id</entry>
+	  <entry align="left">Definition</entry>
+	  <entry align="left">Valid for V4L2</entry>
+	  <entry align="left">Valid for V4L2 subdev</entry>
+	</row>
+      </thead>
+      <tbody valign="top">
+	<row>
+	  <entry><constant>V4L2_SEL_TGT_CROP</constant></entry>
+	  <entry>0x0000</entry>
+	  <entry>Crop rectangle. Defines the cropped area.</entry>
+	  <entry>Yes</entry>
+	  <entry>Yes</entry>
+	</row>
+	<row>
+          <entry><constant>V4L2_SEL_TGT_CROP_DEFAULT</constant></entry>
+          <entry>0x0001</entry>
+          <entry>Suggested cropping rectangle that covers the "whole picture".</entry>
+	  <entry>Yes</entry>
+	  <entry>No</entry>
+	</row>
+	<row>
+	  <entry><constant>V4L2_SEL_TGT_CROP_BOUNDS</constant></entry>
+	  <entry>0x0002</entry>
+	  <entry>Bounds of the crop rectangle. All valid crop
+	  rectangles fit inside the crop bounds rectangle.
+	  </entry>
+	  <entry>Yes</entry>
+	  <entry>Yes</entry>
+	</row>
+	<row>
+	  <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry>
+	  <entry>0x0100</entry>
+	  <entry>Compose rectangle. Used to configure scaling
+	  and composition.</entry>
+	  <entry>Yes</entry>
+	  <entry>Yes</entry>
+	</row>
+	<row>
+          <entry><constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant></entry>
+          <entry>0x0101</entry>
+          <entry>Suggested composition rectangle that covers the "whole picture".</entry>
+	  <entry>Yes</entry>
+	  <entry>No</entry>
+	</row>
+	<row>
+	  <entry><constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant></entry>
+	  <entry>0x0102</entry>
+	  <entry>Bounds of the compose rectangle. All valid compose
+	  rectangles fit inside the compose bounds rectangle.</entry>
+	  <entry>Yes</entry>
+	  <entry>Yes</entry>
+	</row>
+	<row>
+          <entry><constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant></entry>
+          <entry>0x0103</entry>
+          <entry>The active area and all padding pixels that are inserted or
+	    modified by hardware.</entry>
+	  <entry>Yes</entry>
+	  <entry>No</entry>
+	</row>
+      </tbody>
+    </tgroup>
+  </table>
+</section>