Merge "Camera2: Many docs updates" into lmp-preview-dev

10 files changed, 336 insertions, 830 deletions

diff --git a/core/java/android/hardware/camera2/CameraCaptureSession.java b/core/java/android/hardware/camera2/CameraCaptureSession.java
index 5fd0f9b..d98bdc2 100644
--- a/core/java/android/hardware/camera2/CameraCaptureSession.java
+++ b/core/java/android/hardware/camera2/CameraCaptureSession.java
@@ -29,19 +29,19 @@ import java.util.List;
  *
  * <p>Creating a session is an expensive operation and can take several hundred milliseconds, since
  * it requires configuring the camera device's internal pipelines and allocating memory buffers for
- * sending images to the desired targets. While
- * {@link CameraDevice#createCaptureSession createCaptureSession} will provide a
- * CameraCaptureSession object immediately, configuration won't be complete until the
- * {@link CameraCaptureSession.StateListener#onConfigured onConfigured} callback is called for the
- * first time. If configuration cannot be completed, then the
+ * sending images to the desired targets. Therefore the setup is done asynchronously, and
+ * {@link CameraDevice#createCaptureSession createCaptureSession} will send the ready-to-use
+ * CameraCaptureSession to the provided listener's
+ * {@link CameraCaptureSession.StateListener#onConfigured onConfigured} callback. If configuration
+ * cannot be completed, then the
  * {@link CameraCaptureSession.StateListener#onConfigureFailed onConfigureFailed} is called, and the
  * session will not become active.</p>
- *
+ *<!--
  * <p>Any capture requests (repeating or non-repeating) submitted before the session is ready will
  * be queued up and will begin capture once the session becomes ready. In case the session cannot be
  * configured and {@link StateListener#onConfigureFailed onConfigureFailed} is called, all queued
  * capture requests are discarded.</p>
- *
+ *-->
  * <p>If a new session is created by the camera device, then the previous session is closed, and its
  * associated {@link StateListener#onClosed onClosed} callback will be invoked.  All
  * of the session methods will throw an IllegalStateException if called once the session is
@@ -166,10 +166,6 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      * capture request will be processed before any further repeating
      * requests are processed.<p>
      *
-     * <p>Repeating requests are a simple way for an application to maintain a
-     * preview or other continuous stream of frames, without having to submit
-     * requests through {@link #capture} at video rates.</p>
-     *
      * <p>To stop the repeating capture, call {@link #stopRepeating}. Calling
      * {@link #abortCaptures} will also clear the request.</p>
      *
@@ -323,7 +319,7 @@ public abstract class CameraCaptureSession implements AutoCloseable {
      *
      * @see #setRepeatingRequest
      * @see #setRepeatingBurst
-     * @see #configureOutputs
+     * @see CameraDevice#createCaptureSession
      */
     public abstract void abortCaptures() throws CameraAccessException;
 
diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java
index 08cfc87..ff56720 100644
--- a/core/java/android/hardware/camera2/CameraCharacteristics.java
+++ b/core/java/android/hardware/camera2/CameraCharacteristics.java
@@ -320,7 +320,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
 
     /**
      * <p>List of frame rate ranges supported by the
-     * AE algorithm/hardware</p>
+     * auto-exposure (AE) algorithm/hardware</p>
      */
     public static final Key<android.util.Range<Integer>[]> CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES =
             new Key<android.util.Range<Integer>[]>("android.control.aeAvailableTargetFpsRanges", new TypeReference<android.util.Range<Integer>[]>() {{ }});
@@ -343,7 +343,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
             new Key<Rational>("android.control.aeCompensationStep", Rational.class);
 
     /**
-     * <p>List of AF modes that can be
+     * <p>List of auto-focus (AF) modes that can be
      * selected with {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}.</p>
      * <p>Not all the auto-focus modes may be supported by a
      * given camera device. This entry lists the valid modes for
@@ -496,7 +496,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
             new Key<int[]>("android.hotPixel.availableHotPixelModes", int[].class);
 
     /**
-     * <p>Supported resolutions for the JPEG thumbnail</p>
+     * <p>Supported resolutions for the JPEG thumbnail.</p>
      * <p>Below condiditions will be satisfied for this size list:</p>
      * <ul>
      * <li>The sizes will be sorted by increasing pixel area (width x height).
@@ -784,11 +784,12 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
      * may be delivered to the application layer from the camera device as
      * soon as they are available.</p>
      * <p>A value of 1 means that partial results are not supported.</p>
-     * <p>A typical use case for this might be: after requesting an AF lock the
-     * new AF state might be available 50% of the way through the pipeline.
-     * The camera device could then immediately dispatch this state via a
-     * partial result to the framework/application layer, and the rest of
-     * the metadata via later partial results.</p>
+     * <p>A typical use case for this might be: after requesting an
+     * auto-focus (AF) lock the new AF state might be available 50%
+     * of the way through the pipeline.  The camera device could
+     * then immediately dispatch this state via a partial result to
+     * the framework/application layer, and the rest of the
+     * metadata via later partial results.</p>
      */
     public static final Key<Integer> REQUEST_PARTIAL_RESULT_COUNT =
             new Key<Integer>("android.request.partialResultCount", int.class);
@@ -1326,7 +1327,13 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
             new Key<android.graphics.Rect>("android.sensor.info.activeArraySize", android.graphics.Rect.class);
 
     /**
-     * <p>Range of valid sensitivities</p>
+     * <p>Range of valid sensitivities.</p>
+     * <p>The minimum and maximum valid values for the
+     * {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} control.</p>
+     * <p>The values are the standard ISO sensitivity values,
+     * as defined in ISO 12232:2006.</p>
+     *
+     * @see CaptureRequest#SENSOR_SENSITIVITY
      */
     public static final Key<android.util.Range<Integer>> SENSOR_INFO_SENSITIVITY_RANGE =
             new Key<android.util.Range<Integer>>("android.sensor.info.sensitivityRange", new TypeReference<android.util.Range<Integer>>() {{ }});
@@ -1372,8 +1379,11 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
 
     /**
      * <p>The physical dimensions of the full pixel
-     * array</p>
-     * <p>Needed for FOV calculation for old API</p>
+     * array.</p>
+     * <p>This is the physical size of the sensor pixel
+     * array defined by {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</p>
+     *
+     * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
      */
     public static final Key<android.util.SizeF> SENSOR_INFO_PHYSICAL_SIZE =
             new Key<android.util.SizeF>("android.sensor.info.physicalSize", android.util.SizeF.class);
@@ -1381,9 +1391,17 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
     /**
      * <p>Dimensions of full pixel array, possibly
      * including black calibration pixels.</p>
-     * <p>Maximum output resolution for raw format must
-     * match this in
-     * android.scaler.availableStreamConfigurations.</p>
+     * <p>The pixel count of the full pixel array,
+     * which covers {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} area.</p>
+     * <p>If a camera device supports raw sensor formats, either this
+     * or {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} is the maximum output
+     * raw size listed in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}.
+     * If a size corresponding to pixelArraySize is listed, the resulting
+     * raw sensor image will include black pixels.</p>
+     *
+     * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
+     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
+     * @see CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE
      */
     public static final Key<android.util.Size> SENSOR_INFO_PIXEL_ARRAY_SIZE =
             new Key<android.util.Size>("android.sensor.info.pixelArraySize", android.util.Size.class);
@@ -1638,8 +1656,8 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
             new Key<Integer>("android.sensor.orientation", int.class);
 
     /**
-     * <p>Optional. Defaults to [OFF]. Lists the supported test
-     * pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}.</p>
+     * <p>Lists the supported sensor test pattern modes for {@link CaptureRequest#SENSOR_TEST_PATTERN_MODE android.sensor.testPatternMode}.</p>
+     * <p>Optional. Defaults to [OFF].</p>
      * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
      *
      * @see CaptureRequest#SENSOR_TEST_PATTERN_MODE
@@ -1649,7 +1667,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
 
     /**
      * <p>Which face detection modes are available,
-     * if any</p>
+     * if any.</p>
      * <p>OFF means face detection is disabled, it must
      * be included in the list.</p>
      * <p>SIMPLE means the device supports the
diff --git a/core/java/android/hardware/camera2/CameraDevice.java b/core/java/android/hardware/camera2/CameraDevice.java
index e9213c5..68f4d64 100644
--- a/core/java/android/hardware/camera2/CameraDevice.java
+++ b/core/java/android/hardware/camera2/CameraDevice.java
@@ -52,7 +52,7 @@ public abstract class CameraDevice implements AutoCloseable {
      * Create a request suitable for a camera preview window. Specifically, this
      * means that high frame rate is given priority over the highest-quality
      * post-processing. These requests would normally be used with the
-     * {@link #setRepeatingRequest} method.
+     * {@link CameraCaptureSession#setRepeatingRequest} method.
      *
      * @see #createCaptureRequest
      */
@@ -61,7 +61,7 @@ public abstract class CameraDevice implements AutoCloseable {
     /**
      * Create a request suitable for still image capture. Specifically, this
      * means prioritizing image quality over frame rate. These requests would
-     * commonly be used with the {@link #capture} method.
+     * commonly be used with the {@link CameraCaptureSession#capture} method.
      *
      * @see #createCaptureRequest
      */
@@ -71,7 +71,7 @@ public abstract class CameraDevice implements AutoCloseable {
      * Create a request suitable for video recording. Specifically, this means
      * that a stable frame rate is used, and post-processing is set for
      * recording quality. These requests would commonly be used with the
-     * {@link #setRepeatingRequest} method.
+     * {@link CameraCaptureSession#setRepeatingRequest} method.
      *
      * @see #createCaptureRequest
      */
@@ -81,8 +81,8 @@ public abstract class CameraDevice implements AutoCloseable {
      * Create a request suitable for still image capture while recording
      * video. Specifically, this means maximizing image quality without
      * disrupting the ongoing recording. These requests would commonly be used
-     * with the {@link #capture} method while a request based on
-     * {@link #TEMPLATE_RECORD} is is in use with {@link #setRepeatingRequest}.
+     * with the {@link CameraCaptureSession#capture} method while a request based on
+     * {@link #TEMPLATE_RECORD} is is in use with {@link CameraCaptureSession#setRepeatingRequest}.
      *
      * @see #createCaptureRequest
      */
@@ -132,116 +132,6 @@ public abstract class CameraDevice implements AutoCloseable {
     /**
      * <p>Set up a new output set of Surfaces for the camera device.</p>
      *
-     * <p>The configuration determines the set of potential output Surfaces for
-     * the camera device for each capture request. A given request may use all
-     * or a only some of the outputs. This method must be called before requests
-     * can be submitted to the camera with {@link #capture capture},
-     * {@link #captureBurst captureBurst},
-     * {@link #setRepeatingRequest setRepeatingRequest}, or
-     * {@link #setRepeatingBurst setRepeatingBurst}.</p>
-     *
-     * <p>Surfaces suitable for inclusion as a camera output can be created for
-     * various use cases and targets:</p>
-     *
-     * <ul>
-     *
-     * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Set
-     *   the size of the Surface with
-     *   {@link android.view.SurfaceHolder#setFixedSize} to be one of the
-     *   supported
-     *   {@link StreamConfigurationMap#getOutputSizes(Class) processed sizes}
-     *   before calling {@link android.view.SurfaceHolder#getSurface}.</li>
-     *
-     * <li>For accessing through an OpenGL texture via a
-     *   {@link android.graphics.SurfaceTexture SurfaceTexture}: Set the size of
-     *   the SurfaceTexture with
-     *   {@link android.graphics.SurfaceTexture#setDefaultBufferSize} to be one
-     *   of the supported
-     *   {@link StreamConfigurationMap#getOutputSizes(Class) processed sizes}
-     *   before creating a Surface from the SurfaceTexture with
-     *   {@link Surface#Surface}.</li>
-     *
-     * <li>For recording with {@link android.media.MediaCodec}: Call
-     *   {@link android.media.MediaCodec#createInputSurface} after configuring
-     *   the media codec to use one of the
-     *   {@link StreamConfigurationMap#getOutputSizes(Class) processed sizes}
-     *   </li>
-     *
-     * <li>For recording with {@link android.media.MediaRecorder}: TODO</li>
-     *
-     * <li>For efficient YUV processing with {@link android.renderscript}:
-     *   Create a RenderScript
-     *   {@link android.renderscript.Allocation Allocation} with a supported YUV
-     *   type, the IO_INPUT flag, and one of the supported
-     *   {@link StreamConfigurationMap#getOutputSizes(int) processed sizes}. Then
-     *   obtain the Surface with
-     *   {@link android.renderscript.Allocation#getSurface}.</li>
-     *
-     * <li>For access to uncompressed or {@link ImageFormat#JPEG JPEG} data in the application:
-     * Create a {@link android.media.ImageReader} object with the desired
-     * {@link StreamConfigurationMap#getOutputFormats() image format}, and a size from the matching
-     * {@link StreamConfigurationMap#getOutputSizes(int) processed size} and {@code format}.
-     * Then obtain a {@link Surface} from it.</li>
-     * </ul>
-     *
-     * </p>
-     *
-     * <p>This function can take several hundred milliseconds to execute, since
-     * camera hardware may need to be powered on or reconfigured.</p>
-     *
-     * <p>The camera device will query each Surface's size and formats upon this
-     * call, so they must be set to a valid setting at this time (in particular:
-     * if the format is user-visible, it must be one of
-     * {@link StreamConfigurationMap#getOutputFormats}; and the size must be one of
-     * {@link StreamConfigurationMap#getOutputSizes(int)}).</p>
-     *
-     * <p>When this method is called with valid Surfaces, the device will transition to the {@link
-     * StateListener#onBusy busy state}. Once configuration is complete, the device will transition
-     * into the {@link StateListener#onIdle idle state}. Capture requests using the newly-configured
-     * Surfaces may then be submitted with {@link #capture}, {@link #captureBurst}, {@link
-     * #setRepeatingRequest}, or {@link #setRepeatingBurst}.</p>
-     *
-     * <p>If this method is called while the camera device is still actively processing previously
-     * submitted captures, then the following sequence of events occurs: The device transitions to
-     * the busy state and calls the {@link StateListener#onBusy} callback. Second, if a repeating
-     * request is set it is cleared.  Third, the device finishes up all in-flight and pending
-     * requests. Finally, once the device is idle, it then reconfigures its outputs, and calls the
-     * {@link StateListener#onIdle} method once it is again ready to accept capture
-     * requests. Therefore, no submitted work is discarded. To idle as fast as possible, use {@link
-     * #flush} and wait for the idle callback before calling configureOutputs. This will discard
-     * work, but reaches the new configuration sooner.</p>
-     *
-     * <p>Using larger resolution outputs, or more outputs, can result in slower
-     * output rate from the device.</p>
-     *
-     * <p>Configuring the outputs with an empty or null list will transition the camera into an
-     * {@link StateListener#onUnconfigured unconfigured state} instead of the {@link
-     * StateListener#onIdle idle state}.  </p>
-     *
-     * <p>Calling configureOutputs with the same arguments as the last call to
-     * configureOutputs has no effect, and the {@link StateListener#onBusy busy}
-     * and {@link StateListener#onIdle idle} state transitions will happen
-     * immediately.</p>
-     *
-     * @param outputs The new set of Surfaces that should be made available as
-     * targets for captured image data.
-     *
-     * @throws IllegalArgumentException if the set of output Surfaces do not
-     * meet the requirements
-     * @throws CameraAccessException if the camera device is no longer connected or has
-     *                               encountered a fatal error
-     * @throws IllegalStateException if the camera device is not idle, or
-     *                               if the camera device has been closed
-     *
-     * @see StateListener#onBusy
-     * @see StateListener#onIdle
-     * @see StateListener#onActive
-     * @see StateListener#onUnconfigured
-     * @see #stopRepeating
-     * @see #flush
-     * @see StreamConfigurationMap#getOutputFormats()
-     * @see StreamConfigurationMap#getOutputSizes(int)
-     * @see StreamConfigurationMap#getOutputSizes(Class)
      * @deprecated Use {@link #createCaptureSession} instead
      */
     @Deprecated
@@ -342,10 +232,7 @@ public abstract class CameraDevice implements AutoCloseable {
      * @param listener The listener to notify about the status of the new capture session.
      * @param handler The handler on which the listener should be invoked, or {@code null} to use
      *                the current thread's {@link android.os.Looper looper}.
-     * <!--
-     * @return A new camera capture session to use, or null if an empty/null set of Surfaces is
-     *         provided.
-     * -->
+     *
      * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements,
      *                                  the listener is null, or the handler is null but the current
      *                                  thread has no looper.
@@ -393,92 +280,16 @@ public abstract class CameraDevice implements AutoCloseable {
     /**
      * <p>Submit a request for an image to be captured by this CameraDevice.</p>
      *
-     * <p>The request defines all the parameters for capturing the single image,
-     * including sensor, lens, flash, and post-processing settings.</p>
-     *
-     * <p>Each request will produce one {@link CaptureResult} and produce new
-     * frames for one or more target Surfaces, set with the CaptureRequest
-     * builder's {@link CaptureRequest.Builder#addTarget} method. The target
-     * surfaces must be configured as active outputs with
-     * {@link #configureOutputs} before calling this method.</p>
-     *
-     * <p>Multiple requests can be in progress at once. They are processed in
-     * first-in, first-out order, with minimal delays between each
-     * capture. Requests submitted through this method have higher priority than
-     * those submitted through {@link #setRepeatingRequest} or
-     * {@link #setRepeatingBurst}, and will be processed as soon as the current
-     * repeat/repeatBurst processing completes.</p>
-     *
-     * @param request the settings for this capture
-     * @param listener The callback object to notify once this request has been
-     * processed. If null, no metadata will be produced for this capture,
-     * although image data will still be produced.
-     * @param handler the handler on which the listener should be invoked, or
-     * {@code null} to use the current thread's {@link android.os.Looper
-     * looper}.
-     *
-     * @return int A unique capture sequence ID used by
-     *             {@link CaptureListener#onCaptureSequenceCompleted}.
-     *
-     * @throws CameraAccessException if the camera device is no longer connected or has
-     *                               encountered a fatal error
-     * @throws IllegalStateException if the camera is currently busy or unconfigured,
-     *                               or the camera device has been closed.
-     * @throws IllegalArgumentException If the request targets Surfaces not
-     * currently configured as outputs. Or if the handler is null, the listener
-     * is not null, and the calling thread has no looper.
-     *
-     * @see #captureBurst
-     * @see #setRepeatingRequest
-     * @see #setRepeatingBurst
-     * @deprecated Use {@link CameraCaptureSession} instead
+     * @deprecated Use {@link CameraCaptureSession#capture} instead
      */
     @Deprecated
     public abstract int capture(CaptureRequest request, CaptureListener listener, Handler handler)
             throws CameraAccessException;
 
     /**
-     * Submit a list of requests to be captured in sequence as a burst. The
-     * burst will be captured in the minimum amount of time possible, and will
-     * not be interleaved with requests submitted by other capture or repeat
-     * calls.
-     *
-     * <p>The requests will be captured in order, each capture producing one
-     * {@link CaptureResult} and image buffers for one or more target
-     * {@link android.view.Surface surfaces}. The target surfaces for each
-     * request (set with {@link CaptureRequest.Builder#addTarget}) must be
-     * configured as active outputs with {@link #configureOutputs} before
-     * calling this method.</p>
-     *
-     * <p>The main difference between this method and simply calling
-     * {@link #capture} repeatedly is that this method guarantees that no
-     * other requests will be interspersed with the burst.</p>
+     * Submit a list of requests to be captured in sequence as a burst.
      *
-     * @param requests the list of settings for this burst capture
-     * @param listener The callback object to notify each time one of the
-     * requests in the burst has been processed. If null, no metadata will be
-     * produced for any requests in this burst, although image data will still
-     * be produced.
-     * @param handler the handler on which the listener should be invoked, or
-     * {@code null} to use the current thread's {@link android.os.Looper
-     * looper}.
-     *
-     * @return int A unique capture sequence ID used by
-     *             {@link CaptureListener#onCaptureSequenceCompleted}.
-     *
-     * @throws CameraAccessException if the camera device is no longer connected or has
-     *                               encountered a fatal error
-     * @throws IllegalStateException if the camera is currently busy or unconfigured,
-     *                               or the camera device has been closed.
-     * @throws IllegalArgumentException If the requests target Surfaces not
-     * currently configured as outputs. Or if the handler is null, the listener
-     * is not null, and the calling thread has no looper. Or if no requests were
-     * passed in.
-     *
-     * @see #capture
-     * @see #setRepeatingRequest
-     * @see #setRepeatingBurst
-     * @deprecated Use {@link CameraCaptureSession} instead
+     * @deprecated Use {@link CameraCaptureSession#captureBurst} instead
      */
     @Deprecated
     public abstract int captureBurst(List<CaptureRequest> requests, CaptureListener listener,
@@ -487,58 +298,7 @@ public abstract class CameraDevice implements AutoCloseable {
     /**
      * Request endlessly repeating capture of images by this CameraDevice.
      *
-     * <p>With this method, the CameraDevice will continually capture images
-     * using the settings in the provided {@link CaptureRequest}, at the maximum
-     * rate possible.</p>
-     *
-     * <p>Repeating requests are a simple way for an application to maintain a
-     * preview or other continuous stream of frames, without having to
-     * continually submit identical requests through {@link #capture}.</p>
-     *
-     * <p>Repeat requests have lower priority than those submitted
-     * through {@link #capture} or {@link #captureBurst}, so if
-     * {@link #capture} is called when a repeating request is active, the
-     * capture request will be processed before any further repeating
-     * requests are processed.<p>
-     *
-     * <p>Repeating requests are a simple way for an application to maintain a
-     * preview or other continuous stream of frames, without having to submit
-     * requests through {@link #capture} at video rates.</p>
-     *
-     * <p>To stop the repeating capture, call {@link #stopRepeating}. Calling
-     * {@link #flush} will also clear the request.</p>
-     *
-     * <p>Calling this method will replace any earlier repeating request or
-     * burst set up by this method or {@link #setRepeatingBurst}, although any
-     * in-progress burst will be completed before the new repeat request will be
-     * used.</p>
-     *
-     * @param request the request to repeat indefinitely
-     * @param listener The callback object to notify every time the
-     * request finishes processing. If null, no metadata will be
-     * produced for this stream of requests, although image data will
-     * still be produced.
-     * @param handler the handler on which the listener should be invoked, or
-     * {@code null} to use the current thread's {@link android.os.Looper
-     * looper}.
-     *
-     * @return int A unique capture sequence ID used by
-     *             {@link CaptureListener#onCaptureSequenceCompleted}.
-     *
-     * @throws CameraAccessException if the camera device is no longer connected or has
-     *                               encountered a fatal error
-     * @throws IllegalStateException if the camera is currently busy or unconfigured,
-     *                               or the camera device has been closed.
-     * @throws IllegalArgumentException If the requests reference Surfaces not
-     * currently configured as outputs. Or if the handler is null, the listener
-     * is not null, and the calling thread has no looper.
-     *
-     * @see #capture
-     * @see #captureBurst
-     * @see #setRepeatingBurst
-     * @see #stopRepeating
-     * @see #flush
-     * @deprecated Use {@link CameraCaptureSession} instead
+     * @deprecated Use {@link CameraCaptureSession#setRepeatingRequest} instead
      */
     @Deprecated
     public abstract int setRepeatingRequest(CaptureRequest request, CaptureListener listener,
@@ -548,58 +308,7 @@ public abstract class CameraDevice implements AutoCloseable {
      * <p>Request endlessly repeating capture of a sequence of images by this
      * CameraDevice.</p>
      *
-     * <p>With this method, the CameraDevice will continually capture images,
-     * cycling through the settings in the provided list of
-     * {@link CaptureRequest CaptureRequests}, at the maximum rate possible.</p>
-     *
-     * <p>If a request is submitted through {@link #capture} or
-     * {@link #captureBurst}, the current repetition of the request list will be
-     * completed before the higher-priority request is handled. This guarantees
-     * that the application always receives a complete repeat burst captured in
-     * minimal time, instead of bursts interleaved with higher-priority
-     * captures, or incomplete captures.</p>
-     *
-     * <p>Repeating burst requests are a simple way for an application to
-     * maintain a preview or other continuous stream of frames where each
-     * request is different in a predicatable way, without having to continually
-     * submit requests through {@link #captureBurst} .</p>
-     *
-     * <p>To stop the repeating capture, call {@link #stopRepeating}. Any
-     * ongoing burst will still be completed, however. Calling
-     * {@link #flush} will also clear the request.</p>
-     *
-     * <p>Calling this method will replace a previously-set repeating request or
-     * burst set up by this method or {@link #setRepeatingRequest}, although any
-     * in-progress burst will be completed before the new repeat burst will be
-     * used.</p>
-     *
-     * @param requests the list of requests to cycle through indefinitely
-     * @param listener The callback object to notify each time one of the
-     * requests in the repeating bursts has finished processing. If null, no
-     * metadata will be produced for this stream of requests, although image
-     * data will still be produced.
-     * @param handler the handler on which the listener should be invoked, or
-     * {@code null} to use the current thread's {@link android.os.Looper
-     * looper}.
-     *
-     * @return int A unique capture sequence ID used by
-     *             {@link CaptureListener#onCaptureSequenceCompleted}.
-     *
-     * @throws CameraAccessException if the camera device is no longer connected or has
-     *                               encountered a fatal error
-     * @throws IllegalStateException if the camera is currently busy or unconfigured,
-     *                               or the camera device has been closed.
-     * @throws IllegalArgumentException If the requests reference Surfaces not
-     * currently configured as outputs. Or if the handler is null, the listener
-     * is not null, and the calling thread has no looper. Or if no requests were
-     * passed in.
-     *
-     * @see #capture
-     * @see #captureBurst
-     * @see #setRepeatingRequest
-     * @see #stopRepeating
-     * @see #flush
-     * @deprecated Use {@link CameraCaptureSession} instead
+     * @deprecated Use {@link CameraCaptureSession#setRepeatingBurst} instead
      */
     @Deprecated
     public abstract int setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener,
@@ -608,24 +317,9 @@ public abstract class CameraDevice implements AutoCloseable {
     /**
      * <p>Cancel any ongoing repeating capture set by either
      * {@link #setRepeatingRequest setRepeatingRequest} or
-     * {@link #setRepeatingBurst}. Has no effect on requests submitted through
-     * {@link #capture capture} or {@link #captureBurst captureBurst}.</p>
+     * {@link #setRepeatingBurst}.
      *
-     * <p>Any currently in-flight captures will still complete, as will any
-     * burst that is mid-capture. To ensure that the device has finished
-     * processing all of its capture requests and is in idle state, wait for the
-     * {@link StateListener#onIdle} callback after calling this
-     * method..</p>
-     *
-     * @throws CameraAccessException if the camera device is no longer connected or has
-     *                               encountered a fatal error
-     * @throws IllegalStateException if the camera is currently busy or unconfigured,
-     *                               or the camera device has been closed.
-     *
-     * @see #setRepeatingRequest
-     * @see #setRepeatingBurst
-     * @see StateListener#onIdle
-     * @deprecated Use {@link CameraCaptureSession} instead
+     * @deprecated Use {@link CameraCaptureSession#stopRepeating} instead
      */
     @Deprecated
     public abstract void stopRepeating() throws CameraAccessException;
@@ -634,36 +328,7 @@ public abstract class CameraDevice implements AutoCloseable {
      * Flush all captures currently pending and in-progress as fast as
      * possible.
      *
-     * <p>The camera device will discard all of its current work as fast as
-     * possible. Some in-flight captures may complete successfully and call
-     * {@link CaptureListener#onCaptureCompleted}, while others will trigger
-     * their {@link CaptureListener#onCaptureFailed} callbacks. If a repeating
-     * request or a repeating burst is set, it will be cleared by the flush.</p>
-     *
-     * <p>This method is the fastest way to idle the camera device for
-     * reconfiguration with {@link #configureOutputs}, at the cost of discarding
-     * in-progress work. Once the flush is complete, the idle callback will be
-     * called.</p>
-     *
-     * <p>Flushing will introduce at least a brief pause in the stream of data
-     * from the camera device, since once the flush is complete, the first new
-     * request has to make it through the entire camera pipeline before new
-     * output buffers are produced.</p>
-     *
-     * <p>This means that using {@code flush()} to simply remove pending
-     * requests is not recommended; it's best used for quickly switching output
-     * configurations, or for cancelling long in-progress requests (such as a
-     * multi-second capture).</p>
-     *
-     * @throws CameraAccessException if the camera device is no longer connected or has
-     *                               encountered a fatal error
-     * @throws IllegalStateException if the camera is not idle/active,
-     *                               or the camera device has been closed.
-     *
-     * @see #setRepeatingRequest
-     * @see #setRepeatingBurst
-     * @see #configureOutputs
-     * @deprecated Use {@link CameraCaptureSession} instead
+     * @deprecated Use {@link CameraCaptureSession#abortCaptures} instead
      */
     @Deprecated
     public abstract void flush() throws CameraAccessException;
@@ -690,15 +355,7 @@ public abstract class CameraDevice implements AutoCloseable {
      * <p>A listener for tracking the progress of a {@link CaptureRequest}
      * submitted to the camera device.</p>
      *
-     * <p>This listener is called when a request triggers a capture to start,
-     * and when the capture is complete. In case on an error capturing an image,
-     * the error method is triggered instead of the completion method.</p>
-     *
-     * @see #capture
-     * @see #captureBurst
-     * @see #setRepeatingRequest
-     * @see #setRepeatingBurst
-     * @deprecated Use {@link CameraCaptureSession} instead
+     * @deprecated Use {@link CameraCaptureSession.CaptureListener} instead
      */
     @Deprecated
     public static abstract class CaptureListener {
@@ -715,29 +372,6 @@ public abstract class CameraDevice 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.
          *
-         * <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>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},
-         * 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
-         * {@link android.graphics.SurfaceTexture#getTimestamp()}.</p>
-         *
-         * <p>For the simplest way to play a shutter sound camera shutter or a
-         * video recording start/stop sound, see the
-         * {@link android.media.MediaActionSound} class.</p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera the CameraDevice sending the callback
-         * @param request the request for the capture that just begun
-         * @param timestamp the timestamp at start of capture, in nanoseconds.
-         *
          * @see android.media.MediaActionSound
          */
         public void onCaptureStarted(CameraDevice camera,
@@ -749,25 +383,6 @@ public abstract class CameraDevice implements AutoCloseable {
          * This method is called when some results from an image capture are
          * available.
          *
-         * <p>The result provided here will contain some subset of the fields of
-         * a full result. Multiple onCapturePartial calls may happen per
-         * capture; a given result field will only be present in one partial
-         * capture at most. The final onCaptureCompleted call will always
-         * contain all the fields, whether onCapturePartial was called or
-         * not.</p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera The CameraDevice sending the callback.
-         * @param request The request that was given to the CameraDevice
-         * @param result The partial output metadata from the capture, which
-         * includes a subset of the CaptureResult fields.
-         *
-         * @see #capture
-         * @see #captureBurst
-         * @see #setRepeatingRequest
-         * @see #setRepeatingBurst
-         *
          * @hide
          */
         public void onCapturePartial(CameraDevice camera,
@@ -779,37 +394,6 @@ public abstract class CameraDevice implements AutoCloseable {
          * This method is called when an image capture makes partial forward progress; some
          * (but not all) results from an image capture are available.
          *
-         * <p>The result provided here will contain some subset of the fields of
-         * a full result. Multiple {@link #onCaptureProgressed} calls may happen per
-         * capture; a given result field will only be present in one partial
-         * capture at most. The final {@link #onCaptureCompleted} call will always
-         * contain all the fields (in particular, the union of all the fields of all
-         * the partial results composing the total result).</p>
-         *
-         * <p>For each request, some result data might be available earlier than others. The typical
-         * delay between each partial result (per request) is a single frame interval.
-         * For performance-oriented use-cases, applications should query the metadata they need
-         * to make forward progress from the partial results and avoid waiting for the completed
-         * result.</p>
-         *
-         * <p>Each request will generate at least {@code 1} partial results, and at most
-         * {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT} partial results.</p>
-         *
-         * <p>Depending on the request settings, the number of partial results per request
-         * will vary, although typically the partial count could be the same as long as the
-         * camera device subsystems enabled stay the same.</p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera The CameraDevice sending the callback.
-         * @param request The request that was given to the CameraDevice
-         * @param partialResult The partial output metadata from the capture, which
-         * includes a subset of the {@link TotalCaptureResult} fields.
-         *
-         * @see #capture
-         * @see #captureBurst
-         * @see #setRepeatingRequest
-         * @see #setRepeatingBurst
          */
         public void onCaptureProgressed(CameraDevice camera,
                 CaptureRequest request, CaptureResult partialResult) {
@@ -819,26 +403,6 @@ public abstract class CameraDevice implements AutoCloseable {
         /**
          * This method is called when an image capture has fully completed and all the
          * result metadata is available.
-         *
-         * <p>This callback will always fire after the last {@link #onCaptureProgressed};
-         * in other words, no more partial results will be delivered once the completed result
-         * is available.</p>
-         *
-         * <p>For performance-intensive use-cases where latency is a factor, consider
-         * using {@link #onCaptureProgressed} instead.</p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera The CameraDevice sending the callback.
-         * @param request The request that was given to the CameraDevice
-         * @param result The total output metadata from the capture, including the
-         * final capture parameters and the state of the camera system during
-         * capture.
-         *
-         * @see #capture
-         * @see #captureBurst
-         * @see #setRepeatingRequest
-         * @see #setRepeatingBurst
          */
         public void onCaptureCompleted(CameraDevice camera,
                 CaptureRequest request, TotalCaptureResult result) {
@@ -849,29 +413,6 @@ public abstract class CameraDevice implements AutoCloseable {
          * This method is called instead of {@link #onCaptureCompleted} when the
          * camera device failed to produce a {@link CaptureResult} for the
          * request.
-         *
-         * <p>Other requests are unaffected, and some or all image buffers from
-         * the capture may have been pushed to their respective output
-         * streams.</p>
-         *
-         * <p>Some partial results may have been delivered before the capture fails;
-         * however after this callback fires, no more partial results will be delivered by
-         * {@link #onCaptureProgressed}.</p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera
-         *            The CameraDevice sending the callback.
-         * @param request
-         *            The request that was given to the CameraDevice
-         * @param failure
-         *            The output failure from the capture, including the failure reason
-         *            and the frame number.
-         *
-         * @see #capture
-         * @see #captureBurst
-         * @see #setRepeatingRequest
-         * @see #setRepeatingBurst
          */
         public void onCaptureFailed(CameraDevice camera,
                 CaptureRequest request, CaptureFailure failure) {
@@ -882,26 +423,6 @@ public abstract class CameraDevice implements AutoCloseable {
          * This method is called independently of the others in CaptureListener,
          * when a capture sequence finishes and all {@link CaptureResult}
          * or {@link CaptureFailure} for it have been returned via this listener.
-         *
-         * <p>In total, there will be at least one result/failure returned by this listener
-         * before this callback is invoked. If the capture sequence is aborted before any
-         * requests have been processed, {@link #onCaptureSequenceAborted} is invoked instead.</p>
-         *
-         * <p>The default implementation does nothing.</p>
-         *
-         * @param camera
-         *            The CameraDevice sending the callback.
-         * @param sequenceId
-         *            A sequence ID returned by the {@link #capture} family of functions.
-         * @param frameNumber
-         *            The last frame number (returned by {@link CaptureResult#getFrameNumber}
-         *            or {@link CaptureFailure#getFrameNumber}) in the capture sequence.
-         *
-         * @see CaptureResult#getFrameNumber()
-         * @see CaptureFailure#getFrameNumber()
-         * @see CaptureResult#getSequenceId()
-         * @see CaptureFailure#getSequenceId()
-         * @see #onCaptureSequenceAborted
          */
         public void onCaptureSequenceCompleted(CameraDevice camera,
                 int sequenceId, long frameNumber) {
@@ -912,25 +433,6 @@ public abstract class CameraDevice implements AutoCloseable {
          * This method is called independently of the others in CaptureListener,
          * when a capture sequence aborts before any {@link CaptureResult}
          * or {@link CaptureFailure} for it have been returned via this listener.
-         *
-         * <p>Due to the asynchronous nature of the camera device, not all submitted captures
-         * are immediately processed. It is possible to clear out the pending requests
-         * by a variety of operations such as {@link CameraDevice#stopRepeating} or
-         * {@link CameraDevice#flush}. When such an event happens,
-         * {@link #onCaptureSequenceCompleted} will not be called.</p>
-         *
-         * <p>The default implementation does nothing.</p>
-         *
-         * @param camera
-         *            The CameraDevice sending the callback.
-         * @param sequenceId
-         *            A sequence ID returned by the {@link #capture} family of functions.
-         *
-         * @see CaptureResult#getFrameNumber()
-         * @see CaptureFailure#getFrameNumber()
-         * @see CaptureResult#getSequenceId()
-         * @see CaptureFailure#getSequenceId()
-         * @see #onCaptureSequenceCompleted
          */
         public void onCaptureSequenceAborted(CameraDevice camera,
                 int sequenceId) {
@@ -945,14 +447,14 @@ public abstract class CameraDevice implements AutoCloseable {
      * <p>A listener must be provided to the {@link CameraManager#openCamera}
      * method to open a camera device.</p>
      *
-     * <p>These events include notifications about the device becoming idle (
-     * allowing for {@link #configureOutputs} to be called), about device
-     * disconnection, and about unexpected device errors.</p>
+     * <p>These events include notifications about the device completing startup (
+     * allowing for {@link #createCaptureSession} to be called), about device
+     * disconnection or closure, and about unexpected device errors.</p>
      *
-     * <p>Events about the progress of specific {@link CaptureRequest
-     * CaptureRequests} are provided through a {@link CaptureListener} given to
-     * the {@link #capture}, {@link #captureBurst}, {@link
-     * #setRepeatingRequest}, or {@link #setRepeatingBurst} methods.
+     * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided
+     * through a {@link CameraCaptureSession.CaptureListener} given to the
+     * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst},
+     * {@link CameraCaptureSession#setRepeatingRequest}, or {@link CameraCaptureSession#setRepeatingBurst} methods.
      *
      * @see CameraManager#openCamera
      */
@@ -1026,8 +528,9 @@ public abstract class CameraDevice implements AutoCloseable {
         /**
          * The method called when a camera device has finished opening.
          *
-         * <p>An opened camera will immediately afterwards transition into
-         * {@link #onUnconfigured}.</p>
+         * <p>At this point, the camera device is ready to use, and
+         * {@link CameraDevice#createCaptureSession} can be called to set up the first capture
+         * session.</p>
          *
          * @param camera the camera device that has become opened
          */
@@ -1036,21 +539,7 @@ public abstract class CameraDevice implements AutoCloseable {
         /**
          * The method called when a camera device has no outputs configured.
          *
-         * <p>An unconfigured camera device needs to be configured with
-         * {@link CameraDevice#configureOutputs} before being able to
-         * submit any capture request.</p>
-         *
-         * <p>This state may be entered by a newly opened camera or by
-         * calling {@link CameraDevice#configureOutputs} with a null/empty
-         * list of Surfaces when idle.</p>
-         *
-         * <p>Any attempts to submit a capture request while in this state
-         * will result in an {@link IllegalStateException} being thrown.</p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera the camera device has that become unconfigured
-         * @deprecated Use {@link CameraCaptureSession.StateListener} instead.
+         * @deprecated Use {@link #onOpened} instead.
          */
         @Deprecated
         public void onUnconfigured(CameraDevice camera) {
@@ -1061,27 +550,7 @@ public abstract class CameraDevice implements AutoCloseable {
          * The method called when a camera device begins processing
          * {@link CaptureRequest capture requests}.
          *
-         * <p>A camera may not be re-configured while in this state. The camera
-         * will transition to the idle state once all pending captures have
-         * completed. If a repeating request is set, the camera will remain active
-         * until it is cleared and the remaining requests finish processing. To
-         * transition to the idle state as quickly as possible, call {@link #flush()},
-         * which will idle the camera device as quickly as possible, likely canceling
-         * most in-progress captures.</p>
-         *
-         * <p>All calls except for {@link CameraDevice#configureOutputs} are
-         * legal while in this state.
-         * </p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera the camera device that has become active
-         *
-         * @see CameraDevice#capture
-         * @see CameraDevice#captureBurst
-         * @see CameraDevice#setRepeatingBurst
-         * @see CameraDevice#setRepeatingRequest
-         * @deprecated Use {@link CameraCaptureSession.StateListener} instead.
+         * @deprecated Use {@link CameraCaptureSession.StateListener#onActive} instead.
          */
         @Deprecated
         public void onActive(CameraDevice camera) {
@@ -1091,32 +560,7 @@ public abstract class CameraDevice implements AutoCloseable {
         /**
          * The method called when a camera device is busy.
          *
-         * <p>A camera becomes busy while it's outputs are being configured
-         * (after a call to {@link CameraDevice#configureOutputs} or while it's
-         * being flushed (after a call to {@link CameraDevice#flush}.</p>
-         *
-         * <p>Once the on-going operations are complete, the camera will automatically
-         * transition into {@link #onIdle} if there is at least one configured output,
-         * or {@link #onUnconfigured} otherwise.</p>
-         *
-         * <p>Any attempts to manipulate the camera while its is busy
-         * will result in an {@link IllegalStateException} being thrown.</p>
-         *
-         * <p>Only the following methods are valid to call while in this state:
-         * <ul>
-         * <li>{@link CameraDevice#getId}</li>
-         * <li>{@link CameraDevice#createCaptureRequest}</li>
-         * <li>{@link CameraDevice#close}</li>
-         * </ul>
-         * </p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera the camera device that has become busy
-         *
-         * @see CameraDevice#configureOutputs
-         * @see CameraDevice#flush
-         * @deprecated Use {@link CameraCaptureSession.StateListener} instead.
+         * @deprecated Use {@link CameraCaptureSession.StateListener#onConfigured} instead.
          */
         @Deprecated
         public void onBusy(CameraDevice camera) {
@@ -1142,30 +586,7 @@ public abstract class CameraDevice implements AutoCloseable {
          * The method called when a camera device has finished processing all
          * submitted capture requests and has reached an idle state.
          *
-         * <p>An idle camera device can have its outputs changed by calling {@link
-         * CameraDevice#configureOutputs}, which will transition it into the busy state.</p>
-         *
-         * <p>To idle and reconfigure outputs without canceling any submitted
-         * capture requests, the application needs to clear its repeating
-         * request/burst, if set, with {@link CameraDevice#stopRepeating}, and
-         * then wait for this callback to be called before calling {@link
-         * CameraDevice#configureOutputs}.</p>
-         *
-         * <p>To idle and reconfigure a camera device as fast as possible, the
-         * {@link CameraDevice#flush} method can be used, which will discard all
-         * pending and in-progress capture requests. Once the {@link
-         * CameraDevice#flush} method is called, the application must wait for
-         * this callback to fire before calling {@link
-         * CameraDevice#configureOutputs}.</p>
-         *
-         * <p>The default implementation of this method does nothing.</p>
-         *
-         * @param camera the camera device that has become idle
-         *
-         * @see CameraDevice#configureOutputs
-         * @see CameraDevice#stopRepeating
-         * @see CameraDevice#flush
-         * @deprecated Use {@link CameraCaptureSession.StateListener} instead.
+         * @deprecated Use {@link CameraCaptureSession.StateListener#onReady} instead.
          */
         @Deprecated
         public void onIdle(CameraDevice camera) {
@@ -1221,7 +642,7 @@ public abstract class CameraDevice implements AutoCloseable {
          *
          * @param camera The device reporting the error
          * @param error The error code, one of the
-         *     {@code CameraDeviceListener.ERROR_*} values.
+         *     {@code StateListener.ERROR_*} values.
          *
          * @see #ERROR_CAMERA_DEVICE
          * @see #ERROR_CAMERA_SERVICE
diff --git a/core/java/android/hardware/camera2/CameraManager.java b/core/java/android/hardware/camera2/CameraManager.java
index 9046b13..e7c9ee3 100644
--- a/core/java/android/hardware/camera2/CameraManager.java
+++ b/core/java/android/hardware/camera2/CameraManager.java
@@ -35,7 +35,7 @@ import android.util.ArrayMap;
 import java.util.ArrayList;
 
 /**
- * <p>An interface for iterating, listing, and connecting to
+ * <p>A system service manager for detecting, characterizing, and connecting to
  * {@link CameraDevice CameraDevices}.</p>
  *
  * <p>You can get an instance of this class by calling
@@ -358,14 +358,18 @@ public final class CameraManager {
     }
 
     /**
-     * Interface for listening to camera devices becoming available or
-     * unavailable.
+     * A listener for camera devices becoming available or
+     * unavailable to open.
      *
      * <p>Cameras become available when they are no longer in use, or when a new
      * removable camera is connected. They become unavailable when some
      * application or service starts using a camera, or when a removable camera
      * is disconnected.</p>
      *
+     * <p>Extend this listener and pass an instance of the subclass to
+     * {@link CameraManager#addAvailabilityListener} to be notified of such availability
+     * changes.</p>
+     *
      * @see addAvailabilityListener
      */
     public static abstract class AvailabilityListener {
diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java
index 94a5a79..90e5e4e 100644
--- a/core/java/android/hardware/camera2/CameraMetadata.java
+++ b/core/java/android/hardware/camera2/CameraMetadata.java
@@ -355,12 +355,14 @@ public abstract class CameraMetadata<TKey> {
      * <li>RAW16 is reprocessable into both YUV_420_888 and JPEG
      * formats.</li>
      * <li>The maximum available resolution for RAW16 streams (both
-     * input/output) will match the value in
-     * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.</li>
+     * input/output) will match the either value in
+     * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize} or
+     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.</li>
      * <li>All DNG-related optional metadata entries are provided
      * by the camera device.</li>
      * </ul>
      *
+     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
      * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE
      * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES
      */
@@ -760,12 +762,14 @@ public abstract class CameraMetadata<TKey> {
     public static final int CONTROL_AF_MODE_OFF = 0;
 
     /**
-     * <p>If lens is not fixed focus.</p>
-     * <p>Use {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} to determine if lens
-     * is fixed-focus. In this mode, the lens does not move unless
+     * <p>Basic automatic focus mode.</p>
+     * <p>In this mode, the lens does not move unless
      * the autofocus trigger action is called. When that trigger
-     * is activated, AF must transition to ACTIVE_SCAN, then to
+     * is activated, AF will transition to ACTIVE_SCAN, then to
      * the outcome of the scan (FOCUSED or NOT_FOCUSED).</p>
+     * <p>Always supported if lens is not fixed focus.</p>
+     * <p>Use {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} to determine if lens
+     * is fixed-focus.</p>
      * <p>Triggering AF_CANCEL resets the lens position to default,
      * and sets the AF state to INACTIVE.</p>
      *
@@ -775,11 +779,16 @@ public abstract class CameraMetadata<TKey> {
     public static final int CONTROL_AF_MODE_AUTO = 1;
 
     /**
+     * <p>Close-up focusing mode.</p>
      * <p>In this mode, the lens does not move unless the
-     * autofocus trigger action is called.</p>
-     * <p>When that trigger is activated, AF must transition to
+     * autofocus trigger action is called. When that trigger is
+     * activated, AF will transition to ACTIVE_SCAN, then to
+     * the outcome of the scan (FOCUSED or NOT_FOCUSED). This
+     * mode is optimized for focusing on objects very close to
+     * the camera.</p>
+     * <p>When that trigger is activated, AF will transition to
      * ACTIVE_SCAN, then to the outcome of the scan (FOCUSED or
-     * NOT_FOCUSED).  Triggering cancel AF resets the lens
+     * NOT_FOCUSED). Triggering cancel AF resets the lens
      * position to default, and sets the AF state to
      * INACTIVE.</p>
      * @see CaptureRequest#CONTROL_AF_MODE
diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java
index d4dfdd5..0ff8cce 100644
--- a/core/java/android/hardware/camera2/CaptureRequest.java
+++ b/core/java/android/hardware/camera2/CaptureRequest.java
@@ -43,14 +43,14 @@ import java.util.Objects;
  * <p>CaptureRequests can be created by using a {@link Builder} instance,
  * obtained by calling {@link CameraDevice#createCaptureRequest}</p>
  *
- * <p>CaptureRequests are given to {@link CameraDevice#capture} or
- * {@link CameraDevice#setRepeatingRequest} to capture images from a camera.</p>
+ * <p>CaptureRequests are given to {@link CameraCaptureSession#capture} or
+ * {@link CameraCaptureSession#setRepeatingRequest} to capture images from a camera.</p>
  *
  * <p>Each request can specify a different subset of target Surfaces for the
  * camera to send the captured data to. All the surfaces used in a request must
  * be part of the surface list given to the last call to
- * {@link CameraDevice#configureOutputs}, when the request is submitted to the
- * camera device.</p>
+ * {@link CameraDevice#createCaptureSession}, when the request is submitted to the
+ * session.</p>
  *
  * <p>For example, a request meant for repeating preview might only include the
  * Surface for the preview SurfaceView or SurfaceTexture, while a
@@ -357,11 +357,11 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      * request fields to one of the templates defined in {@link CameraDevice}.
      *
      * @see CameraDevice#createCaptureRequest
-     * @see #TEMPLATE_PREVIEW
-     * @see #TEMPLATE_RECORD
-     * @see #TEMPLATE_STILL_CAPTURE
-     * @see #TEMPLATE_VIDEO_SNAPSHOT
-     * @see #TEMPLATE_MANUAL
+     * @see CameraDevice#TEMPLATE_PREVIEW
+     * @see CameraDevice#TEMPLATE_RECORD
+     * @see CameraDevice#TEMPLATE_STILL_CAPTURE
+     * @see CameraDevice#TEMPLATE_VIDEO_SNAPSHOT
+     * @see CameraDevice#TEMPLATE_MANUAL
      */
     public final static class Builder {
 
@@ -381,7 +381,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
          * <p>Add a surface to the list of targets for this request</p>
          *
          * <p>The Surface added must be one of the surfaces included in the most
-         * recent call to {@link CameraDevice#configureOutputs}, when the
+         * recent call to {@link CameraDevice#createCaptureSession}, when the
          * request is given to the camera device.</p>
          *
          * <p>Adding a target more than once has no effect.</p>
@@ -473,7 +473,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
     /**
      * <p>The mode control selects how the image data is converted from the
      * sensor's native color into linear sRGB color.</p>
-     * <p>When auto-white balance is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this
+     * <p>When auto-white balance (AWB) is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this
      * control is overridden by the AWB routine. When AWB is disabled, the
      * application controls how the color mapping is performed.</p>
      * <p>We define the expected processing pipeline below. For consistency
@@ -524,7 +524,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
 
     /**
      * <p>A color transform matrix to use to transform
-     * from sensor RGB color space to output linear sRGB color space</p>
+     * from sensor RGB color space to output linear sRGB color space.</p>
      * <p>This matrix is either set by the camera device when the request
      * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or
      * directly by the application in the request when the
@@ -600,13 +600,17 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Integer>("android.control.aeAntibandingMode", int.class);
 
     /**
-     * <p>Adjustment to AE target image
-     * brightness</p>
-     * <p>For example, if EV step is 0.333, '6' will mean an
-     * exposure compensation of +2 EV; -3 will mean an exposure
-     * compensation of -1 EV. Note that this control will only be effective
-     * if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control will take effect even when
-     * {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p>
+     * <p>Adjustment to auto-exposure (AE) target image
+     * brightness.</p>
+     * <p>The adjustment is measured as a count of steps, with the
+     * step size defined by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} and the
+     * allowed range by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}.</p>
+     * <p>For example, if the exposure value (EV) step is 0.333, '6'
+     * will mean an exposure compensation of +2 EV; -3 will mean an
+     * exposure compensation of -1 EV. One EV represents a doubling
+     * of image brightness. Note that this control will only be
+     * effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control
+     * will take effect even when {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p>
      * <p>In the event of exposure compensation value being changed, camera device
      * may take several frames to reach the newly requested exposure target.
      * During that time, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} field will be in the SEARCHING
@@ -614,6 +618,8 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      * change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
      * FLASH_REQUIRED (if the scene is too dark for still capture).</p>
      *
+     * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE
+     * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
      * @see CaptureRequest#CONTROL_AE_LOCK
      * @see CaptureRequest#CONTROL_AE_MODE
      * @see CaptureResult#CONTROL_AE_STATE
@@ -622,7 +628,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Integer>("android.control.aeExposureCompensation", int.class);
 
     /**
-     * <p>Whether AE is currently locked to its latest
+     * <p>Whether auto-exposure (AE) is currently locked to its latest
      * calculated values.</p>
      * <p>Note that even when AE is locked, the flash may be
      * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
@@ -711,9 +717,9 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
 
     /**
      * <p>Range over which fps can be adjusted to
-     * maintain exposure</p>
-     * <p>Only constrains AE algorithm, not manual control
-     * of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
+     * maintain exposure.</p>
+     * <p>Only constrains auto-exposure (AE) algorithm, not
+     * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
      *
      * @see CaptureRequest#SENSOR_EXPOSURE_TIME
      */
@@ -727,9 +733,10 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      * included at all in the request settings. When included and
      * set to START, the camera device will trigger the autoexposure
      * precapture metering sequence.</p>
-     * <p>The effect of AE precapture trigger depends on the current
-     * AE mode and state; see {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture
-     * state transition details.</p>
+     * <p>The effect of auto-exposure (AE) precapture trigger depends
+     * on the current AE mode and state; see
+     * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition
+     * details.</p>
      *
      * @see CaptureResult#CONTROL_AE_STATE
      * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
@@ -739,8 +746,8 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Integer>("android.control.aePrecaptureTrigger", int.class);
 
     /**
-     * <p>Whether AF is currently enabled, and what
-     * mode it is set to</p>
+     * <p>Whether auto-focus (AF) is currently enabled, and what
+     * mode it is set to.</p>
      * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO and the lens is not fixed focus
      * (i.e. <code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} &gt; 0</code>).</p>
      * <p>If the lens is controlled by the camera device auto-focus algorithm,
@@ -804,7 +811,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Integer>("android.control.afTrigger", int.class);
 
     /**
-     * <p>Whether AWB is currently locked to its
+     * <p>Whether auto-white balance (AWB) is currently locked to its
      * latest calculated values.</p>
      * <p>Note that AWB lock is only meaningful for AUTO
      * mode; in other modes, AWB is already fixed to a specific
@@ -814,7 +821,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Boolean>("android.control.awbLock", boolean.class);
 
     /**
-     * <p>Whether AWB is currently setting the color
+     * <p>Whether auto-white balance (AWB) is currently setting the color
      * transform fields, and what its illumination target
      * is.</p>
      * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p>
@@ -988,7 +995,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
 
     /**
      * <p>Whether video stabilization is
-     * active</p>
+     * active.</p>
      * <p>If enabled, video stabilization can modify the
      * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
      * stabilized</p>
@@ -1030,7 +1037,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      * <p>When set to OFF, the camera device will not fire flash for this capture.</p>
      * <p>When set to SINGLE, the camera device will fire flash regardless of the camera
      * device's auto-exposure routine's result. When used in still capture case, this
-     * control should be used along with AE precapture metering sequence
+     * control should be used along with auto-exposure (AE) precapture metering sequence
      * ({@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}), otherwise, the image may be incorrectly exposed.</p>
      * <p>When set to TORCH, the flash will be on continuously. This mode can be used
      * for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
@@ -1102,7 +1109,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
 
     /**
      * <p>Compression quality of the final JPEG
-     * image</p>
+     * image.</p>
      * <p>85-95 is typical usage range</p>
      */
     public static final Key<Byte> JPEG_QUALITY =
@@ -1116,7 +1123,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
 
     /**
-     * <p>Resolution of embedded JPEG thumbnail</p>
+     * <p>Resolution of embedded JPEG thumbnail.</p>
      * <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
      * but the captured JPEG will still be a valid image.</p>
      * <p>When a jpeg image capture is issued, the thumbnail size selected should have
@@ -1204,7 +1211,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
 
     /**
      * <p>Distance to plane of sharpest focus,
-     * measured from frontmost surface of the lens</p>
+     * measured from frontmost surface of the lens.</p>
      * <p>0 means infinity focus. Used value will be clamped
      * to [0, {@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}].</p>
      * <p>Like {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}, this setting won't be applied
@@ -1235,7 +1242,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Integer>("android.lens.opticalStabilizationMode", int.class);
 
     /**
-     * <p>Mode of operation for the noise reduction
+     * <p>Mode of operation for the noise reduction.
      * algorithm</p>
      * <p>Noise filtering control. OFF means no noise reduction
      * will be applied by the camera device.</p>
@@ -1265,40 +1272,39 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Integer>("android.request.id", int.class);
 
     /**
-     * <p>(x, y, width, height).</p>
-     * <p>A rectangle with the top-level corner of (x,y) and size
-     * (width, height). The region of the sensor that is used for
-     * output. Each stream must use this rectangle to produce its
-     * output, cropping to a smaller region if necessary to
-     * maintain the stream's aspect ratio.</p>
-     * <p>HAL2.x uses only (x, y, width)</p>
-     * <p>The crop region is applied after the RAW to other color space (e.g. YUV)
-     * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage,
-     * it is not croppable. The crop region will be ignored by raw streams.</p>
+     * <p>The region of the sensor to read out for this capture.</p>
+     * <p>The crop region coordinate system is based off
+     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the
+     * top-left corner of the sensor active array.</p>
+     * <p>Output streams use this rectangle to produce their output,
+     * cropping to a smaller region if necessary to maintain the
+     * stream's aspect ratio, then scaling the sensor input to
+     * match the output's configured resolution.</p>
+     * <p>The crop region is applied after the RAW to other color
+     * space (e.g. YUV) conversion. Since raw streams
+     * (e.g. RAW16) don't have the conversion stage, they are not
+     * croppable. The crop region will be ignored by raw streams.</p>
      * <p>For non-raw streams, any additional per-stream cropping will
      * be done to maximize the final pixel area of the stream.</p>
      * <p>For example, if the crop region is set to a 4:3 aspect
-     * ratio, then 4:3 streams should use the exact crop
-     * region. 16:9 streams should further crop vertically
+     * ratio, then 4:3 streams will use the exact crop
+     * region. 16:9 streams will further crop vertically
      * (letterbox).</p>
      * <p>Conversely, if the crop region is set to a 16:9, then 4:3
-     * outputs should crop horizontally (pillarbox), and 16:9
-     * streams should match exactly. These additional crops must
+     * outputs will crop horizontally (pillarbox), and 16:9
+     * streams will match exactly. These additional crops will
      * be centered within the crop region.</p>
-     * <p>The output streams must maintain square pixels at all
-     * times, no matter what the relative aspect ratios of the
-     * crop region and the stream are.  Negative values for
-     * corner are allowed for raw output if full pixel array is
-     * larger than active pixel array. Width and height may be
-     * rounded to nearest larger supportable width, especially
-     * for raw output, where only a few fixed scales may be
-     * possible. The width and height of the crop region cannot
-     * be set to be smaller than floor( activeArraySize.width /
-     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and floor(
-     * activeArraySize.height /
-     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom}), respectively.</p>
+     * <p>The width and height of the crop region cannot
+     * be set to be smaller than
+     * <code>floor( activeArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code> and
+     * <code>floor( activeArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code>, respectively.</p>
+     * <p>The camera device may adjust the crop region to account
+     * for rounding and other hardware requirements; the final
+     * crop region used will be included in the output capture
+     * result.</p>
      *
      * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
+     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
      */
     public static final Key<android.graphics.Rect> SCALER_CROP_REGION =
             new Key<android.graphics.Rect>("android.scaler.cropRegion", android.graphics.Rect.class);
@@ -1391,12 +1397,20 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
             new Key<Long>("android.sensor.frameDuration", long.class);
 
     /**
-     * <p>Gain applied to image data. Must be
-     * implemented through analog gain only if set to values
-     * below 'maximum analog sensitivity'.</p>
-     * <p>If the sensor can't apply this exact gain, it should lessen the
-     * gain to the nearest possible value (rather than gain more).</p>
-     * <p>ISO 12232:2006 REI method</p>
+     * <p>The amount of gain applied to sensor data
+     * before processing.</p>
+     * <p>The sensitivity is the standard ISO sensitivity value,
+     * as defined in ISO 12232:2006.</p>
+     * <p>The sensitivity must be within {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}, and
+     * if if it less than {@link CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY android.sensor.maxAnalogSensitivity}, the camera device
+     * is guaranteed to use only analog amplification for applying the gain.</p>
+     * <p>If the camera device cannot apply the exact sensitivity
+     * requested, it will reduce the gain to the nearest supported
+     * value. The final sensitivity used will be available in the
+     * output capture result.</p>
+     *
+     * @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE
+     * @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY
      */
     public static final Key<Integer> SENSOR_SENSITIVITY =
             new Key<Integer>("android.sensor.sensitivity", int.class);
@@ -1459,7 +1473,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
      * lens shading map data in android.statistics.lensShadingMap, with size specified
      * by android.lens.info.shadingMapSize; the returned shading map data will be the one
      * applied by the camera device for this capture request.</p>
-     * <p>The shading map data may depend on the AE and AWB statistics, therefore the reliability
+     * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
      * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
      * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF),
      * to get best results, it is recommended that the applications wait for the AE and AWB to
@@ -1477,7 +1491,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
 
     /**
      * <p>State of the face detector
-     * unit</p>
+     * unit.</p>
      * <p>Whether face detection is enabled, and whether it
      * should output just the basic fields or the full set of
      * fields. Value must be one of the
diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java
index 7d07c92..ce3de1d 100644
--- a/core/java/android/hardware/camera2/CaptureResult.java
+++ b/core/java/android/hardware/camera2/CaptureResult.java
@@ -319,7 +319,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
     /**
      * <p>The mode control selects how the image data is converted from the
      * sensor's native color into linear sRGB color.</p>
-     * <p>When auto-white balance is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this
+     * <p>When auto-white balance (AWB) is enabled with {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}, this
      * control is overridden by the AWB routine. When AWB is disabled, the
      * application controls how the color mapping is performed.</p>
      * <p>We define the expected processing pipeline below. For consistency
@@ -370,7 +370,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
 
     /**
      * <p>A color transform matrix to use to transform
-     * from sensor RGB color space to output linear sRGB color space</p>
+     * from sensor RGB color space to output linear sRGB color space.</p>
      * <p>This matrix is either set by the camera device when the request
      * {@link CaptureRequest#COLOR_CORRECTION_MODE android.colorCorrection.mode} is not TRANSFORM_MATRIX, or
      * directly by the application in the request when the
@@ -446,13 +446,17 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.control.aeAntibandingMode", int.class);
 
     /**
-     * <p>Adjustment to AE target image
-     * brightness</p>
-     * <p>For example, if EV step is 0.333, '6' will mean an
-     * exposure compensation of +2 EV; -3 will mean an exposure
-     * compensation of -1 EV. Note that this control will only be effective
-     * if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control will take effect even when
-     * {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p>
+     * <p>Adjustment to auto-exposure (AE) target image
+     * brightness.</p>
+     * <p>The adjustment is measured as a count of steps, with the
+     * step size defined by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP android.control.aeCompensationStep} and the
+     * allowed range by {@link CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE android.control.aeCompensationRange}.</p>
+     * <p>For example, if the exposure value (EV) step is 0.333, '6'
+     * will mean an exposure compensation of +2 EV; -3 will mean an
+     * exposure compensation of -1 EV. One EV represents a doubling
+     * of image brightness. Note that this control will only be
+     * effective if {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF. This control
+     * will take effect even when {@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} <code>== true</code>.</p>
      * <p>In the event of exposure compensation value being changed, camera device
      * may take several frames to reach the newly requested exposure target.
      * During that time, {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} field will be in the SEARCHING
@@ -460,6 +464,8 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
      * FLASH_REQUIRED (if the scene is too dark for still capture).</p>
      *
+     * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_RANGE
+     * @see CameraCharacteristics#CONTROL_AE_COMPENSATION_STEP
      * @see CaptureRequest#CONTROL_AE_LOCK
      * @see CaptureRequest#CONTROL_AE_MODE
      * @see CaptureResult#CONTROL_AE_STATE
@@ -468,7 +474,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.control.aeExposureCompensation", int.class);
 
     /**
-     * <p>Whether AE is currently locked to its latest
+     * <p>Whether auto-exposure (AE) is currently locked to its latest
      * calculated values.</p>
      * <p>Note that even when AE is locked, the flash may be
      * fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
@@ -557,9 +563,9 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
 
     /**
      * <p>Range over which fps can be adjusted to
-     * maintain exposure</p>
-     * <p>Only constrains AE algorithm, not manual control
-     * of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
+     * maintain exposure.</p>
+     * <p>Only constrains auto-exposure (AE) algorithm, not
+     * manual control of {@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}</p>
      *
      * @see CaptureRequest#SENSOR_EXPOSURE_TIME
      */
@@ -573,9 +579,10 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * included at all in the request settings. When included and
      * set to START, the camera device will trigger the autoexposure
      * precapture metering sequence.</p>
-     * <p>The effect of AE precapture trigger depends on the current
-     * AE mode and state; see {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture
-     * state transition details.</p>
+     * <p>The effect of auto-exposure (AE) precapture trigger depends
+     * on the current AE mode and state; see
+     * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition
+     * details.</p>
      *
      * @see CaptureResult#CONTROL_AE_STATE
      * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE
@@ -585,7 +592,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.control.aePrecaptureTrigger", int.class);
 
     /**
-     * <p>Current state of AE algorithm</p>
+     * <p>Current state of auto-exposure (AE) algorithm.</p>
      * <p>Switching between or enabling AE modes ({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}) always
      * resets the AE state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode},
      * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
@@ -783,8 +790,8 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.control.aeState", int.class);
 
     /**
-     * <p>Whether AF is currently enabled, and what
-     * mode it is set to</p>
+     * <p>Whether auto-focus (AF) is currently enabled, and what
+     * mode it is set to.</p>
      * <p>Only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} = AUTO and the lens is not fixed focus
      * (i.e. <code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} &gt; 0</code>).</p>
      * <p>If the lens is controlled by the camera device auto-focus algorithm,
@@ -848,7 +855,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.control.afTrigger", int.class);
 
     /**
-     * <p>Current state of AF algorithm.</p>
+     * <p>Current state of auto-focus (AF) algorithm.</p>
      * <p>Switching between or enabling AF modes ({@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}) always
      * resets the AF state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode},
      * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
@@ -1245,7 +1252,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.control.afState", int.class);
 
     /**
-     * <p>Whether AWB is currently locked to its
+     * <p>Whether auto-white balance (AWB) is currently locked to its
      * latest calculated values.</p>
      * <p>Note that AWB lock is only meaningful for AUTO
      * mode; in other modes, AWB is already fixed to a specific
@@ -1255,7 +1262,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Boolean>("android.control.awbLock", boolean.class);
 
     /**
-     * <p>Whether AWB is currently setting the color
+     * <p>Whether auto-white balance (AWB) is currently setting the color
      * transform fields, and what its illumination target
      * is.</p>
      * <p>This control is only effective if {@link CaptureRequest#CONTROL_MODE android.control.mode} is AUTO.</p>
@@ -1338,7 +1345,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.control.captureIntent", int.class);
 
     /**
-     * <p>Current state of AWB algorithm</p>
+     * <p>Current state of auto-white balance (AWB) algorithm.</p>
      * <p>Switching between or enabling AWB modes ({@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode}) always
      * resets the AWB state to INACTIVE. Similarly, switching between {@link CaptureRequest#CONTROL_MODE android.control.mode},
      * or {@link CaptureRequest#CONTROL_SCENE_MODE android.control.sceneMode} if <code>{@link CaptureRequest#CONTROL_MODE android.control.mode} == USE_SCENE_MODE</code> resets all
@@ -1559,7 +1566,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
 
     /**
      * <p>Whether video stabilization is
-     * active</p>
+     * active.</p>
      * <p>If enabled, video stabilization can modify the
      * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} to keep the video stream
      * stabilized</p>
@@ -1601,7 +1608,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * <p>When set to OFF, the camera device will not fire flash for this capture.</p>
      * <p>When set to SINGLE, the camera device will fire flash regardless of the camera
      * device's auto-exposure routine's result. When used in still capture case, this
-     * control should be used along with AE precapture metering sequence
+     * control should be used along with auto-exposure (AE) precapture metering sequence
      * ({@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger}), otherwise, the image may be incorrectly exposed.</p>
      * <p>When set to TORCH, the flash will be on continuously. This mode can be used
      * for use cases such as preview, auto-focus assist, still capture, or video recording.</p>
@@ -1690,7 +1697,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
 
     /**
      * <p>Compression quality of the final JPEG
-     * image</p>
+     * image.</p>
      * <p>85-95 is typical usage range</p>
      */
     public static final Key<Byte> JPEG_QUALITY =
@@ -1704,7 +1711,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
 
     /**
-     * <p>Resolution of embedded JPEG thumbnail</p>
+     * <p>Resolution of embedded JPEG thumbnail.</p>
      * <p>When set to (0, 0) value, the JPEG EXIF will not contain thumbnail,
      * but the captured JPEG will still be a valid image.</p>
      * <p>When a jpeg image capture is issued, the thumbnail size selected should have
@@ -1792,7 +1799,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
 
     /**
      * <p>Distance to plane of sharpest focus,
-     * measured from frontmost surface of the lens</p>
+     * measured from frontmost surface of the lens.</p>
      * <p>Should be zero for fixed-focus cameras</p>
      */
     public static final Key<Float> LENS_FOCUS_DISTANCE =
@@ -1800,7 +1807,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
 
     /**
      * <p>The range of scene distances that are in
-     * sharp focus (depth of field)</p>
+     * sharp focus (depth of field).</p>
      * <p>If variable focus not supported, can still report
      * fixed depth of field range</p>
      */
@@ -1859,7 +1866,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Integer>("android.lens.state", int.class);
 
     /**
-     * <p>Mode of operation for the noise reduction
+     * <p>Mode of operation for the noise reduction.
      * algorithm</p>
      * <p>Noise filtering control. OFF means no noise reduction
      * will be applied by the camera device.</p>
@@ -1934,40 +1941,39 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Byte>("android.request.pipelineDepth", byte.class);
 
     /**
-     * <p>(x, y, width, height).</p>
-     * <p>A rectangle with the top-level corner of (x,y) and size
-     * (width, height). The region of the sensor that is used for
-     * output. Each stream must use this rectangle to produce its
-     * output, cropping to a smaller region if necessary to
-     * maintain the stream's aspect ratio.</p>
-     * <p>HAL2.x uses only (x, y, width)</p>
-     * <p>The crop region is applied after the RAW to other color space (e.g. YUV)
-     * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage,
-     * it is not croppable. The crop region will be ignored by raw streams.</p>
+     * <p>The region of the sensor to read out for this capture.</p>
+     * <p>The crop region coordinate system is based off
+     * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with <code>(0, 0)</code> being the
+     * top-left corner of the sensor active array.</p>
+     * <p>Output streams use this rectangle to produce their output,
+     * cropping to a smaller region if necessary to maintain the
+     * stream's aspect ratio, then scaling the sensor input to
+     * match the output's configured resolution.</p>
+     * <p>The crop region is applied after the RAW to other color
+     * space (e.g. YUV) conversion. Since raw streams
+     * (e.g. RAW16) don't have the conversion stage, they are not
+     * croppable. The crop region will be ignored by raw streams.</p>
      * <p>For non-raw streams, any additional per-stream cropping will
      * be done to maximize the final pixel area of the stream.</p>
      * <p>For example, if the crop region is set to a 4:3 aspect
-     * ratio, then 4:3 streams should use the exact crop
-     * region. 16:9 streams should further crop vertically
+     * ratio, then 4:3 streams will use the exact crop
+     * region. 16:9 streams will further crop vertically
      * (letterbox).</p>
      * <p>Conversely, if the crop region is set to a 16:9, then 4:3
-     * outputs should crop horizontally (pillarbox), and 16:9
-     * streams should match exactly. These additional crops must
+     * outputs will crop horizontally (pillarbox), and 16:9
+     * streams will match exactly. These additional crops will
      * be centered within the crop region.</p>
-     * <p>The output streams must maintain square pixels at all
-     * times, no matter what the relative aspect ratios of the
-     * crop region and the stream are.  Negative values for
-     * corner are allowed for raw output if full pixel array is
-     * larger than active pixel array. Width and height may be
-     * rounded to nearest larger supportable width, especially
-     * for raw output, where only a few fixed scales may be
-     * possible. The width and height of the crop region cannot
-     * be set to be smaller than floor( activeArraySize.width /
-     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and floor(
-     * activeArraySize.height /
-     * {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom}), respectively.</p>
+     * <p>The width and height of the crop region cannot
+     * be set to be smaller than
+     * <code>floor( activeArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code> and
+     * <code>floor( activeArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} )</code>, respectively.</p>
+     * <p>The camera device may adjust the crop region to account
+     * for rounding and other hardware requirements; the final
+     * crop region used will be included in the output capture
+     * result.</p>
      *
      * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM
+     * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
      */
     public static final Key<android.graphics.Rect> SCALER_CROP_REGION =
             new Key<android.graphics.Rect>("android.scaler.cropRegion", android.graphics.Rect.class);
@@ -2060,21 +2066,35 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
             new Key<Long>("android.sensor.frameDuration", long.class);
 
     /**
-     * <p>Gain applied to image data. Must be
-     * implemented through analog gain only if set to values
-     * below 'maximum analog sensitivity'.</p>
-     * <p>If the sensor can't apply this exact gain, it should lessen the
-     * gain to the nearest possible value (rather than gain more).</p>
-     * <p>ISO 12232:2006 REI method</p>
+     * <p>The amount of gain applied to sensor data
+     * before processing.</p>
+     * <p>The sensitivity is the standard ISO sensitivity value,
+     * as defined in ISO 12232:2006.</p>
+     * <p>The sensitivity must be within {@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}, and
+     * if if it less than {@link CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY android.sensor.maxAnalogSensitivity}, the camera device
+     * is guaranteed to use only analog amplification for applying the gain.</p>
+     * <p>If the camera device cannot apply the exact sensitivity
+     * requested, it will reduce the gain to the nearest supported
+     * value. The final sensitivity used will be available in the
+     * output capture result.</p>
+     *
+     * @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE
+     * @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY
      */
     public static final Key<Integer> SENSOR_SENSITIVITY =
             new Key<Integer>("android.sensor.sensitivity", int.class);
 
     /**
      * <p>Time at start of exposure of first
-     * row</p>
-     * <p>Monotonic, should be synced to other timestamps in
-     * system</p>
+     * row of the image sensor, in nanoseconds.</p>
+     * <p>The timestamps are also included in all image
+     * buffers produced for the same capture, and will be identical
+     * on all the outputs. The timestamps measure time since an
+     * unspecified starting point, and are monotonically
+     * increasing.</p>
+     * <p>They can be compared with the timestamps for other captures
+     * from the same camera device, but are not guaranteed to be
+     * comparable to any other time source.</p>
      */
     public static final Key<Long> SENSOR_TIMESTAMP =
             new Key<Long>("android.sensor.timestamp", long.class);
@@ -2188,7 +2208,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * lens shading map data in android.statistics.lensShadingMap, with size specified
      * by android.lens.info.shadingMapSize; the returned shading map data will be the one
      * applied by the camera device for this capture request.</p>
-     * <p>The shading map data may depend on the AE and AWB statistics, therefore the reliability
+     * <p>The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
      * of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
      * AUTO modes({@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} <code>!=</code> OFF and {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode} <code>!=</code> OFF),
      * to get best results, it is recommended that the applications wait for the AE and AWB to
@@ -2206,7 +2226,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
 
     /**
      * <p>State of the face detector
-     * unit</p>
+     * unit.</p>
      * <p>Whether face detection is enabled, and whether it
      * should output just the basic fields or the full set of
      * fields. Value must be one of the
@@ -2370,7 +2390,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * applied to that frame.</p>
      * <p>The 4 channel gains are defined in Bayer domain,
      * see {@link CaptureRequest#COLOR_CORRECTION_GAINS android.colorCorrection.gains} for details.</p>
-     * <p>This value should always be calculated by the AWB block,
+     * <p>This value should always be calculated by the auto-white balance (AWB) block,
      * regardless of the android.control.* current values.</p>
      * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
      *
@@ -2396,7 +2416,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
      * that frame.</p>
      * <p>These estimates must be provided for all frames, even if
      * capture settings and color transforms are set by the application.</p>
-     * <p>This value should always be calculated by the AWB block,
+     * <p>This value should always be calculated by the auto-white balance (AWB) block,
      * regardless of the android.control.* current values.</p>
      * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>
      * @deprecated
diff --git a/core/java/android/hardware/camera2/package.html b/core/java/android/hardware/camera2/package.html
index 9f6c2a9..ef0d7bd 100644
--- a/core/java/android/hardware/camera2/package.html
+++ b/core/java/android/hardware/camera2/package.html
@@ -34,49 +34,71 @@ framerate on most Android devices.</p>
 CameraDevices} provide a set of static property information that
 describes the hardware device and the available settings and output
 parameters for the device. This information is provided through the
-{@link android.hardware.camera2.CameraCharacteristics} object.</p>
+{@link android.hardware.camera2.CameraCharacteristics} object, and is
+available through {@link
+android.hardware.camera2.CameraManager#getCameraCharacteristics}</p>
 
 <p>To capture or stream images from a camera device, the application
-must first configure a set of output Surfaces for use with the camera
-device, with {@link
-android.hardware.camera2.CameraDevice#configureOutputs}. Each
-Surface has to be pre-configured with an appropriate size and format
-(if applicable) to match the sizes and formats available from the
-camera device. A target Surface can be obtained from a variety of
-classes, including {@link android.view.SurfaceView}, {@link
-android.graphics.SurfaceTexture} via {@link
-android.view.Surface#Surface(SurfaceTexture), {@link
-android.media.MediaCodec}, and {@link android.media.ImageReader}.
+must first create a {@link
+android.hardware.camera2.CameraCaptureSession camera capture session}
+with a set of output Surfaces for use with the camera device, with
+{@link
+android.hardware.camera2.CameraDevice#createCaptureSession}. Each
+Surface has to be pre-configured with an {@link
+android.hardware.camera2.params.StreamConfigurationMap appropriate
+size and format} (if applicable) to match the sizes and formats
+available from the camera device. A target Surface can be obtained
+from a variety of classes, including {@link android.view.SurfaceView},
+{@link android.graphics.SurfaceTexture} via
+{@link android.view.Surface#Surface(SurfaceTexture)},
+{@link android.media.MediaCodec}, {@link android.media.MediaRecorder},
+{@link android.renderscript.Allocation}, and {@link android.media.ImageReader}.
 </p>
 
+<p>Generally, camera preview images are sent to {@link
+android.view.SurfaceView} or {@link android.view.TextureView} (via its
+{@link android.graphics.SurfaceTexture}). Capture of JPEG images or
+RAW buffers for {@link android.hardware.camera2.DngCreator} can be done
+with {@link android.media.ImageReader} with the
+{android.graphics.ImageFormat#JPEG} and
+{android.graphics.ImageFormat#RAW_SENSOR} formats.  Application-driven
+processing of camera data in RenderScript, OpenGL ES, or directly in
+managed or native code is best done through {@link
+android.renderscript.Allocation} with a YUV {@link
+android.renderscript.Type}, {@link android.graphics.SurfaceTexture},
+and {@link android.media.ImageReader} with a
+{android.graphics.ImageFormat#YUV_420_888} format, respectively.</p>
+
 <p>The application then needs to construct a {@link
 android.hardware.camera2.CaptureRequest}, which defines all the
 capture parameters needed by a camera device to capture a single
 image. The request also lists which of the configured output Surfaces
 should be used as targets for this capture. The CameraDevice has a
 {@link android.hardware.camera2.CameraDevice#createCaptureRequest
-convenience factory method} for creating a request for a given use
-case which is optimized for the Android device the application is
-running on.</p>
+factory method} for creating a {@link
+android.hardware.camera2.CaptureRequest.Builder request builder} for a
+given use case, which is optimized for the Android device the
+application is running on.</p>
 
-<p>Once the request has been set up, it can be handed to the
-CameraDevice either for a one-shot {@link
-android.hardware.camera2.CameraDevice#capture} or for an endlessly
-{@link android.hardware.camera2.CameraDevice#setRepeatingRequest
-repeating} use. Both methods also accept a list of requests to use as
-a burst capture / repeating burst. Repeating requests have a lower
-priority than captures, so a request submitted
+<p>Once the request has been set up, it can be handed to the active
+capture session either for a one-shot {@link
+android.hardware.camera2.CameraCaptureSession#capture capture} or for
+an endlessly {@link
+android.hardware.camera2.CameraCaptureSession#setRepeatingRequest
+repeating} use. Both methods also have a variant that accepts a list
+of requests to use as a burst capture / repeating burst. Repeating
+requests have a lower priority than captures, so a request submitted
 through <code>capture()</code> while there's a repeating request
-configured will be captured as soon as the current repeat (burst)
-capture completes.</p>
+configured will be captured before any new instances of the currently
+repeating (burst) capture will begin capture.</p>
 
 <p>After processing a request, the camera device will produce a {@link
-android.hardware.camera2.CaptureResult} object, which contains
+android.hardware.camera2.TotalCaptureResult} object, which contains
 information about the state of the camera device at time of capture,
 and the final settings used. These may vary somewhat from the request,
 if rounding or resolving contradictory parameters was necessary. The
 camera device will also send a frame of image data into each of the
-output streams included in the request. These are produced
+output {@code Surfaces} included in the request. These are produced
 asynchronously relative to the output CaptureResult, sometimes
 substantially later.</p>
 
diff --git a/core/java/android/hardware/camera2/params/StreamConfiguration.java b/core/java/android/hardware/camera2/params/StreamConfiguration.java
index 1c6b6e9..dd862b5 100644
--- a/core/java/android/hardware/camera2/params/StreamConfiguration.java
+++ b/core/java/android/hardware/camera2/params/StreamConfiguration.java
@@ -28,9 +28,9 @@ import android.util.Size;
 
 /**
  * Immutable class to store the available stream
- * {@link CameraCharacteristics#SCALER_AVAILABLE_STREAM_CONFIGURATIONS configurations} to be used
- * when configuring streams with {@link CameraDevice#configureOutputs}.
- * <!-- TODO: link to input stream configuration -->
+ * {@link CameraCharacteristics#SCALER_AVAILABLE_STREAM_CONFIGURATIONS configurations} to set up
+ * {@link android.view.Surface Surfaces} for creating a {@link CameraCaptureSession capture session}
+ * with {@link CameraDevice#createCaptureSession}.  <!-- TODO: link to input stream configuration -->
  *
  * <p>This is the authoritative list for all input/output formats (and sizes respectively
  * for that format) that are supported by a camera device.</p>
@@ -124,7 +124,7 @@ public final class StreamConfiguration {
      *
      * @return {@code true} if output configuration, {@code false} otherwise
      *
-     * @see CameraDevice#configureOutputs
+     * @see CameraDevice#createCaptureSession
      */
     public boolean isOutput() {
         return !mInput;
diff --git a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
index 4cd6d15..3036425 100644
--- a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
+++ b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
@@ -34,8 +34,10 @@ import static com.android.internal.util.Preconditions.*;
 
 /**
  * Immutable class to store the available stream
- * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP configurations} to be used
- * when configuring streams with {@link CameraDevice#configureOutputs}.
+ * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP configurations} to set up
+ * {@link android.view.Surface Surfaces} for creating a
+ * {@link android.hardware.camera2.CameraCaptureSession capture session} with
+ * {@link android.hardware.camera2.CameraDevice#createCaptureSession}.
  * <!-- TODO: link to input stream configuration -->
  *
  * <p>This is the authoritative list for all <!-- input/ -->output formats (and sizes respectively
@@ -56,7 +58,7 @@ import static com.android.internal.util.Preconditions.*;
  * }</code></pre>
  *
  * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
- * @see CameraDevice#configureOutputs
+ * @see CameraDevice#createCaptureSession
  */
 public final class StreamConfigurationMap {
 
@@ -155,8 +157,8 @@ public final class StreamConfigurationMap {
     }
 
     /**
-     * Determine whether or not output streams can be
-     * {@link CameraDevice#configureOutputs configured} with a particular user-defined format.
+     * Determine whether or not output surfaces with a particular user-defined format can be passed
+     * {@link CameraDevice#createCaptureSession createCaptureSession}.
      *
      * <p>This method determines that the output {@code format} is supported by the camera device;
      * each output {@code surface} target may or may not itself support that {@code format}.
@@ -168,7 +170,7 @@ public final class StreamConfigurationMap {
      * @param format an image format from either {@link ImageFormat} or {@link PixelFormat}
      * @return
      *          {@code true} iff using a {@code surface} with this {@code format} will be
-     *          supported with {@link CameraDevice#configureOutputs}
+     *          supported with {@link CameraDevice#createCaptureSession}
      *
      * @throws IllegalArgumentException
      *          if the image format was not a defined named constant
@@ -176,7 +178,7 @@ public final class StreamConfigurationMap {
      *
      * @see ImageFormat
      * @see PixelFormat
-     * @see CameraDevice#configureOutputs
+     * @see CameraDevice#createCaptureSession
      */
     public boolean isOutputSupportedFor(int format) {
         checkArgumentFormat(format);
@@ -210,7 +212,7 @@ public final class StreamConfigurationMap {
      *
      * <p>Generally speaking this means that creating a {@link Surface} from that class <i>may</i>
      * provide a producer endpoint that is suitable to be used with
-     * {@link CameraDevice#configureOutputs}.</p>
+     * {@link CameraDevice#createCaptureSession}.</p>
      *
      * <p>Since not all of the above classes support output of all format and size combinations,
      * the particular combination should be queried with {@link #isOutputSupportedFor(Surface)}.</p>
@@ -220,7 +222,7 @@ public final class StreamConfigurationMap {
      *
      * @throws NullPointerException if {@code klass} was {@code null}
      *
-     * @see CameraDevice#configureOutputs
+     * @see CameraDevice#createCaptureSession
      * @see #isOutputSupportedFor(Surface)
      */
     public static <T> boolean isOutputSupportedFor(Class<T> klass) {
@@ -244,8 +246,8 @@ public final class StreamConfigurationMap {
     }
 
     /**
-     * Determine whether or not the {@code surface} in its current state is suitable to be
-     * {@link CameraDevice#configureOutputs configured} as an output.
+     * Determine whether or not the {@code surface} in its current state is suitable to be included
+     * in a {@link CameraDevice#createCaptureSession capture session} as an output.
      *
      * <p>Not all surfaces are usable with the {@link CameraDevice}, and not all configurations
      * of that {@code surface} are compatible. Some classes that provide the {@code surface} are
@@ -269,7 +271,7 @@ public final class StreamConfigurationMap {
      *
      * @throws NullPointerException if {@code surface} was {@code null}
      *
-     * @see CameraDevice#configureOutputs
+     * @see CameraDevice#createCaptureSession
      * @see #isOutputSupportedFor(Class)
      */
     public boolean isOutputSupportedFor(Surface surface) {