/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.hardware.camera2.params; import android.annotation.NonNull; import android.annotation.Nullable; import android.annotation.SystemApi; import android.graphics.ImageFormat; import android.hardware.camera2.CameraCaptureSession; import android.hardware.camera2.CameraDevice; import android.hardware.camera2.utils.HashCodeHelpers; import android.hardware.camera2.utils.SurfaceUtils; import android.os.Parcel; import android.os.Parcelable; import android.util.Log; import android.util.Size; import android.view.Surface; import static com.android.internal.util.Preconditions.*; /** * A class for describing camera output, which contains a {@link Surface} and its specific * configuration for creating capture session. * * @see CameraDevice#createCaptureSessionByOutputConfiguration * */ public final class OutputConfiguration implements Parcelable { /** * Rotation constant: 0 degree rotation (no rotation) * * @hide */ @SystemApi public static final int ROTATION_0 = 0; /** * Rotation constant: 90 degree counterclockwise rotation. * * @hide */ @SystemApi public static final int ROTATION_90 = 1; /** * Rotation constant: 180 degree counterclockwise rotation. * * @hide */ @SystemApi public static final int ROTATION_180 = 2; /** * Rotation constant: 270 degree counterclockwise rotation. * * @hide */ @SystemApi public static final int ROTATION_270 = 3; /** * Invalid surface group ID. * *

An {@link OutputConfiguration} with this value indicates that the included surface *doesn't belong to any surface group.

*/ public static final int SURFACE_GROUP_ID_NONE = -1; /** * Create a new {@link OutputConfiguration} instance with a {@link Surface}. * * @param surface * A Surface for camera to output to. * *

This constructor creates a default configuration, with a surface group ID of * {@value #SURFACE_GROUP_ID_NONE}.

* */ public OutputConfiguration(@NonNull Surface surface) { this(SURFACE_GROUP_ID_NONE, surface, ROTATION_0); } /** * Unknown surface source type. */ private final int SURFACE_TYPE_UNKNOWN = -1; /** * The surface is obtained from {@link android.view.SurfaceView}. */ private final int SURFACE_TYPE_SURFACE_VIEW = 0; /** * The surface is obtained from {@link android.graphics.SurfaceTexture}. */ private final int SURFACE_TYPE_SURFACE_TEXTURE = 1; /** * Create a new {@link OutputConfiguration} instance with a {@link Surface}, * with a surface group ID. * *

* A surface group ID is used to identify which surface group this output surface belongs to. A * surface group is a group of output surfaces that are not intended to receive camera output * buffer streams simultaneously. The {@link CameraDevice} may be able to share the buffers used * by all the surfaces from the same surface group, therefore may reduce the overall memory * footprint. The application should only set the same set ID for the streams that are not * simultaneously streaming. A negative ID indicates that this surface doesn't belong to any * surface group. The default value is {@value #SURFACE_GROUP_ID_NONE}.

* *

For example, a video chat application that has an adaptive output resolution feature would * need two (or more) output resolutions, to switch resolutions without any output glitches. * However, at any given time, only one output is active to minimize outgoing network bandwidth * and encoding overhead. To save memory, the application should set the video outputs to have * the same non-negative group ID, so that the camera device can share the same memory region * for the alternating outputs.

* *

It is not an error to include output streams with the same group ID in the same capture * request, but the resulting memory consumption may be higher than if the two streams were * not in the same surface group to begin with, especially if the outputs have substantially * different dimensions.

* * @param surfaceGroupId * A group ID for this output, used for sharing memory between multiple outputs. * @param surface * A Surface for camera to output to. * */ public OutputConfiguration(int surfaceGroupId, @NonNull Surface surface) { this(surfaceGroupId, surface, ROTATION_0); } /** * Create a new {@link OutputConfiguration} instance. * *

This constructor takes an argument for desired camera rotation

* * @param surface * A Surface for camera to output to. * @param rotation * The desired rotation to be applied on camera output. Value must be one of * ROTATION_[0, 90, 180, 270]. Note that when the rotation is 90 or 270 degrees, * application should make sure corresponding surface size has width and height * transposed relative to the width and height without rotation. For example, * if application needs camera to capture 1280x720 picture and rotate it by 90 degree, * application should set rotation to {@code ROTATION_90} and make sure the * corresponding Surface size is 720x1280. Note that {@link CameraDevice} might * throw {@code IllegalArgumentException} if device cannot perform such rotation. * @hide */ @SystemApi public OutputConfiguration(@NonNull Surface surface, int rotation) { this(SURFACE_GROUP_ID_NONE, surface, rotation); } /** * Create a new {@link OutputConfiguration} instance, with rotation and a group ID. * *

This constructor takes an argument for desired camera rotation and for the surface group * ID. See {@link #OutputConfiguration(int, Surface)} for details of the group ID.

* * @param surfaceGroupId * A group ID for this output, used for sharing memory between multiple outputs. * @param surface * A Surface for camera to output to. * @param rotation * The desired rotation to be applied on camera output. Value must be one of * ROTATION_[0, 90, 180, 270]. Note that when the rotation is 90 or 270 degrees, * application should make sure corresponding surface size has width and height * transposed relative to the width and height without rotation. For example, * if application needs camera to capture 1280x720 picture and rotate it by 90 degree, * application should set rotation to {@code ROTATION_90} and make sure the * corresponding Surface size is 720x1280. Note that {@link CameraDevice} might * throw {@code IllegalArgumentException} if device cannot perform such rotation. * @hide */ @SystemApi public OutputConfiguration(int surfaceGroupId, @NonNull Surface surface, int rotation) { checkNotNull(surface, "Surface must not be null"); checkArgumentInRange(rotation, ROTATION_0, ROTATION_270, "Rotation constant"); mSurfaceGroupId = surfaceGroupId; mSurfaceType = SURFACE_TYPE_UNKNOWN; mSurface = surface; mRotation = rotation; mConfiguredSize = SurfaceUtils.getSurfaceSize(surface); mConfiguredFormat = SurfaceUtils.getSurfaceFormat(surface); mConfiguredDataspace = SurfaceUtils.getSurfaceDataspace(surface); mConfiguredGenerationId = surface.getGenerationId(); mIsDeferredConfig = false; } /** * Create a new {@link OutputConfiguration} instance, with desired Surface size and Surface * source class. *

* This constructor takes an argument for desired Surface size and the Surface source class * without providing the actual output Surface. This is used to setup a output configuration * with a deferred Surface. The application can use this output configuration to create a * session. *

*

* However, the actual output Surface must be set via {@link #setDeferredSurface} and finish the * deferred Surface configuration via {@link CameraCaptureSession#finishDeferredConfiguration} * before submitting a request with this Surface target. The deferred Surface can only be * obtained from either from {@link android.view.SurfaceView} by calling * {@link android.view.SurfaceHolder#getSurface}, or from * {@link android.graphics.SurfaceTexture} via * {@link android.view.Surface#Surface(android.graphics.SurfaceTexture)}). *

* * @param surfaceSize Size for the deferred surface. * @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 OutputConfiguration(@NonNull Size surfaceSize, @NonNull Class klass) { checkNotNull(klass, "surfaceSize must not be null"); checkNotNull(klass, "klass must not be null"); if (klass == android.view.SurfaceHolder.class) { mSurfaceType = SURFACE_TYPE_SURFACE_VIEW; } else if (klass == android.graphics.SurfaceTexture.class) { mSurfaceType = SURFACE_TYPE_SURFACE_TEXTURE; } else { mSurfaceType = SURFACE_TYPE_UNKNOWN; throw new IllegalArgumentException("Unknow surface source class type"); } mSurfaceGroupId = SURFACE_GROUP_ID_NONE; mSurface = null; mRotation = ROTATION_0; mConfiguredSize = surfaceSize; mConfiguredFormat = StreamConfigurationMap.imageFormatToInternal(ImageFormat.PRIVATE); mConfiguredDataspace = StreamConfigurationMap.imageFormatToDataspace(ImageFormat.PRIVATE); mConfiguredGenerationId = 0; mIsDeferredConfig = true; } /** * Check if this configuration has deferred configuration. * *

This will return true if the output configuration was constructed with surface deferred. * It will return true even after the deferred surface is set later.

* * @return true if this configuration has deferred surface. * @hide */ public boolean isDeferredConfiguration() { return mIsDeferredConfig; } /** * Set the deferred surface to this OutputConfiguration. * *

* The deferred surface must be obtained from either from {@link android.view.SurfaceView} by * calling {@link android.view.SurfaceHolder#getSurface}, or from * {@link android.graphics.SurfaceTexture} via * {@link android.view.Surface#Surface(android.graphics.SurfaceTexture)}). After the deferred * surface is set, the application must finish the deferred surface configuration via * {@link CameraCaptureSession#finishDeferredConfiguration} before submitting a request with * this surface target. *

* * @param surface The deferred surface to be set. * @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"); if (mSurface != null) { throw new IllegalStateException("Deferred surface is already set!"); } // This will throw IAE is the surface was abandoned. Size surfaceSize = SurfaceUtils.getSurfaceSize(surface); if (!surfaceSize.equals(mConfiguredSize)) { Log.w(TAG, "Deferred surface size " + surfaceSize + " is different with pre-configured size " + mConfiguredSize + ", the pre-configured size will be used."); } mSurface = surface; } /** * Create a new {@link OutputConfiguration} instance with another {@link OutputConfiguration} * instance. * * @param other Another {@link OutputConfiguration} instance to be copied. * * @hide */ public OutputConfiguration(@NonNull OutputConfiguration other) { if (other == null) { throw new IllegalArgumentException("OutputConfiguration shouldn't be null"); } this.mSurface = other.mSurface; this.mRotation = other.mRotation; this.mSurfaceGroupId = other.mSurfaceGroupId; this.mSurfaceType = other.mSurfaceType; this.mConfiguredDataspace = other.mConfiguredDataspace; this.mConfiguredFormat = other.mConfiguredFormat; this.mConfiguredSize = other.mConfiguredSize; this.mConfiguredGenerationId = other.mConfiguredGenerationId; this.mIsDeferredConfig = other.mIsDeferredConfig; } /** * Create an OutputConfiguration from Parcel. */ private OutputConfiguration(@NonNull Parcel source) { int rotation = source.readInt(); int surfaceSetId = source.readInt(); int surfaceType = source.readInt(); int width = source.readInt(); int height = source.readInt(); Surface surface = Surface.CREATOR.createFromParcel(source); checkArgumentInRange(rotation, ROTATION_0, ROTATION_270, "Rotation constant"); mSurfaceGroupId = surfaceSetId; mSurface = surface; mRotation = rotation; if (surface != null) { mSurfaceType = SURFACE_TYPE_UNKNOWN; mConfiguredSize = SurfaceUtils.getSurfaceSize(mSurface); mConfiguredFormat = SurfaceUtils.getSurfaceFormat(mSurface); mConfiguredDataspace = SurfaceUtils.getSurfaceDataspace(mSurface); mConfiguredGenerationId = mSurface.getGenerationId(); mIsDeferredConfig = true; } else { mSurfaceType = surfaceType; mConfiguredSize = new Size(width, height); mConfiguredFormat = StreamConfigurationMap.imageFormatToInternal(ImageFormat.PRIVATE); mConfiguredGenerationId = 0; mConfiguredDataspace = StreamConfigurationMap.imageFormatToDataspace(ImageFormat.PRIVATE); mIsDeferredConfig = false; } } /** * Get the {@link Surface} associated with this {@link OutputConfiguration}. * * @return the {@link Surface} associated with this {@link OutputConfiguration}. */ @NonNull public Surface getSurface() { return mSurface; } /** * Get the rotation associated with this {@link OutputConfiguration}. * * @return the rotation associated with this {@link OutputConfiguration}. * Value will be one of ROTATION_[0, 90, 180, 270] * * @hide */ @SystemApi public int getRotation() { return mRotation; } /** * Get the surface group ID associated with this {@link OutputConfiguration}. * * @return the surface group ID associated with this {@link OutputConfiguration}. * The default value is {@value #SURFACE_GROUP_ID_NONE}. */ public int getSurfaceGroupId() { return mSurfaceGroupId; } public static final Parcelable.Creator CREATOR = new Parcelable.Creator() { @Override public OutputConfiguration createFromParcel(Parcel source) { try { OutputConfiguration outputConfiguration = new OutputConfiguration(source); return outputConfiguration; } catch (Exception e) { Log.e(TAG, "Exception creating OutputConfiguration from parcel", e); return null; } } @Override public OutputConfiguration[] newArray(int size) { return new OutputConfiguration[size]; } }; @Override public int describeContents() { return 0; } @Override public void writeToParcel(Parcel dest, int flags) { if (dest == null) { throw new IllegalArgumentException("dest must not be null"); } dest.writeInt(mRotation); dest.writeInt(mSurfaceGroupId); dest.writeInt(mSurfaceType); dest.writeInt(mConfiguredSize.getWidth()); dest.writeInt(mConfiguredSize.getHeight()); if (mSurface != null) { mSurface.writeToParcel(dest, flags); } } /** * Check if this {@link OutputConfiguration} is equal to another {@link OutputConfiguration}. * *

Two output configurations are only equal if and only if the underlying surfaces, surface * properties (width, height, format, dataspace) when the output configurations are created, * and all other configuration parameters are equal.

* * @return {@code true} if the objects were equal, {@code false} otherwise */ @Override public boolean equals(Object obj) { if (obj == null) { return false; } else if (this == obj) { return true; } else if (obj instanceof OutputConfiguration) { final OutputConfiguration other = (OutputConfiguration) obj; boolean iSSurfaceEqual = mSurface == other.mSurface && mConfiguredGenerationId == other.mConfiguredGenerationId ; if (mIsDeferredConfig) { Log.i(TAG, "deferred config has the same surface"); iSSurfaceEqual = true; } return mRotation == other.mRotation && iSSurfaceEqual&& mConfiguredSize.equals(other.mConfiguredSize) && mConfiguredFormat == other.mConfiguredFormat && mConfiguredDataspace == other.mConfiguredDataspace && mSurfaceGroupId == other.mSurfaceGroupId && mSurfaceType == other.mSurfaceType && mIsDeferredConfig == other.mIsDeferredConfig; } return false; } /** * {@inheritDoc} */ @Override public int hashCode() { // Need ensure that the hashcode remains unchanged after set a deferred surface. Otherwise // The deferred output configuration will be lost in the camera streammap after the deferred // surface is set. if (mIsDeferredConfig) { return HashCodeHelpers.hashCode( mRotation, mConfiguredSize.hashCode(), mConfiguredFormat, mConfiguredDataspace, mSurfaceGroupId, mSurfaceType); } return HashCodeHelpers.hashCode( mRotation, mSurface.hashCode(), mConfiguredGenerationId, mConfiguredSize.hashCode(), mConfiguredFormat, mConfiguredDataspace, mSurfaceGroupId); } private static final String TAG = "OutputConfiguration"; private Surface mSurface; private final int mRotation; private final int mSurfaceGroupId; // Surface source type, this is only used by the deferred surface configuration objects. private final int mSurfaceType; // The size, format, and dataspace of the surface when OutputConfiguration is created. private final Size mConfiguredSize; private final int mConfiguredFormat; private final int mConfiguredDataspace; // Surface generation ID to distinguish changes to Surface native internals private final int mConfiguredGenerationId; // Flag indicating if this config has deferred surface. private final boolean mIsDeferredConfig; }