camera_get_native_orientation()

Retrieve the native orientation of the camera relative to the default orientation of the device.

Synopsis:

#include <camera/camera_api.h>

camera_error_t camera_get_native_orientation(camera_handle_t handle,                 
                                             uint32_t *orientation)

Since:

BlackBerry 10.0.0

Arguments:

handle: The handle returned by a call to the camera_open() function

orientation: A pointer to a uint32_t value that will be updated with the native orientation of the camera expressed in degrees clockwise.

Library:

libcamapi (For the qcc command, use the -l camapi option to link against this library)

Description:

The native orientation describes the installed clockwise angular offset of the camera sensor with respect to the screen when the device is held upright. When a camera is installed with a non-zero orientation offset relative to the rest of the device, the image data output by the camera must be rotated for correct presentation on the screen.

This concept is similar to taking a photo on a film which has been reoriented to take a portrait (tall) rather than a landscape (wide) photograph. The film is still landscape, and when printed, these photographs are printed in landscape (wide) format. It is the responsibility of the viewer to hold the finished photographic print in the correct orientation in order to recreate the captured scene. The value returned by this function indicates how far clockwise the camera hardware has been oriented from the viewer, and therefore indicates how far the user must rotate the output photo buffer clock-wise in order for it to appear upright on-screen.

Note: Since the camera hardware is able to render to rotated buffers on behalf of the user on some devices, it is sufficient to use the camera_get_supported_vf_rotations() and camera_get_photo_rotations() to cover many common use cases.

It is important to understand that even though the camera hardware may be physically installed with a non-zero orientation, the Camera API internally compensates for the native orientation offset when communicating rotation angles between the user and the hardware.

The following are examples of how this function works in relation to other functions available in this API:

Scenario 1: The camera_get_native_orientation() function reports an orientation of 90 degrees, such as for a smartphone. The camera_get_supported_vf_rotations() function reports that 0, 90, 180, 270 are supported viewfinder rotation angles. The user configures the photo viewfinder using camera_set_vf_property() and specifies a value of 0 for CAMERA_IMGPROP_ROTATION to receive upright viewfinder buffers. In this scenario, the API will internally translate 0 to a physical rotation which is relative to the camera hardware by adding the orientation (90) and yielding 90. This ensures that the buffers output from The Camera API are presentable upright on-screen as-is.

Scenario 2: The camera_get_native_orientation() reports an orientation of 90 degrees, such as for a smartphone. The camera_get_supported_vf_rotations() reports that 270 is the only supported viewfinder rotation angle. This could be the case on a device which does not support capture rotation. The use has no choice but to configure the photo viewfinder using a value of 270 when setting CAMERA_IMGPROP_ROTATION using camera_set_vf_property(). The API will internally translate 270 to a physical rotation, which is relative to the camera by adding the orientation (90) and yielding 0. The buffer being rendered to is now understood to be 0-degrees offset relative to the camera hardware. Note that this is consistent with the fact that this particular physical camera does not support viewfinder buffer rotation. Since we also know that this camera has a non-zero native orientation (90), we know that rendering this buffer to the screen will result in a sideways image. The application must rotate this buffer by 90 degrees (the native orientation) prior to being displayed on the screen. You can accomplish this by using the Screen and Windowing API to adjust the SCREEN_PROPERTY_ROTATION of the viewfinder window.

For more information about viewfinder buffer rotation, see the camera_get_supported_vf_rotations(), camera_get_video_rotations(), and camera_get_photo_rotations() functions.

Returns:

CAMERA_EOK when the function successfully completes, otherwise another camera_error_t value that provides the reason that the call failed.