com.avalancheevantage.android.camera3

Class Camera3

java.lang.Object

com.avalancheevantage.android.camera3.Camera3

public final class Camera3
extends java.lang.Object

Camera3 is a wrapper around the Android Camera2 API. It is an attempt to provide a single simple and safe interface to the notoriously bad Android Camera2 API.

It is adapted from the Camera2Basic Google Sample at https://github.com/googlesamples/android-Camera2Basic

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Camera3.CameraState
static interface	Camera3.PreviewSizeCallback

Field Summary

Fields

Modifier and Type	Field and Description
static CaptureRequestConfiguration	CAPTURE_CONFIG_DEFAULT
static ErrorHandler	ERROR_HANDLER_DEFAULT
static CaptureRequestConfiguration	PRECAPTURE_CONFIG_NONE
static CaptureRequestConfiguration	PRECAPTURE_CONFIG_TRIGGER_AUTO_EXPOSE

Constructor Summary

Constructors

Constructor and Description
Camera3(android.content.Context context, ErrorHandler errorHandler) Creates a new Camera3 manager instance.

Method Summary

Modifier and Type	Method and Description
boolean	captureConfigured() It is only safe to call resume() if you have already configured a capture session with startCaptureSession(String, PreviewHandler, List, List, Runnable).
void	captureImage(StillCaptureHandler handler, CaptureRequestConfiguration precapture, CaptureRequestConfiguration capture) Starts the process of capturing a still image from the camera.
java.util.List<java.lang.String>	getAvailableCameras()
java.util.List<android.util.Size>	getAvailableImageSizes(java.lang.String cameraId, int format) Get all supported image sizes for the given image format and camera
java.util.Collection<android.util.Size>	getAvailableVideoSizes(java.lang.String cameraId) TODO doc TODO BUG sometimes some of these sizes don't actually work - lead to surface abandoned error
android.hardware.camera2.CameraCharacteristics	getCameraInfo(java.lang.String cameraId)
android.util.Size	getDefaultVideoSize(java.lang.String cameraId) Get a recommended video size at a reasonable aspect ratio and size.
ErrorHandler	getErrorHandler()
android.util.Size	getLargestAvailableImageSize(java.lang.String cameraId, int imageFormat) Gets the largest image dimensions (by area) that the given camera is able to take in the given format
boolean	hasCameraPermission() Checks if the app has permission to access the camera
boolean	hasMicrophonePermission() Checks if the app has permission to access the microphone
boolean	hasWritePermission() Checks if the app has permission to write to the file system.
boolean	isStarted() Images can only be captured between calling resume() or startCaptureSession(String, PreviewHandler, List, List, Runnable) and calling pause().
void	pause() Stops background threads and frees the camera.
boolean	requestsInQueue() Check if there are any enqueued requests that have not yet been resolved
void	resume()
void	resume(java.lang.Runnable onSessionRestarted) Resumes the capture session established by the last call to startCaptureSession(String, PreviewHandler, List)
void	saveImageAsync(android.media.Image image, java.io.File file) A utility method to asynchronously save an image file.
void	saveImageSync(android.media.Image image, java.io.File file) A utility method to synchronously save an image file.
void	setCaptureResultListener(CaptureResultListener listener) Registers a listener to be updated whenever Camera3 gets a result from the camera.
void	startCaptureSession(java.lang.String cameraId, PreviewHandler previewHandler, java.util.List<StillCaptureHandler> stillCaptureSessions)
void	startCaptureSession(java.lang.String cameraId, PreviewHandler previewHandler, java.util.List<StillCaptureHandler> stillCaptureSessions, java.util.List<VideoCaptureHandler> videoCaptureHandlers)
void	startCaptureSession(java.lang.String cameraId, PreviewHandler previewHandler, java.util.List<StillCaptureHandler> stillCaptureHandlers, java.util.List<VideoCaptureHandler> videoCaptureHandlers, java.lang.Runnable onSessionStarted) Starts a new session.
void	startVideoCapture(VideoCaptureHandler handler, java.io.File outputFile, VideoCaptureStartedCallback callback) Asyncronously requests to start capturing video
void	stopVideoCapture(VideoCaptureHandler handler) Stops video recording.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PRECAPTURE_CONFIG_TRIGGER_AUTO_EXPOSE

public static final CaptureRequestConfiguration PRECAPTURE_CONFIG_TRIGGER_AUTO_EXPOSE

PRECAPTURE_CONFIG_NONE

public static final CaptureRequestConfiguration PRECAPTURE_CONFIG_NONE

CAPTURE_CONFIG_DEFAULT

public static final CaptureRequestConfiguration CAPTURE_CONFIG_DEFAULT

