camera_metadata: Update android.blackLevel.lock
Change-Id: I1e0ebcaf1c7ec3643464e3d92ac1fc116f85e67b
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 9605fd1..2ad79a3 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -12635,7 +12635,7 @@
<tr class="entry" id="controls_android.blackLevel.lock">
- <td class="entry_name" rowspan="3">
+ <td class="entry_name" rowspan="5">
<html><body><p>android.blackLevel.lock<wbr></wbr></p></body></html>
</td>
<td class="entry_type">
@@ -12656,7 +12656,7 @@
<td class="entry_description">
<html><body><p>Whether black-level compensation is locked
-to its current values, or is free to vary<wbr></wbr></p></body></html>
+to its current values, or is free to vary.<wbr></wbr></p></body></html>
</td>
<td class="entry_units">
@@ -12678,12 +12678,12 @@
<tr class="entry_cont">
<td class="entry_details" colspan="5">
<html><body><p>When set to ON, the values used for black-level
-compensation must not change until the lock is set to
-OFF</p>
+compensation will not change until the lock is set to
+OFF.</p>
<p>Since changes to certain capture parameters (such as
exposure time) may require resetting of black level
-compensation, the HAL must report whether setting the
-black level lock was successful in the output result
+compensation, the camera device must report whether setting
+the black level lock was successful in the output result
metadata.</p>
<p>For example, if a sequence of requests is as follows:</p>
<ul>
@@ -12694,8 +12694,9 @@
<li>Request 5: Exposure = 20ms, Black level lock = ON</li>
<li>Request 6: Exposure = 20ms, Black level lock = ON</li>
</ul>
-<p>And the exposure change in Request 4 requires resetting the black
-level offsets, then the output result metadata is expected to be:</p>
+<p>And the exposure change in Request 4 requires the camera
+device to reset the black level offsets, then the output
+result metadata is expected to be:</p>
<ul>
<li>Result 1: Exposure = 10ms, Black level lock = OFF</li>
<li>Result 2: Exposure = 10ms, Black level lock = ON</li>
@@ -12704,18 +12705,29 @@
<li>Result 5: Exposure = 20ms, Black level lock = ON</li>
<li>Result 6: Exposure = 20ms, Black level lock = ON</li>
</ul>
-<p>This indicates to the application that on frame 4, black levels were
-reset due to exposure value changes, and pixel values may not be
-consistent across captures.</p>
-<p>The black level locking must happen at the sensor, and not at the ISP.
-If for some reason black level locking is no longer legal (for example,
-the analog gain has changed, which forces black levels to be
-recalculated), then the HAL is free to override this request (and it
-must report 'OFF' when this does happen) until the next time locking
-is legal again.<wbr></wbr></p></body></html>
+<p>This indicates to the application that on frame 4, black
+levels were reset due to exposure value changes, and pixel
+values may not be consistent across captures.</p>
+<p>The camera device will maintain the lock to the extent
+possible, only overriding the lock to OFF when changes to
+other request parameters require a black level recalculation
+or reset.<wbr></wbr></p></body></html>
</td>
</tr>
+ <tr class="entries_header">
+ <th class="th_details" colspan="5">HAL Implementation Details</th>
+ </tr>
+ <tr class="entry_cont">
+ <td class="entry_details" colspan="5">
+ <html><body><p>If for some reason black level locking is no longer possible
+(for example, the analog gain has changed, which forces
+black level offsets to be recalculated), then the HAL must
+override this request (and it must report 'OFF' when this
+does happen) until the next capture for which locking is
+possible again.<wbr></wbr></p></body></html>
+ </td>
+ </tr>
<tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
<!-- end of entry -->
@@ -12749,7 +12761,7 @@
<tr class="entry" id="dynamic_android.blackLevel.lock">
- <td class="entry_name" rowspan="3">
+ <td class="entry_name" rowspan="5">
<html><body><p>android.blackLevel.lock<wbr></wbr></p></body></html>
</td>
<td class="entry_type">
@@ -12770,7 +12782,7 @@
<td class="entry_description">
<html><body><p>Whether black-level compensation is locked
-to its current values, or is free to vary<wbr></wbr></p></body></html>
+to its current values, or is free to vary.<wbr></wbr></p></body></html>
</td>
<td class="entry_units">
@@ -12791,12 +12803,26 @@
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="5">
- <html><body><p>Whether the black level offset was locked for this frame.
-Should be ON if android.blackLevel.lock was ON in the capture request,
-unless a change in capture settings forced a black level reset.<wbr></wbr></p></body></html>
+ <html><body><p>Whether the black level offset was locked for this frame. Should be
+ON if android.blackLevel.lock was ON in the capture request, unless
+a change in other capture settings forced the camera device to
+perform a black level reset.<wbr></wbr></p></body></html>
</td>
</tr>
+ <tr class="entries_header">
+ <th class="th_details" colspan="5">HAL Implementation Details</th>
+ </tr>
+ <tr class="entry_cont">
+ <td class="entry_details" colspan="5">
+ <html><body><p>If for some reason black level locking is no longer possible
+(for example, the analog gain has changed, which forces
+black level offsets to be recalculated), then the HAL must
+override this request (and it must report 'OFF' when this
+does happen) until the next capture for which locking is
+possible again.<wbr></wbr></p></body></html>
+ </td>
+ </tr>
<tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
<!-- end of entry -->
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index f148c7c..7edf9fe 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -2749,15 +2749,15 @@
<value>ON</value>
</enum>
<description> Whether black-level compensation is locked
- to its current values, or is free to vary</description>
+ to its current values, or is free to vary.</description>
<details>When set to ON, the values used for black-level
- compensation must not change until the lock is set to
- OFF
+ compensation will not change until the lock is set to
+ OFF.
Since changes to certain capture parameters (such as
exposure time) may require resetting of black level
- compensation, the HAL must report whether setting the
- black level lock was successful in the output result
+ compensation, the camera device must report whether setting
+ the black level lock was successful in the output result
metadata.
For example, if a sequence of requests is as follows:
@@ -2769,8 +2769,9 @@
* Request 5: Exposure = 20ms, Black level lock = ON
* Request 6: Exposure = 20ms, Black level lock = ON
- And the exposure change in Request 4 requires resetting the black
- level offsets, then the output result metadata is expected to be:
+ And the exposure change in Request 4 requires the camera
+ device to reset the black level offsets, then the output
+ result metadata is expected to be:
* Result 1: Exposure = 10ms, Black level lock = OFF
* Result 2: Exposure = 10ms, Black level lock = ON
@@ -2779,16 +2780,22 @@
* Result 5: Exposure = 20ms, Black level lock = ON
* Result 6: Exposure = 20ms, Black level lock = ON
- This indicates to the application that on frame 4, black levels were
- reset due to exposure value changes, and pixel values may not be
- consistent across captures.
+ This indicates to the application that on frame 4, black
+ levels were reset due to exposure value changes, and pixel
+ values may not be consistent across captures.
- The black level locking must happen at the sensor, and not at the ISP.
- If for some reason black level locking is no longer legal (for example,
- the analog gain has changed, which forces black levels to be
- recalculated), then the HAL is free to override this request (and it
- must report 'OFF' when this does happen) until the next time locking
- is legal again.</details>
+ The camera device will maintain the lock to the extent
+ possible, only overriding the lock to OFF when changes to
+ other request parameters require a black level recalculation
+ or reset.
+ </details>
+ <hal_details>
+ If for some reason black level locking is no longer possible
+ (for example, the analog gain has changed, which forces
+ black level offsets to be recalculated), then the HAL must
+ override this request (and it must report 'OFF' when this
+ does happen) until the next capture for which locking is
+ possible again.</hal_details>
<tag id="HAL2" />
</entry>
</controls>
@@ -2796,9 +2803,10 @@
<clone entry="android.blackLevel.lock"
kind="controls">
<details>
- Whether the black level offset was locked for this frame.
- Should be ON if android.blackLevel.lock was ON in the capture request,
- unless a change in capture settings forced a black level reset.
+ Whether the black level offset was locked for this frame. Should be
+ ON if android.blackLevel.lock was ON in the capture request, unless
+ a change in other capture settings forced the camera device to
+ perform a black level reset.
</details>
</clone>
</dynamic>