/* * 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. */ /** * @addtogroup Camera * @{ */ /** * @file NdkCameraManager.h */ /* * This file defines an NDK API. * Do not remove methods. * Do not change method signatures. * Do not change the value of constants. * Do not change the size of any of the classes defined in here. * Do not reference types that are not part of the NDK. * Do not #include files that aren't part of the NDK. */ #ifndef _NDK_CAMERA_MANAGER_H #define _NDK_CAMERA_MANAGER_H #include #include "NdkCameraError.h" #include "NdkCameraMetadata.h" #include "NdkCameraDevice.h" __BEGIN_DECLS #if __ANDROID_API__ >= 24 /** * 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 ACameraManager instance. * *

The ACameraManager is responsible for * detecting, characterizing, and connecting to {@link ACameraDevice}s.

* *

The caller must call {@link ACameraManager_delete} to free the resources once it is done * using the ACameraManager instance.

* * @return a {@link ACameraManager} instance. * */ ACameraManager* ACameraManager_create(); /** *

Delete the {@link ACameraManager} instance and free its resources.

* * @param manager the {@link ACameraManager} instance to be deleted. */ void ACameraManager_delete(ACameraManager* manager); /// Struct to hold list of camera devices typedef struct ACameraIdList { int numCameras; ///< Number of connected camera devices const char** cameraIds; ///< list of identifier of connected camera devices } ACameraIdList; /** * Create a list of currently connected camera devices, including * cameras that may be in use by other camera API clients. * *

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.

* *

ACameraManager_getCameraIdList will allocate and return an {@link ACameraIdList}. * The caller must call {@link ACameraManager_deleteCameraIdList} to free the memory

* * @param manager the {@link ACameraManager} of interest * @param cameraIdList the output {@link ACameraIdList} will be filled in here if the method call * succeeds. * * @return */ camera_status_t ACameraManager_getCameraIdList(ACameraManager* manager, /*out*/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); /** * 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. * *

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.

* * @see ACameraManager_registerAvailabilityCallback */ typedef struct ACameraManager_AvailabilityListener { /// 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 camera availability callbacks. * *

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.

* *

The callbacks will be called on a dedicated thread shared among all ACameraManager * instances.

* *

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.

* * @param manager the {@link ACameraManager} of interest. * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be registered. * * @return */ camera_status_t ACameraManager_registerAvailabilityCallback( ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback); /** * Unregister camera availability callbacks. * *

Removing a callback that isn't registered has no effect.

* * @param manager the {@link ACameraManager} of interest. * @param callback the {@link ACameraManager_AvailabilityCallbacks} to be unregistered. * * @return */ camera_status_t ACameraManager_unregisterAvailabilityCallback( ACameraManager* manager, const ACameraManager_AvailabilityCallbacks* callback); /** * Query the capabilities of a camera device. These capabilities are * immutable for a given camera. * *

See {@link ACameraMetadata} document and {@link NdkCameraMetadataTags.h} for more details.

* *

The caller must call {@link ACameraMetadata_free} to free the memory of the output * characteristics.

* * @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 */ camera_status_t ACameraManager_getCameraCharacteristics( ACameraManager* manager, const char* cameraId, /*out*/ACameraMetadata** characteristics); /** * Open a connection to a camera with the given ID. The opened camera device will be * returned in the `device` parameter. * *

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.

* *

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.

* *

Once the camera is successfully opened,the ACameraDevice can then be set up * for operation by calling {@link ACameraDevice_createCaptureSession} and * {@link ACameraDevice_createCaptureRequest}.

* *

If the camera becomes disconnected after this function call returns, * {@link ACameraDevice_stateCallbacks#onDisconnected} with a * ACameraDevice in the disconnected state will be called.

* *

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.

* * @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 */ camera_status_t ACameraManager_openCamera( ACameraManager* manager, const char* cameraId, ACameraDevice_StateCallbacks* callback, /*out*/ACameraDevice** device); #endif /* __ANDROID_API__ >= 24 */ __END_DECLS #endif /* _NDK_CAMERA_MANAGER_H */ /** @} */