@@ -1,6 +1,6 @@
<section id="selection-api">
- <title>Experimental API for cropping, composing and scaling</title>
+ <title>Selection API</title>
<note>
<title>Experimental</title>
@@ -9,6 +9,10 @@
interface and may change in the future.</para>
</note>
+ <section>
+
+ <title>Image cropping, composing and scaling</title>
+
<section>
<title>Introduction</title>
@@ -321,5 +325,30 @@ V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para>
</example>
</section>
+ </section>
+
+ <section>
+ <title>Automatic focus regions of interest</title>
+
+<para>The camera automatic focus algorithms may require configuration of
+regions of interest in form of rectangle or spot coordinates. The automatic
+focus selection targets allow applications to query and set such coordinates.
+Those selections are intended to be used together with the
+<constant>V4L2_CID_AUTO_FOCUS_AREA</constant> <link linkend="camera-controls">
+camera class</link> control. The <constant>V4L2_SEL_TGT_AUTO_FOCUS</constant>
+target is used for querying or setting actual spot or rectangle coordinates,
+while <constant>V4L2_SEL_TGT_AUTO_FOCUS_BOUNDS</constant> target determines
+bounds for a single spot or rectangle. These selections are only effective when
+the <constant>V4L2_CID_AUTO_FOCUS_AREA</constant> control is set to
+<constant>V4L2_AUTO_FOCUS_AREA_RECTANGLE</constant>. The new coordinates shall
+be applied to the hardware only by (re-)starting autofocus process
+(<constant>V4L2_CID_AUTO_FOCUS_START</constant>) or starting continuous
+autofocus (<constant>V4L2_CID_FOCUS_AUTO</constant>). </para>
+
+<para>When the <structfield>width</structfield> and
+<structfield>height</structfield> of the selection rectangle are set to 0 the
+selection determines spot coordinates, rather than a rectangle.</para>
+
+ </section>
</section>
@@ -93,6 +93,22 @@
<entry>Yes</entry>
<entry>No</entry>
</row>
+ <row>
+ <entry><constant>V4L2_SEL_TGT_AUTO_FOCUS</constant></entry>
+ <entry>0x1001</entry>
+ <entry>Actual automatic focus rectangle.</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry><constant>V4L2_SEL_TGT_AUTO_FOCUS_BOUNDS</constant></entry>
+ <entry>0x1002</entry>
+ <entry>Bounds of the automatic focus region of interest. All valid
+ automatic focus rectangles fit inside the automatic focus bounds
+ rectangle.</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -158,7 +174,28 @@
</tbody>
</tgroup>
</table>
+ </section>
+
+ <section>
+ <title>Automatic focus regions of interest</title>
+
+ <para>The camera automatic focus algorithms may require configuration
+ of a region or multiple regions of interest in form of rectangle or spot
+ coordinates.</para>
+
+ <para>A single rectangle of interest is represented in &v4l2-rect;
+ by the coordinates of the top left corner and the rectangle size. Both
+ the coordinates and sizes are expressed in pixels. When the <structfield>
+ width</structfield> and <structfield>height</structfield> fields of
+ &v4l2-rect; are set to 0 the selection determines spot coordinates,
+ rather than a rectangle.</para>
+ <para>Auto focus rectangles are reset to their default values when the
+ output image format is modified. Drivers should use the output image size
+ as the auto focus rectangle default value, but hardware requirements may
+ prevent this.
+ </para>
+ <para>The auto focus selections on input pads are not defined.</para>
</section>
</section>
@@ -55,10 +55,11 @@
interface and may change in the future.</para>
</note>
- <para>The selections are used to configure various image
- processing functionality performed by the subdevs which affect the
- image size. This currently includes cropping, scaling and
- composition.</para>
+ <para>The selections are used to configure various image processing
+ functionality performed by the subdevs which requires passing image
+ area coordinates between a driver and an application.
+ This currently includes cropping, scaling, composition
+ and automatic focus regions of interest.</para>
<para>The selection API replaces <link
linkend="vidioc-subdev-g-crop">the old subdev crop API</link>. All
@@ -50,6 +50,11 @@
/* Current composing area plus all padding pixels */
#define V4L2_SEL_TGT_COMPOSE_PADDED 0x0103
+/* Auto focus region of interest */
+#define V4L2_SEL_TGT_AUTO_FOCUS 0x1001
+/* Auto focus region bounds */
+#define V4L2_SEL_TGT_AUTO_FOCUS_BOUNDS 0x1002
+
/* Backward compatibility target definitions --- to be removed. */
#define V4L2_SEL_TGT_CROP_ACTIVE V4L2_SEL_TGT_CROP
#define V4L2_SEL_TGT_COMPOSE_ACTIVE V4L2_SEL_TGT_COMPOSE