Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 1a645803 authored by Eino-Ville Talvala's avatar Eino-Ville Talvala
Browse files

Camera2: Unhide deferred surface configuration APIs 

To speed up camera startup, allow setting up a camera capture session
before all the output Surfaces are available (but their eventual sizes
and types are known). Also allow images to be captured to the
non-deferred outputs even before the deferred outputs are available.

This allows parallelizing of camera startup and UI layout.

Test: android.hardware.camera2.cts.SurfaceViewPreviewTest#testDeferrredSurfaces 
passes
Bug: 31319716
Change-Id: I657efc39bb8cc2d4bf201e5d70807a227ef82dde
parent 6abee0ef

api/current.txt

+3 −0
Original line number Diff line number Diff line
@@ -13843,6 +13843,7 @@ package android.hardware.camera2 { 
    method public abstract int capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract void close();

    method public abstract void finishDeferredConfiguration(java.util.List<android.hardware.camera2.params.OutputConfiguration>) throws android.hardware.camera2.CameraAccessException;

    method public abstract android.hardware.camera2.CameraDevice getDevice();

    method public abstract android.view.Surface getInputSurface();

    method public abstract boolean isReprocessable();
@@ -14481,9 +14482,11 @@ package android.hardware.camera2.params { 
  public final class OutputConfiguration implements android.os.Parcelable {

    ctor public OutputConfiguration(android.view.Surface);

    ctor public OutputConfiguration(int, android.view.Surface);

    ctor public OutputConfiguration(android.util.Size, java.lang.Class<T>);

    method public int describeContents();

    method public android.view.Surface getSurface();

    method public int getSurfaceGroupId();

    method public void setDeferredSurface(android.view.Surface);

    method public void writeToParcel(android.os.Parcel, int);

    field public static final android.os.Parcelable.Creator<android.hardware.camera2.params.OutputConfiguration> CREATOR;

    field public static final int SURFACE_GROUP_ID_NONE = -1; // 0xffffffff

api/system-current.txt

+3 −0
Original line number Diff line number Diff line
@@ -14291,6 +14291,7 @@ package android.hardware.camera2 { 
    method public abstract int capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract void close();

    method public abstract void finishDeferredConfiguration(java.util.List<android.hardware.camera2.params.OutputConfiguration>) throws android.hardware.camera2.CameraAccessException;

    method public abstract android.hardware.camera2.CameraDevice getDevice();

    method public abstract android.view.Surface getInputSurface();

    method public abstract boolean isReprocessable();
@@ -14931,10 +14932,12 @@ package android.hardware.camera2.params { 
    ctor public OutputConfiguration(int, android.view.Surface);

    ctor public OutputConfiguration(android.view.Surface, int);

    ctor public OutputConfiguration(int, android.view.Surface, int);

    ctor public OutputConfiguration(android.util.Size, java.lang.Class<T>);

    method public int describeContents();

    method public int getRotation();

    method public android.view.Surface getSurface();

    method public int getSurfaceGroupId();

    method public void setDeferredSurface(android.view.Surface);

    method public void writeToParcel(android.os.Parcel, int);

    field public static final android.os.Parcelable.Creator<android.hardware.camera2.params.OutputConfiguration> CREATOR;

    field public static final int ROTATION_0 = 0; // 0x0

api/test-current.txt

+3 −0
Original line number Diff line number Diff line
@@ -13859,6 +13859,7 @@ package android.hardware.camera2 { 
    method public abstract int capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract int captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) throws android.hardware.camera2.CameraAccessException;

    method public abstract void close();

    method public abstract void finishDeferredConfiguration(java.util.List<android.hardware.camera2.params.OutputConfiguration>) throws android.hardware.camera2.CameraAccessException;

    method public abstract android.hardware.camera2.CameraDevice getDevice();

    method public abstract android.view.Surface getInputSurface();

    method public abstract boolean isReprocessable();
@@ -14497,9 +14498,11 @@ package android.hardware.camera2.params { 
  public final class OutputConfiguration implements android.os.Parcelable {

    ctor public OutputConfiguration(android.view.Surface);

    ctor public OutputConfiguration(int, android.view.Surface);

    ctor public OutputConfiguration(android.util.Size, java.lang.Class<T>);

    method public int describeContents();

    method public android.view.Surface getSurface();

    method public int getSurfaceGroupId();

    method public void setDeferredSurface(android.view.Surface);

    method public void writeToParcel(android.os.Parcel, int);

    field public static final android.os.Parcelable.Creator<android.hardware.camera2.params.OutputConfiguration> CREATOR;

    field public static final int SURFACE_GROUP_ID_NONE = -1; // 0xffffffff

core/java/android/hardware/camera2/CameraCaptureSession.java

+30 −33
Original line number Diff line number Diff line
@@ -221,34 +221,32 @@ public abstract class CameraCaptureSession implements AutoCloseable { 
    public abstract void tearDown(@NonNull Surface surface) throws CameraAccessException;



    /**

     * <p>

     * Finish the deferred output configurations where the output Surface was not configured before.

     * </p>

     * <p>

     * For camera use cases where a preview and other output configurations need to be configured,

     * it can take some time for the preview Surface to be ready (e.g., if the preview Surface is

     * obtained from {@link android.view.SurfaceView}, the SurfaceView is ready after the UI layout

     * is done, then it takes some time to get the preview Surface).

     * </p>

     * <p>

     * To speed up camera startup time, the application can configure the

     * {@link CameraCaptureSession} with the desired preview size, and defer the preview output

     * configuration until the Surface is ready. After the {@link CameraCaptureSession} is created

     * successfully with this deferred configuration and other normal configurations, the

     * application can submit requests that don't include deferred output Surfaces. Once the

     * deferred Surface is ready, the application can set the Surface to the same deferred output

     * configuration with the {@link OutputConfiguration#setDeferredSurface} method, and then finish

     * the deferred output configuration via this method, before it can submit requests with this

     * output target.

     * </p>

     * <p>

     * The output Surfaces included by this list of deferred {@link OutputConfiguration

     * OutputConfigurations} can be used as {@link CaptureRequest} targets as soon as this call

     * returns;

     * </p>

     * <p>

     * This method is not supported by Legacy devices.

     * </p>

     * <p>Finish the deferred output configurations where the output Surface was not configured

     * before.</p>

     *

     * <p>For camera use cases where a preview and other output configurations need to be

     * configured, it can take some time for the preview Surface to be ready. For example, if the

     * preview Surface is obtained from {@link android.view.SurfaceView}, the SurfaceView will only

     * be ready after the UI layout is done, potentially delaying camera startup.</p>

     *

     * <p>To speed up camera startup time, the application can configure the

     * {@link CameraCaptureSession} with the eventual preview size (via

     * {@link OutputConfiguration#OutputConfiguration(Size,Class) a deferred OutputConfiguration}),

     * and defer the preview output configuration until the Surface is ready. After the

     * {@link CameraCaptureSession} is created successfully with this deferred output and other

     * normal outputs, the application can start submitting requests as long as they do not include

     * deferred output Surfaces. Once a deferred Surface is ready, the application can set the

     * Surface on the deferred output configuration with the

     * {@link OutputConfiguration#setDeferredSurface} method, and then finish the deferred output

     * configuration via this method, before it can submit capture requests with this output

     * target.</p>

     *

     * <p>The output Surfaces included by this list of deferred

     * {@link OutputConfiguration OutputConfigurations} can be used as {@link CaptureRequest}

     * targets as soon as this call returns.</p>

     *

     * <p>This method is not supported by

     * {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}-level devices.</p>

     *

     * @param deferredOutputConfigs a list of {@link OutputConfiguration OutputConfigurations} that

     *            have had {@link OutputConfiguration#setDeferredSurface setDeferredSurface} invoked
@@ -256,13 +254,12 @@ public abstract class CameraCaptureSession implements AutoCloseable { 
     * @throws CameraAccessException if the camera device is no longer connected or has encountered

     *             a fatal error.

     * @throws IllegalStateException if this session is no longer active, either because the session

     *             was explicitly closed, a new session has been created or the camera device has

     *             been closed. Or if this output configuration was already finished with the

     *             included surface before.

     *             was explicitly closed, a new session has been created, or the camera device has

     *             been closed.

     * @throws IllegalArgumentException for invalid output configurations, including ones where the

     *             source of the Surface is no longer valid or the Surface is from a unsupported

     *             source.

     * @hide

     *             source. Or if one of the output configuration was already finished with an

     *             included surface in a prior call.

     */

    public abstract void finishDeferredConfiguration(

            List<OutputConfiguration> deferredOutputConfigs) throws CameraAccessException;

core/java/android/hardware/camera2/params/OutputConfiguration.java

+0 −2
Original line number Diff line number Diff line
@@ -229,7 +229,6 @@ public final class OutputConfiguration implements Parcelable { 
     * @param klass a non-{@code null} {@link Class} object reference that indicates the source of

     *            this surface. Only {@link android.view.SurfaceHolder SurfaceHolder.class} and

     *            {@link android.graphics.SurfaceTexture SurfaceTexture.class} are supported.

     * @hide

     */

    public <T> OutputConfiguration(@NonNull Size surfaceSize, @NonNull Class<T> klass) {

        checkNotNull(klass, "surfaceSize must not be null");
@@ -283,7 +282,6 @@ public final class OutputConfiguration implements Parcelable { 
     * @throws IllegalArgumentException if the Surface is invalid.

     * @throws IllegalStateException if a Surface was already set to this deferred

     *         OutputConfiguration.

     * @hide

     */

    public void setDeferredSurface(@NonNull Surface surface) {

        checkNotNull(surface, "Surface must not be null");