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

Commit 4480a41d authored by Emilian Peev's avatar Emilian Peev
Browse files

Camera: Polish ExtensionService docs and APIs 

Improve various extension related system APIs including:
- Missing java docs
- Missing doc links
- Incorrect or missing annotations
- Interface names

Bug: 322520569
Test: make docs

Change-Id: I4fc25b419315e92c1df80479c35b572c412f09b4
parent c7d6d505

core/api/system-current.txt

+13 −13
Original line number Diff line number Diff line
@@ -4583,7 +4583,7 @@ package android.hardware.camera2 { 
package android.hardware.camera2.extension {















  @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract class AdvancedExtender {













    ctor @FlaggedApi("com.android.internal.camera.flags.concert_mode") protected AdvancedExtender(@NonNull android.hardware.camera2.CameraManager);













    ctor @FlaggedApi("com.android.internal.camera.flags.concert_mode") public AdvancedExtender(@NonNull android.hardware.camera2.CameraManager);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public abstract java.util.List<android.hardware.camera2.CaptureRequest.Key> getAvailableCaptureRequestKeys(@NonNull String);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public abstract java.util.List<android.hardware.camera2.CaptureResult.Key> getAvailableCaptureResultKeys(@NonNull String);















    method @FlaggedApi("com.android.internal.camera.flags.camera_extensions_characteristics_get") @NonNull public abstract java.util.List<android.util.Pair<android.hardware.camera2.CameraCharacteristics.Key,java.lang.Object>> getAvailableCharacteristicsKeyValues();









@@ -4591,23 +4591,23 @@ package android.hardware.camera2.extension {













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public abstract android.hardware.camera2.extension.SessionProcessor getSessionProcessor();















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public abstract java.util.Map<java.lang.Integer,java.util.List<android.util.Size>> getSupportedCaptureOutputResolutions(@NonNull String);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public abstract java.util.Map<java.lang.Integer,java.util.List<android.util.Size>> getSupportedPreviewOutputResolutions(@NonNull String);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void init(@NonNull String, @NonNull android.hardware.camera2.extension.CharacteristicsMap);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void initialize(@NonNull String, @NonNull android.hardware.camera2.extension.CharacteristicsMap);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract boolean isExtensionAvailable(@NonNull String, @NonNull android.hardware.camera2.extension.CharacteristicsMap);















  }





























  @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract class CameraExtensionService extends android.app.Service {















    ctor @FlaggedApi("com.android.internal.camera.flags.concert_mode") protected CameraExtensionService();













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public android.os.IBinder onBind(@Nullable android.content.Intent);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public final android.os.IBinder onBind(@Nullable android.content.Intent);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public abstract android.hardware.camera2.extension.AdvancedExtender onInitializeAdvancedExtension(int);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract boolean onRegisterClient(@NonNull android.os.IBinder);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void onUnregisterClient(@NonNull android.os.IBinder);















  }





























  @FlaggedApi("com.android.internal.camera.flags.concert_mode") public final class CameraOutputSurface {













    ctor @FlaggedApi("com.android.internal.camera.flags.concert_mode") public CameraOutputSurface(@NonNull android.view.Surface, @Nullable android.util.Size);













    ctor @FlaggedApi("com.android.internal.camera.flags.concert_mode") public CameraOutputSurface(@NonNull android.view.Surface, @NonNull android.util.Size);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public int getImageFormat();













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @Nullable public android.util.Size getSize();













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @Nullable public android.view.Surface getSurface();













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public android.util.Size getSize();













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public android.view.Surface getSurface();















  }





























  @FlaggedApi("com.android.internal.camera.flags.concert_mode") public class CharacteristicsMap {









@@ -4625,10 +4625,10 @@ package android.hardware.camera2.extension {



























  @FlaggedApi("com.android.internal.camera.flags.concert_mode") public final class RequestProcessor {















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public void abortCaptures();













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public int setRepeating(@NonNull android.hardware.camera2.extension.RequestProcessor.Request, @Nullable java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.RequestProcessor.RequestCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public int setRepeating(@NonNull android.hardware.camera2.extension.RequestProcessor.Request, @NonNull java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.RequestProcessor.RequestCallback) throws android.hardware.camera2.CameraAccessException;















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public void stopRepeating();













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public int submit(@NonNull android.hardware.camera2.extension.RequestProcessor.Request, @Nullable java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.RequestProcessor.RequestCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public int submitBurst(@NonNull java.util.List<android.hardware.camera2.extension.RequestProcessor.Request>, @Nullable java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.RequestProcessor.RequestCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public int submit(@NonNull android.hardware.camera2.extension.RequestProcessor.Request, @NonNull java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.RequestProcessor.RequestCallback) throws android.hardware.camera2.CameraAccessException;













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public int submitBurst(@NonNull java.util.List<android.hardware.camera2.extension.RequestProcessor.Request>, @NonNull java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.RequestProcessor.RequestCallback) throws android.hardware.camera2.CameraAccessException;















  }





























  @FlaggedApi("com.android.internal.camera.flags.concert_mode") public static final class RequestProcessor.Request {









@@ -4647,15 +4647,15 @@ package android.hardware.camera2.extension {













  }





























  @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract class SessionProcessor {













    ctor @FlaggedApi("com.android.internal.camera.flags.concert_mode") protected SessionProcessor();













    ctor @FlaggedApi("com.android.internal.camera.flags.concert_mode") public SessionProcessor();















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void deInitSession(@NonNull android.os.IBinder);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") @NonNull public abstract android.hardware.camera2.extension.ExtensionConfiguration initSession(@NonNull android.os.IBinder, @NonNull String, @NonNull android.hardware.camera2.extension.CharacteristicsMap, @NonNull android.hardware.camera2.extension.CameraOutputSurface, @NonNull android.hardware.camera2.extension.CameraOutputSurface);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void onCaptureSessionEnd();















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void onCaptureSessionStart(@NonNull android.hardware.camera2.extension.RequestProcessor, @NonNull String);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void setParameters(@NonNull android.hardware.camera2.CaptureRequest);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract int startCapture(@Nullable java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.SessionProcessor.CaptureCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract int startRepeating(@Nullable java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.SessionProcessor.CaptureCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract int startTrigger(@NonNull android.hardware.camera2.CaptureRequest, @Nullable java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.SessionProcessor.CaptureCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract int startMultiFrameCapture(@NonNull java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.SessionProcessor.CaptureCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract int startRepeating(@NonNull java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.SessionProcessor.CaptureCallback);













    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract int startTrigger(@NonNull android.hardware.camera2.CaptureRequest, @NonNull java.util.concurrent.Executor, @NonNull android.hardware.camera2.extension.SessionProcessor.CaptureCallback);















    method @FlaggedApi("com.android.internal.camera.flags.concert_mode") public abstract void stopRepeating();















  }







































core/java/android/hardware/camera2/extension/AdvancedExtender.java



+32
−9




























Original line number
Diff line number
Diff line








@@ -43,8 +43,9 @@ import java.util.Map;













 *















 * <p>This advanced contract empowers implementations to gain access to















 * more Camera2 capability. This includes: (1) Add custom surfaces with













 * specific formats like YUV, RAW, RAW_DEPTH. (2) Access to













 * the capture request callbacks as well as all the images retrieved of













 * specific formats like {@link android.graphics.ImageFormat#YUV_420_888},













 * {@link android.graphics.ImageFormat#RAW10}, {@link android.graphics.ImageFormat#RAW_DEPTH10}.













 * (2) Access to the capture request callbacks as well as all the images retrieved of















 * various image formats. (3)















 * Able to triggers single or repeating request with the capabilities to















 * specify target surfaces, template id and parameters.









@@ -60,8 +61,14 @@ public abstract class AdvancedExtender {













    private CameraUsageTracker mCameraUsageTracker;















    private static final String TAG = "AdvancedExtender";











































    /**













     * Initialize a camera extension advanced extender instance.













     *













     * @param cameraManager the system camera manager













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)













    protected AdvancedExtender(@NonNull CameraManager cameraManager) {













    public AdvancedExtender(@NonNull CameraManager cameraManager) {















        mCameraManager = cameraManager;















        try {















            String [] cameraIds = mCameraManager.getCameraIdListNoLazy();









@@ -87,6 +94,14 @@ public abstract class AdvancedExtender {













        mCameraUsageTracker = tracker;















    }





























    /**













     * Returns the camera metadata vendor id, that can be used to













     * configure and enable vendor tag support for a particular













     * camera metadata buffer.













     *













     * @param cameraId           The camera2 id string of the camera.













     * @return the camera metadata vendor Id associated with the given camera













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)















    public long getMetadataVendorId(@NonNull String cameraId) {















        long vendorId = mMetadataVendorIdMap.containsKey(cameraId) ?










@@ -131,12 +146,15 @@ public abstract class AdvancedExtender {













     *                           CameraCharacteristics.















     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)













    public abstract void init(@NonNull String cameraId, @NonNull CharacteristicsMap map);













    public abstract void initialize(@NonNull String cameraId, @NonNull CharacteristicsMap map);































    /**















     * Returns supported output format/size map for preview. The format













     * could be PRIVATE or YUV_420_888. Implementations must support













     * PRIVATE format at least.













     * could be {@link android.graphics.ImageFormat#PRIVATE} or













     * {@link android.graphics.ImageFormat#YUV_420_888}. Implementations must support













     * {@link android.graphics.ImageFormat#PRIVATE} format at least.













     * An example of how the map is parsed can be found in













     * {@link #initializeParcelable(Map)}















     *















     * <p>The preview surface format in the CameraCaptureSession may not















     * be identical to the supported preview output format returned here.









@@ -149,11 +167,16 @@ public abstract class AdvancedExtender {





























    /**















     * Returns supported output format/size map for image capture. OEM is













     * required to support both JPEG and YUV_420_888 format output.













     * required to support both {@link android.graphics.ImageFormat#JPEG} and













     * {@link android.graphics.ImageFormat#YUV_420_888} format output.













     * An example of how the map is parsed can be found in













     * {@link #initializeParcelable(Map)}















     *















     * <p>The surface created with this supported















     * format/size could be either added in CameraCaptureSession with HAL













     * processing OR it  configures intermediate surfaces(YUV/RAW..) and













     * processing OR it  configures intermediate surfaces(













     * {@link android.graphics.ImageFormat#YUV_420_888}/













     * {@link android.graphics.ImageFormat#RAW10}..) and















     * writes the output to the output surface.















     * @param cameraId           The camera2 id string of the camera.















     */










@@ -256,7 +279,7 @@ public abstract class AdvancedExtender {





























        @Override















        public void init(String cameraId, Map<String, CameraMetadataNative> charsMapNative) {













            AdvancedExtender.this.init(cameraId, new CharacteristicsMap(charsMapNative));













            AdvancedExtender.this.initialize(cameraId, new CharacteristicsMap(charsMapNative));















        }































        @Override

































core/java/android/hardware/camera2/extension/CameraExtensionService.java



+6
−5




























Original line number
Diff line number
Diff line








@@ -23,6 +23,7 @@ import android.annotation.SystemApi;













import android.app.AppOpsManager;















import android.app.Service;















import android.content.Intent;













import android.hardware.camera2.CameraExtensionCharacteristics.Extension;















import android.os.IBinder;















import android.os.RemoteException;















import android.util.Log;










@@ -92,7 +93,7 @@ public abstract class CameraExtensionService extends Service {













    @FlaggedApi(Flags.FLAG_CONCERT_MODE)















    @Override















    @NonNull













    public IBinder onBind(@Nullable Intent intent) {













    public final IBinder onBind(@Nullable Intent intent) {















        if (mCameraUsageTracker == null) {















            mCameraUsageTracker = new CameraTracker();















        }










@@ -153,21 +154,21 @@ public abstract class CameraExtensionService extends Service {













        }































        @Override













        public IPreviewExtenderImpl initializePreviewExtension(int extensionType)













        public IPreviewExtenderImpl initializePreviewExtension(@Extension int extensionType)















                throws RemoteException {















            // Basic Extension API is not supported















            return null;















        }































        @Override













        public IImageCaptureExtenderImpl initializeImageExtension(int extensionType)













        public IImageCaptureExtenderImpl initializeImageExtension(@Extension int extensionType)















                throws RemoteException {















            // Basic Extension API is not supported















            return null;















        }































        @Override













        public IAdvancedExtenderImpl initializeAdvancedExtension(int extensionType)













        public IAdvancedExtenderImpl initializeAdvancedExtension(@Extension int extensionType)















                throws RemoteException {















            AdvancedExtender extender =  CameraExtensionService.this.onInitializeAdvancedExtension(















                    extensionType);










@@ -205,5 +206,5 @@ public abstract class CameraExtensionService extends Service {













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)















    @NonNull













    public abstract AdvancedExtender onInitializeAdvancedExtension(int extensionType);













    public abstract AdvancedExtender onInitializeAdvancedExtension(@Extension int extensionType);















}
























core/java/android/hardware/camera2/extension/CameraOutputSurface.java



+33
−10




























Original line number
Diff line number
Diff line








@@ -18,8 +18,8 @@ package android.hardware.camera2.extension;





























import android.annotation.FlaggedApi;















import android.annotation.NonNull;













import android.annotation.Nullable;















import android.annotation.SystemApi;













import android.graphics.ImageFormat;















import android.hardware.camera2.utils.SurfaceUtils;















import android.util.Size;















import android.view.Surface;









@@ -28,6 +28,14 @@ import com.android.internal.camera.flags.Flags;













































/**













 * Helper method used to describe a single camera output













 * {@link Surface}.













 *













 * <p>Instances of this class can be used as arguments when













 * initializing {@link ExtensionOutputConfiguration}.</p>













 *













 * @see ExtensionConfiguration













 * @see ExtensionOutputConfiguration















 * @hide















 */















@SystemApi









@@ -40,27 +48,39 @@ public final class CameraOutputSurface {













       mOutputSurface = surface;















    }





























    /**













     * Initialize a camera output surface instance













     *













     * @param surface      Output {@link Surface} to be













     *                     configured as camera output













     * @param size         Requested size of the camera













     *                     output













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)















    public CameraOutputSurface(@NonNull Surface surface,













            @Nullable Size size ) {













            @NonNull Size size) {















        mOutputSurface = new OutputSurface();















        mOutputSurface.surface = surface;















        mOutputSurface.imageFormat = SurfaceUtils.getSurfaceFormat(surface);













        if (size != null) {















        mOutputSurface.size = new android.hardware.camera2.extension.Size();















        mOutputSurface.size.width = size.getWidth();















        mOutputSurface.size.height = size.getHeight();















    }













    }





























    /**













     * Return the current output {@link Surface}













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)













    @Nullable













    @NonNull















    public Surface getSurface() {















        return mOutputSurface.surface;















    }





























    /**













     * Return the current requested output size













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)













    @Nullable













    @NonNull















    public android.util.Size getSize() {















        if (mOutputSurface.size != null) {















            return new Size(mOutputSurface.size.width, mOutputSurface.size.height);









@@ -68,8 +88,11 @@ public final class CameraOutputSurface {













        return null;















    }





























    /**













     * Return the current surface output {@link android.graphics.ImageFormat}













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)













    public int getImageFormat() {













    public @ImageFormat.Format int getImageFormat() {















        return mOutputSurface.imageFormat;















    }















}
























core/java/android/hardware/camera2/extension/CharacteristicsMap.java



+24
−0




























Original line number
Diff line number
Diff line








@@ -30,12 +30,22 @@ import java.util.Map;













import java.util.Set;































/**













 * Helper class used to forward the current













 * system camera characteristics information.













 *















 * @hide















 */















@SystemApi















@FlaggedApi(Flags.FLAG_CONCERT_MODE)















public class CharacteristicsMap {















    private final HashMap<String, CameraCharacteristics> mCharMap;



























    /**













     * Initialize a camera characteristics map instance













     *













     * @param charsMap       Maps camera ids to respective













     *                       {@link CameraCharacteristics}













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)















    CharacteristicsMap(@NonNull Map<String, CameraMetadataNative> charsMap) {















        mCharMap = new HashMap<>();









@@ -44,12 +54,26 @@ public class CharacteristicsMap {













        }















    }





























    /**













     * Return the set of camera ids stored in the characteristics map













     *













     * @return Set of the camera ids stored in the map













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)















    @NonNull















    public Set<String> getCameraIds() {















        return mCharMap.keySet();















    }





























    /**













     * Return the corresponding {@link CameraCharacteristics} given













     * a valid camera id













     *













     * @param cameraId Camera device id













     *













     * @return Valid {@link CameraCharacteristics} instance of null













     *         in case the camera id is not part of the map













     */















    @FlaggedApi(Flags.FLAG_CONCERT_MODE)















    @Nullable















    public CameraCharacteristics get(@NonNull String cameraId) {