Connect to the camera

The first thing you must do to use the Camera library is to connect to a camera that's specified in the sensor configuration.

To connect to the camera, you use camera_open(), which gives you a reference to a camera_handle_t handle. When your application successfully connects and you receive a valid handle from the Camera API, it confirms that your application can access the specified camera with the requested access mode. Each application can have multiple handles open to multiple cameras—up to 16 handles open per application.

The cameras that are available to the Sensor service are configured in the sensor configuration file. For more information about this configuration file and service, see the Sensor chapter in the Sensor Framework Services Guide.

When you call camera_open(), you must specify the following input arguments:

camera unit

To connect to the camera, you need to know its identifier, which is specified as a camera_unit_t enumerator value. This identifier tells the library which camera to access. You can use the identifiers of CAMERA_UNIT_1, CAMERA_UNIT_2, etc, which map respectively to the cameras defined in the sensor configuration file as SENSOR_UNIT_1, SENSOR_UNIT_2, etc. If you don't know what cameras are connected to your system, you can use Camera API calls to find out; for more information, see “Determine the cameras connected to your system.”

mode of access

This mode specifies what access permissions you require on the camera. Typically, your camera application requires read/write access to a camera. Only one application can have write access to a camera at any given time. Multiple applications with read-only access can query information about the camera, but can't modify its configuration. That is, they can't write to the camera roll (e.g., they can't record or encode on the camera) or start/stop the viewfinder. For this reason, ensure that you call camera_close() after your application is done with its write access to the camera, otherwise other applications won't have write access to it.

You can specify the access using one or more Camera access mode flags, which are OR'ed together.

In general, the flags control permissions to the camera and the image buffers. However, CAMERA_MODE_ROLL gives you access to the camera roll. The camera roll is the default directory where the Sensor service puts video files, which is required when you record video. The directory to use as the camera roll is specified using the -r option when you start the Sensor service. For more information, see “Understanding the camera roll.”

When camera_open() returns successfully (i.e., with CAMERA_EOK), a valid handle is provided. You must use this handle to make other Camera API calls to the specified camera. Since you have the camera open (i.e., you connected to it), you must call camera_close() whenever an error occurs when you make Camera API calls. For more information about closing the camera, see “Stop the viewfinder.”

Determine the cameras connected to your system

If you don't know what cameras are connected to your system, use camera_get_supported_cameras() to retrieve a list of the available cameras. You may need to call this function twice. The first time is to determine the proper-sized array that's required to store units for the number of available cameras. The second time you call this function, you must pass in an allocated array large enough to store all of the camera units. If you know the required array size ahead of time, it isn't necessary to call the function twice.

The following code snippet shows how to determine what cameras are connected to your system and how to connect to the first camera returned to you:

...
...
camera_unit_t unit;
camera_unit_t *supportedCameras;
uint32_t numSupported;
camera_handle_t cameraHandle;
int err;

// Get how many cameras are supported, which is returned in the reference to numSupported.
err = camera_get_supported_cameras(0, &numSupported, NULL);
if (err != CAMERA_EOK) {
    printf("Failed to get the number of supported cameras\n");
    return err;
}

// Allocate an array big enough to hold all camera units.
supportedCameras = (camera_unit_t*) malloc(sizeof(camera_unit_t) * numSupported);

// Get the list of supported cameras by calling camera_get_supported_cameras() again.
err = camera_get_supported_cameras(numSupported, &numSupported, supportedCameras);
if (err != CAMERA_EOK) {
    printf("Failed to get a list of supported cameras\n");
    free(supportedCameras);
    return err;
}

// We'll just use the first camera that we get. If there are more, we'll ignore them for now.
unit = supportedCameras[0];
free(supportedCameras);
printf("The number of cameras connected to the system: %d\n. Assigning to camera unit #%d\n",
        numSupported, unit);

err = camera_open(unit, CAMERA_MODE_RW | CAMERA_MODE_ROLL, &cameraHandle);
if (err != CAMERA_EOK) {
    printf("Failed to connect to the camera\n");
    return err;
}
printf("We got a valid camera handle\n");
...
...