OSDN Git Service

camera_metadata: add max capture stall for reprocess
authorZhijun He <zhijunhe@google.com>
Sat, 25 Apr 2015 00:59:50 +0000 (17:59 -0700)
committerZhijun He <zhijunhe@google.com>
Tue, 28 Apr 2015 17:40:45 +0000 (17:40 +0000)
Bug: 19988710
Change-Id: I05bf3f72fdd54127d9aaa1583e9b0903be94c310

camera/docs/docs.html
camera/docs/metadata_properties.xml
camera/include/system/camera_metadata_tags.h
camera/src/camera_metadata_tag_info.c

index 0ba3e1d..f4bf33e 100644 (file)
             ><a href="#dynamic_android.reprocess.effectiveExposureFactor">android.reprocess.effectiveExposureFactor</a></li>
           </ul>
         </li>
+        <li>
+          <span class="toc_kind_header">static</span>
+          <ul class="toc_section">
+            <li
+            ><a href="#static_android.reprocess.maxCaptureStall">android.reprocess.maxCaptureStall</a></li>
+          </ul>
+        </li>
       </ul> <!-- toc_section -->
     </li>
     <li>
@@ -3447,8 +3454,9 @@ strategy.<wbr/></p>
               <p>This control (except for MANUAL) is only effective if
 <code><a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF</code> and any 3A routine is active.<wbr/></p>
 <p>ZERO_<wbr/>SHUTTER_<wbr/>LAG will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
-contains OPAQUE_<wbr/>REPROCESSING.<wbr/> MANUAL will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
-contains MANUAL_<wbr/>SENSOR.<wbr/> Other intent values are always supported.<wbr/></p>
+contains OPAQUE_<wbr/>REPROCESSING or YUV_<wbr/>REPROCESSING.<wbr/> MANUAL will be supported if
+<a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a> contains MANUAL_<wbr/>SENSOR.<wbr/> Other intent values are
+always supported.<wbr/></p>
             </td>
           </tr>
 
@@ -7611,8 +7619,9 @@ strategy.<wbr/></p>
               <p>This control (except for MANUAL) is only effective if
 <code><a href="#controls_android.control.mode">android.<wbr/>control.<wbr/>mode</a> != OFF</code> and any 3A routine is active.<wbr/></p>
 <p>ZERO_<wbr/>SHUTTER_<wbr/>LAG will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
-contains OPAQUE_<wbr/>REPROCESSING.<wbr/> MANUAL will be supported if <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a>
-contains MANUAL_<wbr/>SENSOR.<wbr/> Other intent values are always supported.<wbr/></p>
+contains OPAQUE_<wbr/>REPROCESSING or YUV_<wbr/>REPROCESSING.<wbr/> MANUAL will be supported if
+<a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a> contains MANUAL_<wbr/>SENSOR.<wbr/> Other intent values are
+always supported.<wbr/></p>
             </td>
           </tr>
 
@@ -8546,6 +8555,7 @@ enhancement.<wbr/></p>
             <td class="entry_tags">
               <ul class="entry_tags">
                   <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -8691,6 +8701,7 @@ device.<wbr/></p>
             <td class="entry_tags">
               <ul class="entry_tags">
                   <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -8795,6 +8806,7 @@ enhancement.<wbr/></p>
             <td class="entry_tags">
               <ul class="entry_tags">
                   <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -13097,6 +13109,7 @@ sensor output.<wbr/> </p></span>
             <td class="entry_tags">
               <ul class="entry_tags">
                   <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -13249,6 +13262,7 @@ by this camera device.<wbr/></p>
             <td class="entry_tags">
               <ul class="entry_tags">
                   <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -13360,6 +13374,7 @@ sensor output.<wbr/> </p></span>
             <td class="entry_tags">
               <ul class="entry_tags">
                   <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -14522,6 +14537,9 @@ that can be configured and used simultaneously by a camera device.<wbr/></p>
             </td>
 
             <td class="entry_tags">
+              <ul class="entry_tags">
+                  <li><a href="#tag_REPROC">REPROC</a></li>
+              </ul>
             </td>
 
           </tr>
@@ -14851,6 +14869,7 @@ raw sensor images.<wbr/></p>
 <li>The maximum available resolution for OPAQUE streams
   (both input/<wbr/>output) will match the maximum available
   resolution of JPEG streams.<wbr/></li>
