camera3: Update focalLength tags.
Change-Id: I59614223ae65e602f3461029cb4b8848fb22950e
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 9f7883b..3528f5b 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -6780,7 +6780,7 @@
</td> <!-- entry_type -->
<td class="entry_description">
- <p>Lens optical zoom setting</p>
+ <p>The current lens focal length; used for optical zoom.<wbr/></p>
</td>
<td class="entry_units">
@@ -6788,7 +6788,7 @@
</td>
<td class="entry_range">
- <p>> 0</p>
+ <p><a href="#static_android.lens.info.availableFocalLengths">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Focal<wbr/>Lengths</a></p>
</td>
<td class="entry_tags">
@@ -6803,7 +6803,15 @@
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="5">
- <p>Will not be supported on most devices.<wbr/></p>
+ <p>This setting controls the physical focal length of the camera
+device's lens.<wbr/> Changing the focal length changes the field of
+view of the camera device,<wbr/> and is usually used for optical zoom.<wbr/></p>
+<p>Like <a href="#controls_android.lens.focusDistance">android.<wbr/>lens.<wbr/>focus<wbr/>Distance</a> and <a href="#controls_android.lens.aperture">android.<wbr/>lens.<wbr/>aperture</a>,<wbr/> this
+setting won't be applied instantaneously,<wbr/> and it may take several
+frames before the lens can move to the requested focal length.<wbr/>
+While the focal length is still changing,<wbr/> <a href="#dynamic_android.lens.state">android.<wbr/>lens.<wbr/>state</a> will
+be set to MOVING.<wbr/></p>
+<p>This is expected not to be supported on most devices.<wbr/></p>
</td>
</tr>
@@ -7059,22 +7067,22 @@
n
</span>
<span class="entry_type_visibility"> [public]</span>
- <div class="entry_type_notes">the list of available focal lengths</div>
+ <div class="entry_type_notes">The list of available focal lengths</div>
</td> <!-- entry_type -->
<td class="entry_description">
- <p>If fitted with optical zoom,<wbr/> what focal
-lengths are available.<wbr/> If not,<wbr/> the static focal
-length</p>
+ <p>The available focal lengths for this device for use with
+<a href="#controls_android.lens.focalLength">android.<wbr/>lens.<wbr/>focal<wbr/>Length</a>.<wbr/></p>
</td>
<td class="entry_units">
</td>
<td class="entry_range">
- <p>> 0</p>
+ <p>Each value in this list must be > 0.<wbr/> This list must
+contain at least one value.<wbr/></p>
</td>
<td class="entry_tags">
@@ -7090,8 +7098,10 @@
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="5">
- <p>If optical zoom not supported,<wbr/> only one value
-should be reported</p>
+ <p>If optical zoom is not supported,<wbr/> this will only report
+a single value corresponding to the static focal length of the
+device.<wbr/> Otherwise,<wbr/> this will report every focal length supported
+by the device.<wbr/></p>
</td>
</tr>
@@ -7671,7 +7681,7 @@
</td> <!-- entry_type -->
<td class="entry_description">
- <p>Lens optical zoom setting</p>
+ <p>The current lens focal length; used for optical zoom.<wbr/></p>
</td>
<td class="entry_units">
@@ -7679,7 +7689,7 @@
</td>
<td class="entry_range">
- <p>> 0</p>
+ <p><a href="#static_android.lens.info.availableFocalLengths">android.<wbr/>lens.<wbr/>info.<wbr/>available<wbr/>Focal<wbr/>Lengths</a></p>
</td>
<td class="entry_tags">
@@ -7694,7 +7704,15 @@
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="5">
- <p>Will not be supported on most devices.<wbr/></p>
+ <p>This setting controls the physical focal length of the camera
+device's lens.<wbr/> Changing the focal length changes the field of
+view of the camera device,<wbr/> and is usually used for optical zoom.<wbr/></p>
+<p>Like <a href="#controls_android.lens.focusDistance">android.<wbr/>lens.<wbr/>focus<wbr/>Distance</a> and <a href="#controls_android.lens.aperture">android.<wbr/>lens.<wbr/>aperture</a>,<wbr/> this
+setting won't be applied instantaneously,<wbr/> and it may take several
+frames before the lens can move to the requested focal length.<wbr/>
+While the focal length is still changing,<wbr/> <a href="#dynamic_android.lens.state">android.<wbr/>lens.<wbr/>state</a> will
+be set to MOVING.<wbr/></p>
+<p>This is expected not to be supported on most devices.<wbr/></p>
</td>
</tr>
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index 30cbfbf..f435b69 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -1656,10 +1656,24 @@
<tag id="V1" />
</entry>
<entry name="focalLength" type="float" visibility="public">
- <description>Lens optical zoom setting</description>
+ <description>
+ The current lens focal length; used for optical zoom.
+ </description>
<units>focal length in mm</units>
- <range>&gt; 0</range>
- <details>Will not be supported on most devices.</details>
+ <range>android.lens.info.availableFocalLengths</range>
+ <details>
+ This setting controls the physical focal length of the camera
+ device's lens. Changing the focal length changes the field of
+ view of the camera device, and is usually used for optical zoom.
+
+ Like android.lens.focusDistance and android.lens.aperture, this
+ setting won't be applied instantaneously, and it may take several
+ frames before the lens can move to the requested focal length.
+ While the focal length is still changing, android.lens.state will
+ be set to MOVING.
+
+ This is expected not to be supported on most devices.
+ </details>
<tag id="V1" />
</entry>
<entry name="focusDistance" type="float" visibility="public">
@@ -1717,17 +1731,25 @@
<tag id="V1" />
</entry>
<entry name="availableFocalLengths" type="float" visibility="public"
- type_notes="the list of available focal lengths"
+ type_notes="The list of available focal lengths"
container="array">
<array>
<size>n</size>
</array>
- <description>If fitted with optical zoom, what focal
- lengths are available. If not, the static focal
- length</description>
- <range>&gt; 0</range>
- <details>If optical zoom not supported, only one value
- should be reported</details>
+ <description>
+ The available focal lengths for this device for use with
+ android.lens.focalLength.
+ </description>
+ <range>
+ Each value in this list must be &gt; 0. This list must
+ contain at least one value.
+ </range>
+ <details>
+ If optical zoom is not supported, this will only report
+ a single value corresponding to the static focal length of the
+ device. Otherwise, this will report every focal length supported
+ by the device.
+ </details>
<tag id="BC" />
<tag id="V1" />
</entry>