ERROR_HANDLER_DEFAULT

public static final ErrorHandler ERROR_HANDLER_DEFAULT

Constructor Detail

Camera3

public Camera3(@NonNull
               android.content.Context context,
               @Nullable
               ErrorHandler errorHandler)

Creates a new Camera3 manager instance. Only one such manager should have to exist per Activity. Many different preview sessions, capture sessions, and capture requests can exist for one Camera3 object.

Parameters:

context - The context from which to access the camera. Should usually just be the current activity

errorHandler - An ErrorHandler to handle any errors that arise over the lifetime

Method Detail

startCaptureSession

public void startCaptureSession(@NonNull
                                java.lang.String cameraId,
                                @Nullable
                                PreviewHandler previewHandler,
                                @Nullable
                                java.util.List<StillCaptureHandler> stillCaptureSessions)

See Also:

startCaptureSession(String, PreviewHandler, List, List, Runnable)

startCaptureSession

public void startCaptureSession(@NonNull
                                java.lang.String cameraId,
                                @Nullable
                                PreviewHandler previewHandler,
                                @Nullable
                                java.util.List<StillCaptureHandler> stillCaptureSessions,
                                @Nullable
                                java.util.List<VideoCaptureHandler> videoCaptureHandlers)

See Also:

startCaptureSession(String, PreviewHandler, List, List, Runnable)

startCaptureSession

public void startCaptureSession(@NonNull
                                java.lang.String cameraId,
                                @Nullable
                                PreviewHandler previewHandler,
                                @Nullable
                                java.util.List<StillCaptureHandler> stillCaptureHandlers,
                                @Nullable
                                java.util.List<VideoCaptureHandler> videoCaptureHandlers,
                                @Nullable
                                java.lang.Runnable onSessionStarted)

Starts a new session. Only one session can be open at a time.

Parameters:

cameraId - which camera to use (from getAvailableCameras()).

previewHandler - an object representing the configuration for the camera preview, or null to not show a preview (see PreviewHandler).

stillCaptureHandlers - a list of zero or more StillCaptureHandler's, or null if no still images will be captured. Usually only one is required.

videoCaptureHandlers - a list of zero or more VideoCaptureHandler's, or null if no video will be recorded. Usually a maximum of one is required.

onSessionStarted - an optional callback that will be called to notify the user when the camera has been opened and the capture session has been started.

See Also:

PreviewHandler, StillCaptureHandler, VideoCaptureHandler

resume

public void resume()

See Also:

resume(Runnable)

resume

public void resume(@Nullable
                   java.lang.Runnable onSessionRestarted)

Resumes the capture session established by the last call to startCaptureSession(String, PreviewHandler, List)

If you're not sure if startCaptureSession(String, PreviewHandler, List) has been called already or not, you can check with captureConfigured()

Parameters:

onSessionRestarted - an optional callback that will be called to notify the user when the camera has been opened and the capture session has been restarted.

pause

public void pause()

Stops background threads and frees the camera.

pause must be called in Activity.onPause() form the activity that started the session. Otherwise, the app could close without relinquishing control of the camera.

setCaptureResultListener

public void setCaptureResultListener(@Nullable
                                     CaptureResultListener listener)

Registers a listener to be updated whenever Camera3 gets a result from the camera. This is useful for keeping track of what state the camera is in (e.g. if you want to play a sound when the capture is completed). Note: this is NOT the way you receive the result of the capture (i.e. an image). For that, use the OnImageAvailableListener in StillCaptureHandler.StillCaptureHandler(int, Size, OnImageAvailableListener)

Parameters:

listener - the listener to register or null to stop listening

startVideoCapture

public void startVideoCapture(@NonNull
                              VideoCaptureHandler handler,
                              @Nullable
                              java.io.File outputFile,
                              @Nullable
                              VideoCaptureStartedCallback callback)

Asyncronously requests to start capturing video

Parameters:

handler - the handler responsible for configuring and writing the video

outputFile - the file where the video will be saved, or null to write to a temp file

callback - a callback function to be called when the video capture has been started

stopVideoCapture

public void stopVideoCapture(@NonNull
                             VideoCaptureHandler handler)

Stops video recording. Video recording must have already started.

Note: the starting video recording is asyncronous so if you stop immediately after you start this method may cause an IllegalStateException

Parameters:

handler - the handler that is currently recording video

captureImage

public void captureImage(@NonNull
                         StillCaptureHandler handler,
                         @Nullable
                         CaptureRequestConfiguration precapture,
                         @NonNull
                         CaptureRequestConfiguration capture)