+<li>Static metadata <a href="#static_android.reprocess.maxCaptureStall">android.<wbr/>reprocess.<wbr/>max<wbr/>Capture<wbr/>Stall</a>.<wbr/></li>
 <li>Only below controls are effective for reprocessing requests and
   will be present in capture results,<wbr/> other controls in reprocess
   requests will be ignored by the camera device.<wbr/><ul>
@@ -14940,6 +14959,7 @@ following:</p>
 <li>The maximum available resolution for YUV_<wbr/>420_<wbr/>888 streams
   (both input/<wbr/>output) will match the maximum available
   resolution of JPEG streams.<wbr/></li>
+<li>Static metadata <a href="#static_android.reprocess.maxCaptureStall">android.<wbr/>reprocess.<wbr/>max<wbr/>Capture<wbr/>Stall</a>.<wbr/></li>
 <li>Only the below controls are effective for reprocessing requests and will be
   present in capture results.<wbr/> The reprocess requests are from the original capture
   results that are assocaited with the intermidate YUV_<wbr/>420_<wbr/>888 output buffers.<wbr/>
@@ -16375,6 +16395,9 @@ camera device for input streams,<wbr/> to their corresponding output formats.<wb
             </td>
 
             <td class="entry_tags">
+              <ul class="entry_tags">
+                  <li><a href="#tag_REPROC">REPROC</a></li>
+              </ul>
             </td>
 
           </tr>
@@ -16757,7 +16780,7 @@ StreamConfigurationMap#getOutputMinFrameDuration)</p>
 
             <td class="entry_description">
               <p>This lists the maximum stall duration for each
-format/<wbr/>size combination.<wbr/></p>
+output format/<wbr/>size combination.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -25004,6 +25027,7 @@ to know when sensor settings have been applied.<wbr/></p>
               <span class="entry_type_visibility"> [public]</span>
 
 
+              <span class="entry_type_hwlevel">[limited] </span>
 
 
 
@@ -25025,7 +25049,7 @@ frame by the application processing before sending for reprocessing.<wbr/></p>
 
             <td class="entry_tags">
               <ul class="entry_tags">
-                  <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -25111,6 +25135,7 @@ Similarly,<wbr/> for edge enhancement reprocessing,<wbr/> it is only effective w
               <span class="entry_type_visibility"> [public]</span>
 
 
+              <span class="entry_type_hwlevel">[limited] </span>
 
 
 
@@ -25132,7 +25157,7 @@ frame by the application processing before sending for reprocessing.<wbr/></p>
 
             <td class="entry_tags">
               <ul class="entry_tags">
-                  <li><a href="#tag_V1">V1</a></li>
+                  <li><a href="#tag_REPROC">REPROC</a></li>
               </ul>
             </td>
 
@@ -25183,6 +25208,101 @@ Similarly,<wbr/> for edge enhancement reprocessing,<wbr/> it is only effective w
 
       <!-- end of kind -->
       </tbody>
