Using a camera

To learn more about the bar-descriptor.xml file, see Using the bar-descriptor.xml file.

Libraries needed for the Camera

To use the Camera APIs in your app, you need to import the Camera libraries by adding the following line to your project's .pro file.

 LIBS += -lbbcascadesmultimedia -lbbmultimedia 

For more information on linking against libraries, see Linking against libraries.

Include camera libraries

Include the camera libraries into the appropriate C++ header file for your app.

#include <bb/cascades/multimedia/CameraSettings>
#include <bb/cascades/multimedia/Camera>
#include <bb/multimedia/SystemSound>
#include <bb/cascades/TouchEvent>

Add using statements

Adding using statements to your app's source code file is not strictly necessary, however they reduce the amount of code you need to write when declaring variables. Here are the using statements found in the C++ version of the camera sample app used in this discussion.

using namespace bb::cascades;
using namespace bb::multimedia;
using namespace bb::cascades::multimedia;

Open a camera unit

Most devices have a rear camera, however, some devices also have a front camera. These cameras are identified with the CameraUnit::Rear and CameraUnit::Front enumerations. It's always a good idea to determine which camera units are supported by the device before attempting to open one.

For more information about the enumerations that represent the camera unit types, see CameraUnit.

Find supported cameras in C++

You can use the supportedCameras() function to determine which cameras are supported. This function returns a QList containing all of the supported cameras on the device. Since the onCreationCompleted signal handler is not available in C++, you can use the following code in your app's constructor, or you can just create your own initializeCamera() function, and put the following code in there.

• Expand to see the code sample

   
  // App's constructor.
  // ...
  
  // Retrieve a list of accessible camera units.
  QList<CameraUnit::Type> list = cameraObj->supportedCameras(); 
  
  if(list.isEmpty() || list.contains(CameraUnit::None))
  {
      // Report: "No cameras are accessible."
  }
  else 
  {
      if(list.contains(CameraUnit::Rear))
      { 
          // The default camera unit is rear 
          // so no parameter is necessary. 
          cameraObj->open();
      } 
      else if (list.contains(CameraUnit::Front))
      { 
          // Open the front camera unit.
          cameraObj->open(CameraUnit::Front);
      }
      else
      {
          // Report unknown error.
      }
  }
  

Find supported cameras in QML

You can use the supportedCameras property in your QML code to determine which cameras are supported. You can use the onCreationCompleted() signal to check the supportedCameras property and open a supported camera.

You can define a property variable called supCameras to hold a QVariantList of supported cameras. Then you can use the supportedCameras property to fill the supCameras variable with a list of supported camera units. Next, you can check the first element of the supCameras list to make certain that it's not empty, and that at least one camera unit is supported, and therefore accessible to your app. Once you know that a camera unit is available, you can proceed to find a specific camera unit. You don't have to open the Rear camera unit first as the code sample shows below, you can use logic to find any camera unit you prefer, and in any order you want. Here's a QML code sample that demonstrates how to use the QVariantList to find an accessible camera unit.

• Expand to see the code sample

  Camera {
      id: camera1
      // ...
       
      // Define a property to hold the QVariantList.
      property variant supCameras;
   
      // ...
       
      // Find an accessible camera unit and open the camera.
      onCreationCompleted: {
          // Check to see if your app has access to the camera.
          supCameras = camera1.supportedCameras;
   
          if (supCameras.length == 0 || supCameras[0] == CameraUnit.None) {
              // Report: "No camera units are accessible."
          }
          else if (supCameras[0] == CameraUnit.Rear || 
                     supCameras[1] == CameraUnit.Rear) {
              camera1.open(CameraUnit.Rear);
          }
          else if (supCameras[0] == CameraUnit.Front || 
                     supCameras[1] == CameraUnit.Front) {
              camera1.open(CameraUnit.Front);
          }
          else {
              // Report unknown error.
          }
      }
       
      // ...
  } // End of Camera control.
  

Another option for finding a supported camera unit

If a camera unit is not supported, it's also not accessible to your app. When a camera unit is supported, this doesn't necessarily mean that it's also readily available, and therefore accessible to your app at that time. It may not be accessible if it's acquired, or in use by another process. However, if the camera unit is supported and available, then it's accessible to your app.

You can use the allCamerasAccessible() function (in C++), or the allCamerasAccessible property (in QML) to find an accessible camera unit.

This function returns (or property contains) a Boolean value to indicate whether your app has access to the camera or not. This function returns (or property contains) a value of true if the camera is both supported and accessible. Once your app confirms that it can access the camera, it can proceed to open a camera unit. Here's a C++ sample showing you how to use the allCamerasAccessible() function.

 
if(cameraObj->allCamerasAccessible()) 
{
    // Open the front camera unit. 
    cameraObj->open(CameraUnit::Front);
}

This function is implemented as a property in QML. Here's a QML sample to show you how to use the allCamerasAccessible property in your QML code.

onCreationCompleted: {
    // Check to see if your app has access to the camera.
    if (camera1.allCamerasAccessible) {
        // Open the rear camera.
        camera1.open(CameraUnit.Rear);
    }
}

Open the camera

You can use the open(CameraUnit::Type unit) function to open a camera. The CameraUnit::Type unit parameter is the target camera that you want to open. If you leave this parameter blank, the open() function will open the rear camera unit by default. Here's a C++ sample showing you how to use the open() function.

// Open the front camera unit.
cameraObj->open(CameraUnit::Front);

Here's a QML sample showing you how to use the open function.

// Open the front camera unit.
camera1.open(CameraUnit.Front);

Start a viewfinder

Your app can start the viewfinder with a call to the Camera object's startViewfinder() function. When the viewfinder is started, your app can take photos or record video. The Camera object allows your app to access the low-level graphics hardware on the device. This makes the viewfinder useful and efficient for previewing any image being photographed. You must define a Camera control and use it to start the viewfinder either in your QML or C++ code. The following QML code defines the Camera object and sets its objectName property so it can be accessed from C++ code.

Camera {
   id: camera1
   objectName: "myCameraObj"
}

Here's a QML sample that demonstrates how to use the startViewfinder() function when the cameraOpened() signal is emitted. This signal indicates that the camera is open. Your app shouldn't try to start the viewfinder unless the camera is open.

onCameraOpened: {
    // When the camera is open, start the viewfinder.
    camera1.startViewfinder();
}

Here's a C++ code sample that demonstrates how to use the Camera::startViewfinder() function to start the viewfinder.

void MyCamera::onCameraOpened()
{
    // ...
 
    cameraObj->startViewfinder();
}

Close the connection to the camera

When your app is finished with the camera, it must shut it down to release the resources it currently holds. Your app can shut down the camera with the following C++ function call to the camera's close() function. It's a good idea to use the close() function in your app's destructor.

MyCamera::~MyCamera()
{
    if (settings)
        delete settings;
 
    // Close the camera.
    cameraObj->close();
}

Shutting down the connection to the camera releases all of the resources that are currently being held by the camera. Therefore it's important to shut down the camera when your app has finished using it, or when you want to switch to another camera unit.

Using your app's destructor to close the camera gives you a good opportunity to do all of the necessary clean-up for your app before it closes.