Camera: Add details about default output YUV encoding

Make it clear that YUV_420_8888 buffers from camera 1) Are using JFIF YUV<->RGB transforms 2) Should be interpreted as sRGB after conversion to sRGB Also fix some broken doc links in the camera package. Test: m offline-sdk-docs Bug: 290382236 Change-Id: Iaf18df8371e596a498d14c33abd495a1d367a311
2023-07-07 11:22:11 -07:00
parent dcc5cf1712
commit c983047566
7 changed files with 63 additions and 40 deletions
--- a/core/java/android/hardware/camera2/CameraDevice.java
+++ b/core/java/android/hardware/camera2/CameraDevice.java
@@ -283,7 +283,8 @@ public abstract class CameraDevice implements AutoCloseable {
     * @see StreamConfigurationMap#getInputFormats
     * @see StreamConfigurationMap#getInputSizes
     * @see StreamConfigurationMap#getValidOutputFormatsForInput
-     * @see StreamConfigurationMap#getOutputSizes
+     * @see StreamConfigurationMap#getOutputSizes(int)
+     * @see StreamConfigurationMap#getOutputSizes(Class)
     * @see android.media.ImageWriter
     * @see android.media.ImageReader
     * @deprecated Please use {@link
--- a/core/java/android/hardware/camera2/CameraManager.java
+++ b/core/java/android/hardware/camera2/CameraManager.java
@@ -129,14 +129,17 @@ public final class CameraManager {
    /**
     * Enable physical camera availability callbacks when the logical camera is unavailable
     *
-     * <p>Previously once a logical camera becomes unavailable, no {@link
-     * #onPhysicalCameraAvailable} or {@link #onPhysicalCameraUnavailable} will be called until
-     * the logical camera becomes available again. The results in the app opening the logical
-     * camera not able to receive physical camera availability change.</p>
+     * <p>Previously once a logical camera becomes unavailable, no
+     * {@link AvailabilityCallback#onPhysicalCameraAvailable} or
+     * {@link AvailabilityCallback#onPhysicalCameraUnavailable} will
+     * be called until the logical camera becomes available again. The
+     * results in the app opening the logical camera not able to
+     * receive physical camera availability change.</p>
     *
-     * <p>With this change, the {@link #onPhysicalCameraAvailable} and {@link
-     * #onPhysicalCameraUnavailable} can still be called while the logical camera is unavailable.
-     * </p>
+     * <p>With this change, the {@link
+     * AvailabilityCallback#onPhysicalCameraAvailable} and {@link
+     * AvailabilityCallback#onPhysicalCameraUnavailable} can still be
+     * called while the logical camera is unavailable.  </p>
     */
    @ChangeId
    @EnabledSince(targetSdkVersion = android.os.Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
--- a/core/java/android/hardware/camera2/package.html
+++ b/core/java/android/hardware/camera2/package.html
@@ -62,12 +62,28 @@ RAW buffers for {@link android.hardware.camera2.DngCreator} can be
 done with {@link android.media.ImageReader} with the {@link
 android.graphics.ImageFormat#JPEG} and {@link
 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 {@link
-android.graphics.ImageFormat#YUV_420_888} format, respectively.</p>
+processing of camera data in OpenGL ES, or directly in managed or
+native code is best done through {@link
+android.graphics.SurfaceTexture}, or {@link android.media.ImageReader}
+with a {@link android.graphics.ImageFormat#YUV_420_888} format,
+respectively. </p>
+
+<p>By default, YUV-format buffers provided by the camera are using the
+JFIF YUV<->RGB transform matrix (equivalent to Rec.601 full-range
+encoding), and after conversion to RGB with this matrix, the resulting
+RGB data is in the sRGB colorspace.  Captured JPEG images may contain
+an ICC profile to specify their color space information; if not, they
+should be assumed to be in the sRGB space as well. On some devices,
+the output colorspace can be changed via {@link
+android.hardware.camera2.params.SessionConfiguration#setColorSpace}.
+</p>
+<p>
+Note that although the YUV->RGB transform is the JFIF matrix (Rec.601
+full-range), due to legacy and compatibility reasons, the output is in
+the sRGB colorspace, which uses the Rec.709 color primaries. Image
+processing code can safely treat the output RGB as being in the sRGB
+colorspace.
+</p>

 <p>The application then needs to construct a {@link
 android.hardware.camera2.CaptureRequest}, which defines all the
--- a/core/java/android/hardware/camera2/params/ColorSpaceProfiles.java
+++ b/core/java/android/hardware/camera2/params/ColorSpaceProfiles.java
@@ -192,7 +192,7 @@ public final class ColorSpaceProfiles {
     * @see OutputConfiguration#setDynamicRangeProfile
     * @see SessionConfiguration#setColorSpace
     * @see ColorSpace.Named
-     * @see DynamicRangeProfiles.Profile
+     * @see DynamicRangeProfiles
     */
    public @NonNull Set<Long> getSupportedDynamicRangeProfiles(@NonNull ColorSpace.Named colorSpace,
            @ImageFormat.Format int imageFormat) {
@@ -230,7 +230,7 @@ public final class ColorSpaceProfiles {
     * @see SessionConfiguration#setColorSpace
     * @see OutputConfiguration#setDynamicRangeProfile
     * @see ColorSpace.Named
-     * @see DynamicRangeProfiles.Profile
+     * @see DynamicRangeProfiles
     */
    public @NonNull Set<ColorSpace.Named> getSupportedColorSpacesForDynamicRange(
            @ImageFormat.Format int imageFormat,
--- a/core/java/android/hardware/camera2/params/RecommendedStreamConfigurationMap.java
+++ b/core/java/android/hardware/camera2/params/RecommendedStreamConfigurationMap.java
@@ -45,7 +45,7 @@ import java.util.Set;
 * Immutable class to store the recommended stream 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}.
+ * {@link android.hardware.camera2.CameraDevice#createCaptureSession(SessionConfiguration)}.
 *
 * <p>The recommended list does not replace or deprecate the exhaustive complete list found in
 * {@link StreamConfigurationMap}. It is a suggestion about available power and performance
@@ -70,7 +70,7 @@ import java.util.Set;
 * }</code></pre>
 *
 * @see CameraCharacteristics#getRecommendedStreamConfigurationMap
- * @see CameraDevice#createCaptureSession
+ * @see CameraDevice#createCaptureSession(SessionConfiguration)
 */
 public final class RecommendedStreamConfigurationMap {

@@ -282,7 +282,7 @@ public final class RecommendedStreamConfigurationMap {

    /**
     * Determine whether or not output surfaces with a particular user-defined format can be passed
-     * {@link CameraDevice#createCaptureSession createCaptureSession}.
+     * {@link CameraDevice#createCaptureSession(SessionConfiguration) createCaptureSession}.
     *
     * <p>
     * For further information refer to {@link StreamConfigurationMap#isOutputSupportedFor}.
@@ -292,7 +292,7 @@ public final class RecommendedStreamConfigurationMap {
     * @param format an image format from either {@link ImageFormat} or {@link PixelFormat}
     * @return
     *          {@code true} if using a {@code surface} with this {@code format} will be
-     *          supported with {@link CameraDevice#createCaptureSession}
+     *          supported with {@link CameraDevice#createCaptureSession(SessionConfiguration)}
     *
     * @throws IllegalArgumentException
     *          if the image format was not a defined named constant
@@ -508,8 +508,10 @@ public final class RecommendedStreamConfigurationMap {
    }

    /**
-     * 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.
+     * Determine whether or not the {@code surface} in its current
+     * state is suitable to be included in a {@link
+     * CameraDevice#createCaptureSession(SessionConfiguration) capture
+     * session} as an output.
     *
     * <p>For more information refer to {@link StreamConfigurationMap#isOutputSupportedFor}.
     * </p>
--- a/core/java/android/hardware/camera2/params/SessionConfiguration.java
+++ b/core/java/android/hardware/camera2/params/SessionConfiguration.java
@@ -55,7 +55,7 @@ public final class SessionConfiguration implements Parcelable {
     * at regular non high speed FPS ranges and optionally {@link InputConfiguration} for
     * reprocessable sessions.
     *
-     * @see CameraDevice#createCaptureSession
+     * @see CameraDevice#createCaptureSession(SessionConfiguration)
     * @see CameraDevice#createReprocessableCaptureSession
     */
    public static final int SESSION_REGULAR = CameraDevice.SESSION_OPERATION_MODE_NORMAL;
@@ -110,10 +110,7 @@ public final class SessionConfiguration implements Parcelable {
     *
     * @see #SESSION_REGULAR
     * @see #SESSION_HIGH_SPEED
-     * @see CameraDevice#createCaptureSession(List, CameraCaptureSession.StateCallback, Handler)
-     * @see CameraDevice#createCaptureSessionByOutputConfigurations
-     * @see CameraDevice#createReprocessableCaptureSession
-     * @see CameraDevice#createConstrainedHighSpeedCaptureSession
+     * @see CameraDevice#createCaptureSession(SessionConfiguration)
     */
    public SessionConfiguration(@SessionMode int sessionType,
            @NonNull List<OutputConfiguration> outputs,
--- a/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
+++ b/core/java/android/hardware/camera2/params/StreamConfigurationMap.java
@@ -41,7 +41,7 @@ import java.util.Set;
 * {@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}.
+ * {@link android.hardware.camera2.CameraDevice#createCaptureSession(SessionConfiguration)}.
 * <!-- TODO: link to input stream configuration -->
 *
 * <p>This is the authoritative list for all <!-- input/ -->output formats (and sizes respectively
@@ -62,7 +62,7 @@ import java.util.Set;
 * }</code></pre>
 *
 * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP
- * @see CameraDevice#createCaptureSession
+ * @see CameraDevice#createCaptureSession(SessionConfiguration)
 */
 public final class StreamConfigurationMap {

@@ -456,7 +456,7 @@ public final class StreamConfigurationMap {

    /**
     * Determine whether or not output surfaces with a particular user-defined format can be passed
-     * {@link CameraDevice#createCaptureSession createCaptureSession}.
+     * {@link CameraDevice#createCaptureSession(SessionConfiguration) 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}.
@@ -468,7 +468,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#createCaptureSession}
+     *          supported with {@link CameraDevice#createCaptureSession(SessionConfiguration)}
     *
     * @throws IllegalArgumentException
     *          if the image format was not a defined named constant
@@ -476,7 +476,7 @@ public final class StreamConfigurationMap {
     *
     * @see ImageFormat
     * @see PixelFormat
-     * @see CameraDevice#createCaptureSession
+     * @see CameraDevice#createCaptureSession(SessionConfiguration)
     */
    public boolean isOutputSupportedFor(int format) {
        checkArgumentFormat(format);
@@ -521,7 +521,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#createCaptureSession}.</p>
+     * {@link CameraDevice#createCaptureSession(SessionConfiguration)}.</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>
@@ -531,7 +531,7 @@ public final class StreamConfigurationMap {
     *
     * @throws NullPointerException if {@code klass} was {@code null}
     *
-     * @see CameraDevice#createCaptureSession
+     * @see CameraDevice#createCaptureSession(SessionConfiguration)
     * @see #isOutputSupportedFor(Surface)
     */
    public static <T> boolean isOutputSupportedFor(Class<T> klass) {
@@ -555,8 +555,10 @@ public final class StreamConfigurationMap {
    }

    /**
-     * 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.
+     * Determine whether or not the {@code surface} in its current
+     * state is suitable to be included in a {@link
+     * CameraDevice#createCaptureSession(SessionConfiguration) 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
@@ -588,7 +590,7 @@ public final class StreamConfigurationMap {
     * @throws NullPointerException if {@code surface} was {@code null}
     * @throws IllegalArgumentException if the Surface endpoint is no longer valid
     *
-     * @see CameraDevice#createCaptureSession
+     * @see CameraDevice#createCaptureSession(SessionConfiguration)
     * @see #isOutputSupportedFor(Class)
     */
    public boolean isOutputSupportedFor(Surface surface) {
@@ -623,14 +625,16 @@ public final class StreamConfigurationMap {
    }

    /**
-     * Determine whether or not the particular stream configuration is suitable to be included
-     * in a {@link CameraDevice#createCaptureSession capture session} as an output.
+     * Determine whether or not the particular stream configuration is
+     * suitable to be included in a {@link
+     * CameraDevice#createCaptureSession(SessionConfiguration) capture
+     * session} as an output.
     *
     * @param size stream configuration size
     * @param format stream configuration format
     * @return {@code true} if this is supported, {@code false} otherwise
     *
-     * @see CameraDevice#createCaptureSession
+     * @see CameraDevice#createCaptureSession(SessionConfiguration)
     * @see #isOutputSupportedFor(Class)
     * @hide
     */