Starts the process of capturing a still image from the camera. Should be called after calling startCaptureSession(String, PreviewHandler, List)

Parameters:

handler - the StillCaptureHandler which will be responsible for processing the image

precapture - the precapture configuration. Use PRECAPTURE_CONFIG_TRIGGER_AUTO_EXPOSE to trigger auto focus prior to the image capture or use PRECAPTURE_CONFIG_NONE to skip precapture (and use the preview focus). This will speed up the capture process.

capture - the configuration for the actual image capture (on top of the defaults). Use CAPTURE_CONFIG_DEFAULT if you don't want to change the default configuration at all.

getErrorHandler

@Contract(pure=true)
public ErrorHandler getErrorHandler()

captureConfigured

@Contract(pure=true)
public boolean captureConfigured()

It is only safe to call resume() if you have already configured a capture session with startCaptureSession(String, PreviewHandler, List, List, Runnable). This method allows you to check that status.

Returns:

true if this instance of camera3 is configured with a capture session

isStarted

@Contract(pure=true)
public boolean isStarted()

Images can only be captured between calling resume() or startCaptureSession(String, PreviewHandler, List, List, Runnable) and calling pause(). This method allows you to check whether the camera can receive requests. If this is false, you can call resume().

Returns:

true if the camera can receive requests

requestsInQueue

@Contract(pure=true)
public boolean requestsInQueue()

Check if there are any enqueued requests that have not yet been resolved

Returns:

true if the request queue is not empty.

getAvailableCameras

public java.util.List<java.lang.String> getAvailableCameras()
                                                     throws android.hardware.camera2.CameraAccessException

Throws:

android.hardware.camera2.CameraAccessException

getCameraInfo

@Nullable
public android.hardware.camera2.CameraCharacteristics getCameraInfo(java.lang.String cameraId)
                                                                        throws android.hardware.camera2.CameraAccessException

Throws:

android.hardware.camera2.CameraAccessException

getAvailableImageSizes

@NonNull
public java.util.List<android.util.Size> getAvailableImageSizes(@NonNull
                                                                          java.lang.String cameraId,
                                                                          int format)

Get all supported image sizes for the given image format and camera

Parameters:

cameraId - the id of the camera form getAvailableCameras()

format - one of ImageFormat

Returns:

an unmodifiable Collection of all the supported sizes

getLargestAvailableImageSize

@Nullable
public android.util.Size getLargestAvailableImageSize(java.lang.String cameraId,
                                                                 int imageFormat)

Gets the largest image dimensions (by area) that the given camera is able to take in the given format

Parameters:

cameraId - the id of the camera form getAvailableCameras()

imageFormat - one of ImageFormat

Returns:

the largest Size if one exists or null if the camera does not offer any sizes for the given format

See Also:

getAvailableImageSizes(String, int)

getAvailableVideoSizes

@NonNull
public java.util.Collection<android.util.Size> getAvailableVideoSizes(@NonNull
                                                                                java.lang.String cameraId)

TODO doc TODO BUG sometimes some of these sizes don't actually work - lead to surface abandoned error

Parameters:

cameraId - the id of the camera form getAvailableCameras()

Returns:

getDefaultVideoSize

public android.util.Size getDefaultVideoSize(@NonNull
                                             java.lang.String cameraId)

Get a recommended video size at a reasonable aspect ratio and size. Chooses form getAvailableVideoSizes(String)

Parameters:

cameraId - the id of the camera form getAvailableCameras()

Returns:

the best available video size or null if the camera does not support any video sizes

saveImageAsync

public void saveImageAsync(android.media.Image image,
                           java.io.File file)

A utility method to asynchronously save an image file. The image will be closed once it is saved.

The caller must obtain permission to write to external storage (if necessary) before calling this method.

Parameters:

image - the image to save

file - the file to write to

See Also:

saveImageSync(Image, File)

saveImageSync

public void saveImageSync(android.media.Image image,
                          java.io.File file)

A utility method to synchronously save an image file. The image will not be closed by this method; it must be closed by the user after this function returns

Parameters:

image - the image to save

file - the file to write to

hasCameraPermission

public boolean hasCameraPermission()

Checks if the app has permission to access the camera

Returns:

true if you can capture images

See Also:

Manifest.permission.CAMERA

hasMicrophonePermission

public boolean hasMicrophonePermission()

Checks if the app has permission to access the microphone

Returns:

true if you can record audio

See Also:

Manifest.permission.RECORD_AUDO

hasWritePermission

public boolean hasWritePermission()

Checks if the app has permission to write to the file system.

Returns:

true if you can write files

See Also:

Manifest.permission.WRITE_EXTERNAL_STORAGE