camera3: Update sceneMode tag spec.
Change-Id: I495435397086a295280c556d94fe8efd442a12c3
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 9f7883b..bd752bb 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -2276,7 +2276,7 @@
<tr class="entry" id="controls_android.control.sceneMode">
- <td class="entry_name" rowspan="1">
+ <td class="entry_name" rowspan="5">
android.<wbr/>control.<wbr/>scene<wbr/>Mode
</td>
<td class="entry_type">
@@ -2286,88 +2286,113 @@
<ul class="entry_type_enum">
<li>
- <span class="entry_type_enum_name">UNSUPPORTED</span>
+ <span class="entry_type_enum_name">DISABLED</span>
<span class="entry_type_enum_value">0</span>
+ <span class="entry_type_enum_notes"><p>Indicates that no scene modes are set for a given capture request.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">FACE_PRIORITY</span>
- <span class="entry_type_enum_notes"><p>if face detection support exists Use face
-detection data to drive 3A routines.<wbr/> If face detection
-statistics are disabled,<wbr/> should still operate correctly
-(but not return face detection statistics to the
-framework).<wbr/></p>
-<p>Unlike the other scene modes,<wbr/> aeMode,<wbr/> awbMode,<wbr/> and afMode
-remain active when FACE_<wbr/>PRIORITY is set.<wbr/> This is due to
-compatibility concerns with the old camera
-API</p></span>
+ <span class="entry_type_enum_notes"><p>If face detection support exists,<wbr/> use face
+detection data for auto-focus,<wbr/> auto-white balance,<wbr/> and
+auto-exposure routines.<wbr/> If face detection statistics are
+disabled (i.<wbr/>e.<wbr/> <a href="#controls_android.statistics.faceDetectMode">android.<wbr/>statistics.<wbr/>face<wbr/>Detect<wbr/>Mode</a> is set to OFF),<wbr/>
+this should still operate correctly (but will not return
+face detection statistics to the framework).<wbr/></p>
+<p>Unlike the other scene modes,<wbr/> <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a>,<wbr/>
+<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>,<wbr/> and android.<wbr/>control.<wbr/>af<wbr/>Mode
+remain active when FACE_<wbr/>PRIORITY is set.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">ACTION</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for photos of quickly moving objects.<wbr/>
+Similar to SPORTS.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">PORTRAIT</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for still photos of people.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">LANDSCAPE</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for photos of distant macroscopic objects.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">NIGHT</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for low-light settings.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">NIGHT_PORTRAIT</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for still photos of people in low-light
+settings.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">THEATRE</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for dim,<wbr/> indoor settings where flash must
+remain off.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">BEACH</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for bright,<wbr/> outdoor beach settings.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">SNOW</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for bright,<wbr/> outdoor settings containing snow.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">SUNSET</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for scenes of the setting sun.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">STEADYPHOTO</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized to avoid blurry photos due to small amounts of
+device motion (for example: due to hand shake).<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">FIREWORKS</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for nighttime photos of fireworks.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">SPORTS</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for photos of quickly moving people.<wbr/>
+Similar to ACTION.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">PARTY</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for dim,<wbr/> indoor settings with multiple moving
+people.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">CANDLELIGHT</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for dim settings where the main light source
+is a flame.<wbr/></p></span>
</li>
<li>
<span class="entry_type_enum_name">BARCODE</span>
<span class="entry_type_enum_optional">optional</span>
+ <span class="entry_type_enum_notes"><p>Optimized for accurately capturing a photo of barcode
+for use by camera applications that wish to read the
+barcode value.<wbr/></p></span>
</li>
</ul>
</td> <!-- entry_type -->
<td class="entry_description">
- <p>Which scene mode is active when
-<a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> = SCENE_<wbr/>MODE</p>
+ <p>A camera mode optimized for conditions typical in a particular
+capture setting.<wbr/></p>
</td>
<td class="entry_units">
@@ -2384,7 +2409,33 @@
</td>
</tr>
+ <tr class="entries_header">
+ <th class="th_details" colspan="5">Details</th>
+ </tr>
+ <tr class="entry_cont">
+ <td class="entry_details" colspan="5">
+ <p>This is the mode that that is active when
+<code><a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> == USE_<wbr/>SCENE_<wbr/>MODE</code>.<wbr/> Aside from FACE_<wbr/>PRIORITY,<wbr/>
+these modes will disable <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a>,<wbr/>
+<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>,<wbr/> and <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a> while in use.<wbr/></p>
+<p>The interpretation and implementation of these scene modes is left
+to the implementor of the camera device.<wbr/> Their behavior will not be
+consistent across all devices,<wbr/> and any given device may only implement
+a subset of these modes.<wbr/></p>
+ </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">
+ <p>HAL implementations that include scene modes are expected to provide
+the per-scene settings to use for <a href="#controls_android.control.aeMode">android.<wbr/>control.<wbr/>ae<wbr/>Mode</a>,<wbr/>
+<a href="#controls_android.control.awbMode">android.<wbr/>control.<wbr/>awb<wbr/>Mode</a>,<wbr/> and <a href="#controls_android.control.afMode">android.<wbr/>control.<wbr/>af<wbr/>Mode</a> in
+<a href="#static_android.control.sceneModeOverrides">android.<wbr/>control.<wbr/>scene<wbr/>Mode<wbr/>Overrides</a>.<wbr/></p>
+ </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 30cbfbf..c94bcff 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -768,37 +768,131 @@
</entry>
<entry name="sceneMode" type="byte" visibility="public" enum="true">
<enum>
- <value id="0">UNSUPPORTED</value>
+ <value id="0">DISABLED
+ <notes>
+ Indicates that no scene modes are set for a given capture request.
+ </notes>
+ </value>
<value>FACE_PRIORITY
- <notes>if face detection support exists Use face
- detection data to drive 3A routines. If face detection
- statistics are disabled, should still operate correctly
- (but not return face detection statistics to the
- framework).
+ <notes>If face detection support exists, use face
+ detection data for auto-focus, auto-white balance, and
+ auto-exposure routines. If face detection statistics are
+ disabled (i.e. android.statistics.faceDetectMode is set to OFF),
+ this should still operate correctly (but will not return
+ face detection statistics to the framework).
- Unlike the other scene modes, aeMode, awbMode, and afMode
- remain active when FACE_PRIORITY is set. This is due to
- compatibility concerns with the old camera
- API</notes></value>
- <value optional="true">ACTION</value>
- <value optional="true">PORTRAIT</value>
- <value optional="true">LANDSCAPE</value>
- <value optional="true">NIGHT</value>
- <value optional="true">NIGHT_PORTRAIT</value>
- <value optional="true">THEATRE</value>
- <value optional="true">BEACH</value>
- <value optional="true">SNOW</value>
- <value optional="true">SUNSET</value>
- <value optional="true">STEADYPHOTO</value>
- <value optional="true">FIREWORKS</value>
- <value optional="true">SPORTS</value>
- <value optional="true">PARTY</value>
- <value optional="true">CANDLELIGHT</value>
- <value optional="true">BARCODE</value>
+ Unlike the other scene modes, android.control.aeMode,
+ android.control.awbMode, and android.control.afMode
+ remain active when FACE_PRIORITY is set.
+ </notes>
+ </value>
+ <value optional="true">ACTION
+ <notes>
+ Optimized for photos of quickly moving objects.
+ Similar to SPORTS.
+ </notes>
+ </value>
+ <value optional="true">PORTRAIT
+ <notes>
+ Optimized for still photos of people.
+ </notes>
+ </value>
+ <value optional="true">LANDSCAPE
+ <notes>
+ Optimized for photos of distant macroscopic objects.
+ </notes>
+ </value>
+ <value optional="true">NIGHT
+ <notes>
+ Optimized for low-light settings.
+ </notes>
+ </value>
+ <value optional="true">NIGHT_PORTRAIT
+ <notes>
+ Optimized for still photos of people in low-light
+ settings.
+ </notes>
+ </value>
+ <value optional="true">THEATRE
+ <notes>
+ Optimized for dim, indoor settings where flash must
+ remain off.
+ </notes>
+ </value>
+ <value optional="true">BEACH
+ <notes>
+ Optimized for bright, outdoor beach settings.
+ </notes>
+ </value>
+ <value optional="true">SNOW
+ <notes>
+ Optimized for bright, outdoor settings containing snow.
+ </notes>
+ </value>
+ <value optional="true">SUNSET
+ <notes>
+ Optimized for scenes of the setting sun.
+ </notes>
+ </value>
+ <value optional="true">STEADYPHOTO
+ <notes>
+ Optimized to avoid blurry photos due to small amounts of
+ device motion (for example: due to hand shake).
+ </notes>
+ </value>
+ <value optional="true">FIREWORKS
+ <notes>
+ Optimized for nighttime photos of fireworks.
+ </notes>
+ </value>
+ <value optional="true">SPORTS
+ <notes>
+ Optimized for photos of quickly moving people.
+ Similar to ACTION.
+ </notes>
+ </value>
+ <value optional="true">PARTY
+ <notes>
+ Optimized for dim, indoor settings with multiple moving
+ people.
+ </notes>
+ </value>
+ <value optional="true">CANDLELIGHT
+ <notes>
+ Optimized for dim settings where the main light source
+ is a flame.
+ </notes>
+ </value>
+ <value optional="true">BARCODE
+ <notes>
+ Optimized for accurately capturing a photo of barcode
+ for use by camera applications that wish to read the
+ barcode value.
+ </notes>
+ </value>
</enum>
- <description>Which scene mode is active when
- android.control.mode = SCENE_MODE</description>
+ <description>
+ A camera mode optimized for conditions typical in a particular
+ capture setting.
+ </description>
<range>android.control.availableSceneModes</range>
+ <details>
+ This is the mode that that is active when
+ `android.control.mode == USE_SCENE_MODE`. Aside from FACE_PRIORITY,
+ these modes will disable android.control.aeMode,
+ android.control.awbMode, and android.control.afMode while in use.
+
+ The interpretation and implementation of these scene modes is left
+ to the implementor of the camera device. Their behavior will not be
+ consistent across all devices, and any given device may only implement
+ a subset of these modes.
+ </details>
+ <hal_details>
+ HAL implementations that include scene modes are expected to provide
+ the per-scene settings to use for android.control.aeMode,
+ android.control.awbMode, and android.control.afMode in
+ android.control.sceneModeOverrides.
+ </hal_details>
<tag id="BC" />
</entry>
<entry name="videoStabilizationMode" type="byte" visibility="public"
diff --git a/camera/include/system/camera_metadata_tags.h b/camera/include/system/camera_metadata_tags.h
index a15c2c8..d745b64 100644
--- a/camera/include/system/camera_metadata_tags.h
+++ b/camera/include/system/camera_metadata_tags.h
@@ -456,7 +456,7 @@
// ANDROID_CONTROL_SCENE_MODE
typedef enum camera_metadata_enum_android_control_scene_mode {
- ANDROID_CONTROL_SCENE_MODE_UNSUPPORTED = 0,
+ ANDROID_CONTROL_SCENE_MODE_DISABLED = 0,
ANDROID_CONTROL_SCENE_MODE_FACE_PRIORITY,
ANDROID_CONTROL_SCENE_MODE_ACTION,
ANDROID_CONTROL_SCENE_MODE_PORTRAIT,
diff --git a/camera/src/camera_metadata_tag_info.c b/camera/src/camera_metadata_tag_info.c
index 7511249..13e3443 100644
--- a/camera/src/camera_metadata_tag_info.c
+++ b/camera/src/camera_metadata_tag_info.c
@@ -910,8 +910,8 @@
}
case ANDROID_CONTROL_SCENE_MODE: {
switch (value) {
- case ANDROID_CONTROL_SCENE_MODE_UNSUPPORTED:
- msg = "UNSUPPORTED";
+ case ANDROID_CONTROL_SCENE_MODE_DISABLED:
+ msg = "DISABLED";
ret = 0;
break;
case ANDROID_CONTROL_SCENE_MODE_FACE_PRIORITY: