Viewfinder Mode

The viewfinder mode is used to specify the main operating mode of the camera.

The viewfinder, in the context of the Camera library, is the raw data from the imaging datapath. Basically, the viewfinder is a stream of image buffers (video) that you can either show on a display, process in a stream, or both. This viewfinder shouldn't be confused with the one found in a camera.

You must always set the viewfinder mode before you do anything else with the camera. We recommend that you set the viewfinder mode before you set any configuration settings on the camera. If you don't, any previous configuration settings are lost because setting the viewfinder mode resets the camera's configuration to its default values for the viewfinder. The reason is to ensure that the camera is in a valid state for use.

When you set the viewfinder mode, it allows for the discovery of camera capabilities and the available configuration modes and settings. The viewfinder mode selection also impacts the features that are available on the camera, and the default settings for the imaging datapath.

Different cameras may support different viewfinder modes. Therefore, it's a good idea to query the modes that are supported by the camera before you set the viewfinder mode. For information about the defined viewfinder modes, see camera_vfmode_t.

For example, when you set the viewfinder mode to CAMERA_VFMODE_VIDEO, you are indicating that your application needs to get a stream of frames from the camera. In the following code snippet, we are using one configured camera that's assigned as CAMERA_UNIT_1:

camera_handle_t cameraHandle;

// Open the camera assigned as "CAMERA_UNIT_1"
err = camera_open(CAMERA_UNIT_1, CAMERA_MODE_RW | CAMERA_MODE_ROLL, &cameraHandle);
if (err != EOK) {
    printf("Failed to open the camera: err = %d\n", err);
    return err;
}

// Set the viewfinder mode for video
err = camera_set_vf_mode(cameraHandle, CAMERA_VFMODE_VIDEO);
if (err != EOK) {
     printf("Failed to set VF mode: err = %d\n", err);
     camera_close(cameraHandle);
     break;
}

You may want to later encode these frames. After you have set the viewfinder mode, all of the query API functions are available (e.g., camera_get_supported_vf_resolutions(), camera_has_feature()). You can use these functions to get lists of features and specifics supported by the camera to match your use case.

Viewfinder window

By default, the Camera library creates a viewfinder window. The viewfinder window is a child Screen window that's managed by the Sensor service. This conveniently allows you to create a parent Screen window in your application and then join the viewfinder window to your application. This simplifies the application code you need to write to work with the image buffers (because the Sensor service handles the logic of managing these buffers) and to refresh the video stream.

Depending on the requirements of your application, there are situations where you won't require this viewfinder window to be created. For example, you might want to:

encode the image buffers and write them to files
run algorithms on the image buffers
process the image buffers and manipulate them
handle posting the image buffers in your application

In these situations, when you don't require the viewfinder window, you can disable the automatic creation of it. To tell the Sensor service to not create a viewfinder window, call camera_set_vf_property() with the CAMERA_IMGPROP_CREATEWINDOW property set to 0 (zero):

camera_set_vf_property(cameraHandle, CAMERA_IMGPROP_CREATEWINDOW, 0);

After you set the viewfinder mode, you can modify the viewfinder settings using camera_set_vf_property(), configure the camera, and then start the viewfinder using camera_start_viewfinder(). When you are finished using the camera, you can call camera_stop_viewfinder() to stop the viewfinder.

If you want to change the video mode, you must first stop the viewfinder, then call camera_set_vf_mode() to change its mode. Keep in mind that any previous settings on the camera are lost when you do this. For that reason, you may want to reapply any sensor configuration settings before you do anything else. To start getting image buffers again, you must restart the viewfinder.