From 6216e4e06f00b5b1c1faf739be1fdbe13ad18ca9 Mon Sep 17 00:00:00 2001
From: Chien-Yu Chen <cychen@google.com>
Date: Fri, 29 May 2015 11:49:54 -0700
Subject: [PATCH] Camera2: update docs for reprocess timestamp

Bug: 21112186
Change-Id: Ie49c00c96f7e69b672df5afa34e06e3dcd49490f
---
 .../camera2/CameraCaptureSession.java         | 24 ++++++++++++-------
 .../hardware/camera2/CaptureResult.java       |  4 ++++
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/core/java/android/hardware/camera2/CameraCaptureSession.java b/core/java/android/hardware/camera2/CameraCaptureSession.java
index b3e7cfcf2c7ca..c22ee5f0d6dbc 100644
--- a/core/java/android/hardware/camera2/CameraCaptureSession.java
+++ b/core/java/android/hardware/camera2/CameraCaptureSession.java
@@ -654,16 +654,22 @@ public abstract class CameraCaptureSession implements AutoCloseable {
 
         /**
          * This method is called when the camera device has started capturing
-         * the output image for the request, at the beginning of image exposure.
+         * the output image for the request, at the beginning of image exposure, or
+         * when the camera device has started processing an input image for a reprocess
+         * request.
          *
-         * <p>This callback is invoked right as the capture of a frame begins,
-         * so it is the most appropriate time for playing a shutter sound,
-         * or triggering UI indicators of capture.</p>
+         * <p>For a regular capture request, this callback is invoked right as
+         * the capture of a frame begins, so it is the most appropriate time
+         * for playing a shutter sound, or triggering UI indicators of capture.</p>
          *
          * <p>The request that is being used for this capture is provided, along
-         * with the actual timestamp for the start of exposure. This timestamp
-         * matches the timestamp that will be included in
-         * {@link CaptureResult#SENSOR_TIMESTAMP the result timestamp field},
+         * with the actual timestamp for the start of exposure. For a reprocess
+         * request, this timestamp will be the input image's start of exposure
+         * which matches {@link CaptureResult#SENSOR_TIMESTAMP the result timestamp field}
+         * of the {@link TotalCaptureResult} that was used to
+         * {@link CameraDevice#createReprocessCaptureRequest create the reprocess request}.
+         * This timestamp matches the timestamps that will be
+         * included in {@link CaptureResult#SENSOR_TIMESTAMP the result timestamp field},
          * and in the buffers sent to each output Surface. These buffer
          * timestamps are accessible through, for example,
          * {@link android.media.Image#getTimestamp() Image.getTimestamp()} or
@@ -679,7 +685,9 @@ public abstract class CameraCaptureSession implements AutoCloseable {
          *
          * @param session the session returned by {@link CameraDevice#createCaptureSession}
          * @param request the request for the capture that just begun
-         * @param timestamp the timestamp at start of capture, in nanoseconds.
+         * @param timestamp the timestamp at start of capture for a regular request, or
+         *                  the timestamp at the input image's start of capture for a
+         *                  reprocess request, in nanoseconds.
          * @param frameNumber the frame number for this capture
          *
          * @see android.media.MediaActionSound
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index f4017d0184b3f..96faad285af65 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -2988,6 +2988,10 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * timestamps measure time in the same timebase as {@link android.os.SystemClock#elapsedRealtimeNanos }, and they can
      * be compared to other timestamps from other subsystems that
      * are using that base.</p>
+     * <p>For reprocessing, the timestamp will match the start of exposure of
+     * the input image, i.e. {@link CaptureResult#SENSOR_TIMESTAMP the
+     * timestamp} in the TotalCaptureResult that was used to create the
+     * reprocess capture request.</p>
      * <p><b>Units</b>: Nanoseconds</p>
      * <p><b>Range of valid values:</b><br>
      * &gt; 0</p>