+      <tr><td colspan="6" class="kind">static</td></tr>
+
+      <thead class="entries_header">
+        <tr>
+          <th class="th_name">Property Name</th>
+          <th class="th_type">Type</th>
+          <th class="th_description">Description</th>
+          <th class="th_units">Units</th>
+          <th class="th_range">Range</th>
+          <th class="th_tags">Tags</th>
+        </tr>
+      </thead>
+
+      <tbody>
+
+        
+
+        
+
+        
+
+        
+
+                
+          <tr class="entry" id="static_android.reprocess.maxCaptureStall">
+            <td class="entry_name
+             " rowspan="3">
+              android.<wbr/>reprocess.<wbr/>max<wbr/>Capture<wbr/>Stall
+            </td>
+            <td class="entry_type">
+                <span class="entry_type_name">int32</span>
+
+              <span class="entry_type_visibility"> [public]</span>
+
+
+              <span class="entry_type_hwlevel">[limited] </span>
+
+
+
+
+            </td> <!-- entry_type -->
+
+            <td class="entry_description">
+              <p>The maximal camera capture pipeline stall (in unit of frame count) introduced by a
+reprocess capture request.<wbr/></p>
+            </td>
+
+            <td class="entry_units">
+              Number of frames.<wbr/>
+            </td>
+
+            <td class="entry_range">
+              <p>&lt;= 4</p>
+            </td>
+
+            <td class="entry_tags">
+              <ul class="entry_tags">
+                  <li><a href="#tag_REPROC">REPROC</a></li>
+              </ul>
+            </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>The key describes the maximal interference that one reprocess (input) request
+can introduce to the camera simultaneous streaming of regular (output) capture
+requests,<wbr/> including repeating requests.<wbr/></p>
+<p>When a reprocessing capture request is submitted while a camera output repeating request
+(e.<wbr/>g.<wbr/> preview) is being served by the camera device,<wbr/> it may preempt the camera capture
+pipeline for at least one frame duration so that the camera device is unable to process
+the following capture request in time for the next sensor start of exposure boundary.<wbr/>
+When this happens,<wbr/> the application may observe a capture time gap (longer than one frame
+duration) between adjacent capture output frames,<wbr/> which usually exhibits as preview
+glitch if the repeating request output targets include a preview surface.<wbr/> This key gives
+the worst-case number of frame stall introduced by one reprocess request with any kind of
+formats/<wbr/>sizes combination.<wbr/></p>
+<p>If this key reports 0,<wbr/> it means a reprocess request doesn't introduce any glitch to the
+ongoing camera repeating request outputs,<wbr/> as if this reprocess request is never issued.<wbr/></p>
+<p>This key is supported if the camera device supports OPAQUE or YUV reprocessing (
+i.<wbr/>e.<wbr/> <a href="#static_android.request.availableCapabilities">android.<wbr/>request.<wbr/>available<wbr/>Capabilities</a> contains OPAQUE_<wbr/>REPROCESSING or
+YUV_<wbr/>REPROCESSING).<wbr/></p>
+            </td>
+          </tr>
+
+
+          <tr class="entry_spacer"><td class="entry_spacer" colspan="6"></td></tr>
+           <!-- end of entry -->
+        
+        
+
+      <!-- end of kind -->
+      </tbody>
 
   <!-- end of section -->
   <tr><td colspan="6" id="section_depth" class="section">depth</td></tr>
@@ -25429,7 +25549,7 @@ StreamConfigurationMap#getOutputMinFrameDuration)</p>
 
             <td class="entry_description">
               <p>This lists the maximum stall duration for each
-format/<wbr/>size combination for depth streams.<wbr/></p>
+output format/<wbr/>size combination for depth streams.<wbr/></p>
             </td>
 
             <td class="entry_units">
@@ -25657,7 +25777,6 @@ corrupted during depth measurement.<wbr/></p>
           <li><a href="#dynamic_android.statistics.hotPixelMap">android.statistics.hotPixelMap</a> (dynamic)</li>
           <li><a href="#dynamic_android.sync.frameNumber">android.sync.frameNumber</a> (dynamic)</li>
           <li><a href="#static_android.sync.maxLatency">android.sync.maxLatency</a> (static)</li>
-          <li><a href="#controls_android.reprocess.effectiveExposureFactor">android.reprocess.effectiveExposureFactor</a> (controls)</li>
           <li><a href="#dynamic_android.edge.mode">android.edge.mode</a> (dynamic)</li>
           <li><a href="#dynamic_android.hotPixel.mode">android.hotPixel.mode</a> (dynamic)</li>
           <li><a href="#dynamic_android.lens.aperture">android.lens.aperture</a> (dynamic)</li>
@@ -25730,6 +25849,22 @@ corrupted during depth measurement.<wbr/></p>
           <li><a href="#static_android.depth.availableDepthStallDurations">android.depth.availableDepthStallDurations</a> (static)</li>
         </ul>
       </li> <!-- tag_DEPTH -->
+      <li id="tag_REPROC">REPROC - 
+        Entry is required for the YUV or Opaque reprocessing capability.
+    
+        <ul class="tags_entries">
+          <li><a href="#controls_android.edge.mode">android.edge.mode</a> (controls)</li>
+          <li><a href="#static_android.edge.availableEdgeModes">android.edge.availableEdgeModes</a> (static)</li>
+          <li><a href="#controls_android.noiseReduction.mode">android.noiseReduction.mode</a> (controls)</li>
+          <li><a href="#static_android.noiseReduction.availableNoiseReductionModes">android.noiseReduction.availableNoiseReductionModes</a> (static)</li>
+          <li><a href="#static_android.request.maxNumInputStreams">android.request.maxNumInputStreams</a> (static)</li>
+          <li><a href="#static_android.scaler.availableInputOutputFormatsMap">android.scaler.availableInputOutputFormatsMap</a> (static)</li>
+          <li><a href="#controls_android.reprocess.effectiveExposureFactor">android.reprocess.effectiveExposureFactor</a> (controls)</li>
+          <li><a href="#static_android.reprocess.maxCaptureStall">android.reprocess.maxCaptureStall</a> (static)</li>
+          <li><a href="#dynamic_android.edge.mode">android.edge.mode</a> (dynamic)</li>
+          <li><a href="#dynamic_android.noiseReduction.mode">android.noiseReduction.mode</a> (dynamic)</li>
+        </ul>
+      </li> <!-- tag_REPROC -->
       <li id="tag_FUTURE">FUTURE - 
         Entry is  under-specified and is not required for now. This is for book-keeping purpose,
         do not implement or use it, it may be revised for future.
