Merge "CameraNDK: add NDK API documents" into nyc-dev (7a967c72) · Commits · e / os / android_frameworks_av

camera/ndk/impl/ACameraManager.cpp

+31 −1

Original line number	Diff line number	Diff line
		@@ -471,8 +471,38 @@ ACameraManager::openCamera(

		if (!serviceRet.isOk()) {
		ALOGE("%s: connect camera device failed: %s", __FUNCTION__, serviceRet.toString8().string());
		// Convert serviceRet to camera_status_t
		switch(serviceRet.serviceSpecificErrorCode()) {
		case hardware::ICameraService::ERROR_DISCONNECTED:
		ret = ACAMERA_ERROR_CAMERA_DISCONNECTED;
		break;
		case hardware::ICameraService::ERROR_CAMERA_IN_USE:
		ret = ACAMERA_ERROR_CAMERA_IN_USE;
		break;
		case hardware::ICameraService::ERROR_MAX_CAMERAS_IN_USE:
		ret = ACAMERA_ERROR_MAX_CAMERA_IN_USE;
		break;
		case hardware::ICameraService::ERROR_ILLEGAL_ARGUMENT:
		ret = ACAMERA_ERROR_INVALID_PARAMETER;
		break;
		case hardware::ICameraService::ERROR_DEPRECATED_HAL:
		// Should not reach here since we filtered legacy HALs earlier
		ret = ACAMERA_ERROR_INVALID_PARAMETER;
		break;
		case hardware::ICameraService::ERROR_DISABLED:
		ret = ACAMERA_ERROR_CAMERA_DISABLED;
		break;
		case hardware::ICameraService::ERROR_PERMISSION_DENIED:
		ret = ACAMERA_ERROR_PERMISSION_DENIED;
		break;
		case hardware::ICameraService::ERROR_INVALID_OPERATION:
		default:
		ret = ACAMERA_ERROR_UNKNOWN;
		break;
		}

		delete device;
		return ACAMERA_ERROR_CAMERA_DISCONNECTED;
		return ret;
		}
		if (deviceRemote == nullptr) {
		ALOGE("%s: connect camera device failed! remote device is null", __FUNCTION__);

include/camera/ndk/NdkCameraCaptureSession.h

+465 −17

File changed.

Preview size limit exceeded, changes collapsed.

include/camera/ndk/NdkCameraDevice.h

+586 −31

File changed.

Preview size limit exceeded, changes collapsed.

include/camera/ndk/NdkCameraError.h

+14 −0

Original line number	Diff line number	Diff line
		@@ -14,6 +14,14 @@
		* limitations under the License.
		*/

		/**
		* @addtogroup Camera
		* @{
		*/

		/**
		* @file NdkCameraError.h
		*/

		/*
		* This file defines an NDK API.
		@@ -52,6 +60,10 @@ typedef enum {
		ACAMERA_ERROR_INVALID_OPERATION = ACAMERA_ERROR_BASE - 13,
		ACAMERA_ERROR_TIMEOUT = ACAMERA_ERROR_BASE - 14,
		ACAMERA_ERROR_STREAM_CONFIGURE_FAIL = ACAMERA_ERROR_BASE - 15,
		ACAMERA_ERROR_CAMERA_IN_USE = ACAMERA_ERROR_BASE - 16,
		ACAMERA_ERROR_MAX_CAMERA_IN_USE = ACAMERA_ERROR_BASE - 17,
		ACAMERA_ERROR_CAMERA_DISABLED = ACAMERA_ERROR_BASE - 18,
		ACAMERA_ERROR_PERMISSION_DENIED = ACAMERA_ERROR_BASE - 19,
		} camera_status_t;


		@@ -60,3 +72,5 @@ typedef enum {
		#endif

		#endif // _NDK_CAMERA_ERROR_H

		/** @} */

include/camera/ndk/NdkCameraManager.h

+199 −24

Original line number	Diff line number	Diff line
		@@ -14,6 +14,15 @@
		* limitations under the License.
		*/

		/**
		* @addtogroup Camera
		* @{
		*/

		/**
		* @file NdkCameraManager.h
		*/

		/*
		* This file defines an NDK API.
		* Do not remove methods.
		@@ -35,66 +44,230 @@
		extern "C" {
		#endif

		/**
		* ACameraManager is opaque type that provides access to camera service.
		*
		* A pointer can be obtained using {@link ACameraManager_create} method.
		*/
		typedef struct ACameraManager ACameraManager;

		/**
		* Create CameraManager instance.
		* The caller must call ACameraManager_delete to free the resources
		* Create ACameraManager instance.
		*
		* <p>The ACameraManager is responsible for
		* detecting, characterizing, and connecting to {@link ACameraDevice}s.</p>
		*
		* <p>The caller must call {@link ACameraManager_delete} to free the resources once it is done
		* using the ACameraManager instance.</p>
		*
		* @return a {@link ACameraManager} instance.
		*
		*/
		ACameraManager* ACameraManager_create();

		/**
		* delete the ACameraManager and free its resources
		* <p>Delete the {@link ACameraManager} instance and free its resources. </p>
		*
		* @param manager the {@link ACameraManager} instance to be deleted.
		*/
		void ACameraManager_delete(ACameraManager*);
		void ACameraManager_delete(ACameraManager* manager);

		// Struct to hold list of camera devices
		/// Struct to hold list of camera devices
		typedef struct ACameraIdList {
		int numCameras;
		const char** cameraIds;
		int numCameras; ///< Number of connected camera devices
		const char** cameraIds; ///< list of identifier of connected camera devices
		} ACameraIdList;

		/**
		* Create/delete a list of camera devices.
		* ACameraManager_getCameraIdList will allocate and return an ACameraIdList.
		* The caller must call ACameraManager_deleteCameraIdList to free the memory
		* Create a list of currently connected camera devices, including
		* cameras that may be in use by other camera API clients.
		*
		* <p>Non-removable cameras use integers starting at 0 for their
		* identifiers, while removable cameras have a unique identifier for each
		* individual device, even if they are the same model.</p>
		*
		* <p>ACameraManager_getCameraIdList will allocate and return an {@link ACameraIdList}.
		* The caller must call {@link ACameraManager_deleteCameraIdList} to free the memory</p>
		*
		* @param manager the {@link ACameraManager} of interest
		* @param cameraIdList the output {@link ACameraIdList} will be filled in here if the method call
		* succeeds.
		*
		* @return <ul>
		* <li>{@link ACAMERA_OK} if the method call succeeds.</li>
		* <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or cameraIdList is NULL.</li>
		* <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li>
		* <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li></ul>
		*/
		camera_status_t ACameraManager_getCameraIdList(ACameraManager*,
		camera_status_t ACameraManager_getCameraIdList(ACameraManager* manager,
		/out/ACameraIdList** cameraIdList);
		void ACameraManager_deleteCameraIdList(ACameraIdList* cameraIdList);

		/**
		* Delete a list of camera devices allocated via {@link ACameraManager_getCameraIdList}.
		*
		* @param cameraIdList the {@link ACameraIdList} to be deleted.
		*/
		void ACameraManager_deleteCameraIdList(ACameraIdList* cameraIdList);

		// Struct to hold camera availability callbacks
		/**
		* Definition of camera availability callbacks.
		*
		* @param context The optional application context provided by user in
		* {@link ACameraManager_AvailabilityCallbacks}.
		* @param cameraId The ID of the camera device whose availability is changing. The memory of this
		* argument is owned by camera framework and will become invalid immediately after
		* this callback returns.
		*/
		typedef void (ACameraManager_AvailabilityCallback)(void context, const char* cameraId);

		/**
		* A listener for camera devices becoming available or unavailable to open.
		*
		* <p>Cameras become available when they are no longer in use, or when a new
		* removable camera is connected. They become unavailable when some
		* application or service starts using a camera, or when a removable camera
		* is disconnected.</p>
		*
		* @see ACameraManager_registerAvailabilityCallback
		*/
		typedef struct ACameraManager_AvailabilityListener {
		void* context; // optional application context.
		/// Optional application context.
		void* context;
		/// Called when a camera becomes available
		ACameraManager_AvailabilityCallback onCameraAvailable;
		/// Called when a camera becomes unavailable
		ACameraManager_AvailabilityCallback onCameraUnavailable;
		} ACameraManager_AvailabilityCallbacks;

		/**
		* register/unregister camera availability callbacks
		* Register camera availability callbacks.
		*
		* <p>onCameraUnavailable will be called whenever a camera device is opened by any camera API client.
		* Other camera API clients may still be able to open such a camera device, evicting the existing
		* client if they have higher priority than the existing client of a camera device.
		* See {@link ACameraManager_openCamera} for more details.</p>
		*
		* <p>The callbacks will be called on a dedicated thread shared among all ACameraManager
		* instances.</p>
		*
		* <p>Since this callback will be registered with the camera service, remember to unregister it
		* once it is no longer needed; otherwise the callback will continue to receive events
		* indefinitely and it may prevent other resources from being released. Specifically, the
		* callbacks will be invoked independently of the general activity lifecycle and independently
		* of the state of individual ACameraManager instances.</p>
		*
		* @param manager the {@link ACameraManager} of interest.
		* @param callback the {@link ACameraManager_AvailabilityCallbacks} to be registered.
		*
		* @return <ul>
		* <li>{@link ACAMERA_OK} if the method call succeeds.</li>
		* <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager or callback is NULL, or
		* {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or
		* {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul>
		*/
		camera_status_t ACameraManager_registerAvailabilityCallback(
		ACameraManager, const ACameraManager_AvailabilityCallbacks callback);
		ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback);

		/**
		* Unregister camera availability callbacks.
		*
		* <p>Removing a callback that isn't registered has no effect.</p>
		*
		* @param manager the {@link ACameraManager} of interest.
		* @param callback the {@link ACameraManager_AvailabilityCallbacks} to be unregistered.
		*
		* @return <ul>
		* <li>{@link ACAMERA_OK} if the method call succeeds.</li>
		* <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if callback,
		* {ACameraManager_AvailabilityCallbacks#onCameraAvailable} or
		* {ACameraManager_AvailabilityCallbacks#onCameraUnavailable} is NULL.</li></ul>
		*/
		camera_status_t ACameraManager_unregisterAvailabilityCallback(
		ACameraManager, const ACameraManager_AvailabilityCallbacks callback);
		ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback);

		/**
		* Query the characteristics of a camera.
		* The caller must call ACameraMetadata_free to free the memory of the output characteristics.
		* Query the capabilities of a camera device. These capabilities are
		* immutable for a given camera.
		*
		* <p>See {@link ACameraMetadata} document and {@link NdkCameraMetadataTags.h} for more details.</p>
		*
		* <p>The caller must call {@link ACameraMetadata_free} to free the memory of the output
		* characteristics.</p>
		*
		* @param manager the {@link ACameraManager} of interest.
		* @param cameraId the ID string of the camera device of interest.
		* @param characteristics the output {@link ACameraMetadata} will be filled here if the method call
		* succeeeds.
		*
		* @return <ul>
		* <li>{@link ACAMERA_OK} if the method call succeeds.</li>
		* <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, or characteristics
		* is NULL, or cameraId does not match any camera devices connected.</li>
		* <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li>
		* <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li>
		* <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
		*/
		camera_status_t ACameraManager_getCameraCharacteristics(
		ACameraManager, const char cameraId,
		ACameraManager* manager, const char* cameraId,
		/out/ACameraMetadata** characteristics);

		/**
		* Open a camera device synchronously.
		* The opened camera device will be returned in
		* Open a connection to a camera with the given ID. The opened camera device will be
		* returned in the `device` parameter.
		*
		* <p>Use {@link ACameraManager_getCameraIdList} to get the list of available camera
		* devices. Note that even if an id is listed, open may fail if the device
		* is disconnected between the calls to {@link ACameraManager_getCameraIdList} and
		* {@link ACameraManager_openCamera}, or if a higher-priority camera API client begins using the
		* camera device.</p>
		*
		* <p>Devices for which the
		* {@link ACameraManager_AvailabilityCallbacks#onCameraUnavailable} callback has been called due to
		* the device being in use by a lower-priority, background camera API client can still potentially
		* be opened by calling this method when the calling camera API client has a higher priority
		* than the current camera API client using this device. In general, if the top, foreground
		* activity is running within your application process, your process will be given the highest
		* priority when accessing the camera, and this method will succeed even if the camera device is
		* in use by another camera API client. Any lower-priority application that loses control of the
		* camera in this way will receive an
		* {@link ACameraDevice_stateCallbacks#onDisconnected} callback.</p>
		*
		* <p>Once the camera is successfully opened,the ACameraDevice can then be set up
		* for operation by calling {@link ACameraDevice_createCaptureSession} and
		* {@link ACameraDevice_createCaptureRequest}.</p>
		*
		* <p>If the camera becomes disconnected after this function call returns,
		* {@link ACameraDevice_stateCallbacks#onDisconnected} with a
		* ACameraDevice in the disconnected state will be called.</p>
		*
		* <p>If the camera runs into error after this function call returns,
		* {@link ACameraDevice_stateCallbacks#onError} with a
		* ACameraDevice in the error state will be called.</p>
		*
		* @param manager the {@link ACameraManager} of interest.
		* @param cameraId the ID string of the camera device to be opened.
		* @param callback the {@link ACameraDevice_StateCallbacks} associated with the opened camera device.
		* @param device the opened {@link ACameraDevice} will be filled here if the method call succeeds.
		*
		* @return <ul>
		* <li>{@link ACAMERA_OK} if the method call succeeds.</li>
		* <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if manager, cameraId, callback, or device
		* is NULL, or cameraId does not match any camera devices connected.</li>
		* <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if connection to camera service fails.</li>
		* <li>{@link ACAMERA_ERROR_NOT_ENOUGH_MEMORY} if allocating memory fails.</li>
		* <li>{@link ACAMERA_ERROR_CAMERA_IN_USE} if camera device is being used by a higher
		* priority camera API client.</li>
		* <li>{@link ACAMERA_ERROR_MAX_CAMERA_IN_USE} if the system-wide limit for number of open
		* cameras or camera resources has been reached, and more camera devices cannot be
		* opened until previous instances are closed.</li>
		* <li>{@link ACAMERA_ERROR_CAMERA_DISABLED} if the camera is disabled due to a device
		* policy, and cannot be opened.</li>
		* <li>{@link ACAMERA_ERROR_PERMISSION_DENIED} if the application does not have permission
		* to open camera.</li>
		* <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
		*/
		camera_status_t ACameraManager_openCamera(
		ACameraManager, const char cameraId,
		ACameraManager* manager, const char* cameraId,
		ACameraDevice_StateCallbacks* callback,
		/out/ACameraDevice** device);

		@@ -103,3 +276,5 @@ camera_status_t ACameraManager_openCamera(
		#endif

		#endif //_NDK_CAMERA_MANAGER_H

		/** @} */