index 5464425..f39d7be 100644 (file)
@@ -36,6 +36,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
     <tag id="DEPTH">
         Entry is required for the depth capability.
     </tag>
+    <tag id="REPROC">
+        Entry is required for the YUV or Opaque reprocessing capability.
+    </tag>
     <tag id="FUTURE">
         Entry is  under-specified and is not required for now. This is for book-keeping purpose,
         do not implement or use it, it may be revised for future.
@@ -1305,8 +1308,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           `android.control.mode != OFF` and any 3A routine is active.
 
           ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities
-          contains OPAQUE_REPROCESSING. MANUAL will be supported if android.request.availableCapabilities
-          contains MANUAL_SENSOR. Other intent values are always supported.
+          contains OPAQUE_REPROCESSING or YUV_REPROCESSING. MANUAL will be supported if
+          android.request.availableCapabilities contains MANUAL_SENSOR. Other intent values are
+          always supported.
           </details>
           <tag id="BC" />
         </entry>
@@ -2625,6 +2629,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           quality images.
           </hal_details>
           <tag id="V1" />
+          <tag id="REPROC" />
         </entry>
         <entry name="strength" type="byte">
           <description>Control the amount of edge enhancement
@@ -2655,11 +2660,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           capture rate, then FAST and HIGH_QUALITY will generate the same output.
           </hal_details>
           <tag id="V1" />
+          <tag id="REPROC" />
         </entry>
       </static>
       <dynamic>
         <clone entry="android.edge.mode" kind="controls">
           <tag id="V1" />
+          <tag id="REPROC" />
         </clone>
       </dynamic>
     </section>
@@ -3702,6 +3709,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           images.
           </hal_details>
           <tag id="V1" />
+          <tag id="REPROC" />
         </entry>
         <entry name="strength" type="byte">
           <description>Control the amount of noise reduction
@@ -3734,11 +3742,13 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           capture rate, then FAST and HIGH_QUALITY will generate the same output.
           </hal_details>
           <tag id="V1" />
+          <tag id="REPROC" />
         </entry>
       </static>
       <dynamic>
         <clone entry="android.noiseReduction.mode" kind="controls">
           <tag id="V1" />
+          <tag id="REPROC" />
         </clone>
       </dynamic>
     </section>
@@ -4096,6 +4106,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           For the reprocessing flow and controls, see
           hardware/libhardware/include/hardware/camera3.h Section 10 for more details.
           </hal_details>
+          <tag id="REPROC" />
         </entry>
       </static>
       <dynamic>
@@ -4306,6 +4317,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               * The maximum available resolution for OPAQUE streams
                 (both input/output) will match the maximum available
                 resolution of JPEG streams.
+              * Static metadata android.reprocess.maxCaptureStall.
               * Only below controls are effective for reprocessing requests and
                 will be present in capture results, other controls in reprocess
                 requests will be ignored by the camera device.
@@ -4388,6 +4400,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
               * The maximum available resolution for YUV_420_888 streams
                 (both input/output) will match the maximum available
                 resolution of JPEG streams.
+              * Static metadata android.reprocess.maxCaptureStall.
               * Only the below controls are effective for reprocessing requests and will be
                 present in capture results. The reprocess requests are from the original capture
                 results that are assocaited with the intermidate YUV_420_888 output buffers.
@@ -4981,6 +4994,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
           combinations listed for that capability. It can optionally support
           additional formats if it so chooses.
           </hal_details>
+          <tag id="REPROC" />
         </entry>
         <entry name="availableStreamConfigurations" type="int32" visibility="hidden"
           enum="true" container="array"
@@ -5122,7 +5136,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>This lists the maximum stall duration for each
-          format/size combination.
+          output format/size combination.
           </description>
           <units>(format, width, height, ns) x n</units>
           <details>
@@ -7871,7 +7885,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
     </section>
     <section name="reprocess">
       <controls>
-        <entry name="effectiveExposureFactor" type="float" visibility="public">
+        <entry name="effectiveExposureFactor" type="float" visibility="public" hwlevel="limited">
             <description>
             The amount of exposure time increase factor applied to the original output
             frame by the application processing before sending for reprocessing.
@@ -7914,13 +7928,46 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             Similarly, for edge enhancement reprocessing, it is only effective when
             `android.edge.mode != OFF`.
             </details>
-          <tag id="V1" />
+          <tag id="REPROC" />
         </entry>
       </controls>
       <dynamic>
       <clone entry="android.reprocess.effectiveExposureFactor" kind="controls">
       </clone>
       </dynamic>
+      <static>
+        <entry name="maxCaptureStall" type="int32" visibility="public" hwlevel="limited">
+          <description>
+          The maximal camera capture pipeline stall (in unit of frame count) introduced by a
+          reprocess capture request.
+          </description>
+          <units>Number of frames.</units>
+          <range> &amp;lt;= 4</range>
+          <details>
+          The key describes the maximal interference that one reprocess (input) request
+          can introduce to the camera simultaneous streaming of regular (output) capture
+          requests, including repeating requests.
+
+          When a reprocessing capture request is submitted while a camera output repeating request
+          (e.g. preview) is being served by the camera device, it may preempt the camera capture
+          pipeline for at least one frame duration so that the camera device is unable to process
+          the following capture request in time for the next sensor start of exposure boundary.
+          When this happens, the application may observe a capture time gap (longer than one frame
+          duration) between adjacent capture output frames, which usually exhibits as preview
+          glitch if the repeating request output targets include a preview surface. This key gives
+          the worst-case number of frame stall introduced by one reprocess request with any kind of
+          formats/sizes combination.
+
+          If this key reports 0, it means a reprocess request doesn't introduce any glitch to the
+          ongoing camera repeating request outputs, as if this reprocess request is never issued.
+
+          This key is supported if the camera device supports OPAQUE or YUV reprocessing (
+          i.e. android.request.availableCapabilities contains OPAQUE_REPROCESSING or
+          YUV_REPROCESSING).
+          </details>
+          <tag id="REPROC" />
+        </entry>
+      </static>
     </section>
     <section name="depth">
       <static>
@@ -8008,7 +8055,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
             <size>n</size>
           </array>
           <description>This lists the maximum stall duration for each
-          format/size combination for depth streams.
+          output format/size combination for depth streams.
           </description>
           <units>(format, width, height, ns) x n</units>
           <details>
index 98d5e79..c859650 100644 (file)
@@ -393,6 +393,7 @@ typedef enum camera_metadata_tag {
 
     ANDROID_REPROCESS_EFFECTIVE_EXPOSURE_FACTOR =     // float        | public
             ANDROID_REPROCESS_START,
+    ANDROID_REPROCESS_MAX_CAPTURE_STALL,              // int32        | public
     ANDROID_REPROCESS_END,
 
     ANDROID_DEPTH_MAX_DEPTH_SAMPLES =                 // int32        | system
index 4126d57..33325c9 100644 (file)
@@ -639,6 +639,8 @@ static tag_info_t android_reprocess[ANDROID_REPROCESS_END -
         ANDROID_REPROCESS_START] = {
     [ ANDROID_REPROCESS_EFFECTIVE_EXPOSURE_FACTOR - ANDROID_REPROCESS_START ] =
     { "effectiveExposureFactor",       TYPE_FLOAT  },
+    [ ANDROID_REPROCESS_MAX_CAPTURE_STALL - ANDROID_REPROCESS_START ] =
+    { "maxCaptureStall",               TYPE_INT32  },
 };
 
 static tag_info_t android_depth[ANDROID_DEPTH_END -
@@ -2493,6 +2495,9 @@ int camera_metadata_enum_snprint(uint32_t tag,
         case ANDROID_REPROCESS_EFFECTIVE_EXPOSURE_FACTOR: {
             break;
         }
+        case ANDROID_REPROCESS_MAX_CAPTURE_STALL: {
+            break;
+        }
 
         case ANDROID_DEPTH_MAX_DEPTH_SAMPLES: {
             break;