Retrieve the native orientation of the camera relative to the default orientation of the device.
camera_error_t camera_get_native_orientation(camera_handle_t handle, uint32_t *orientation)
The handle returned by a call to the camera_open() function
A pointer to an uint32 value that is populated with the native orientation expressed in degrees clockwise.
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-screen.
This is similar to taking a photo on a film which has been re-oriented to take a portrait(tall) rather than a landscape(wide) photograph. The film is still landscape(wide), and when printed, these photographs are output 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.
It is important to understand that even though the camera hardware may be physically installed with a non-zero orientation, this 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_photo_vf_rotations() function reports that 0, 90, 180, 270 are supported capture rotation angles. The user configures the photo viewfinder using camera_set_photovf_property() and specifies a value of 0 for CAMERA_IMGPROP_ROTATION to receive upright image buffers. In this scenario, the API will internally translate 0 to a physical rotation which is relative to the camera by adding the orientation (90) and yielding 90. This capability 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_photo_vf_rotations() reports that 270 is the only supported capture rotation angle. This could be the case on a device which does not support capture rotation. The user has no choice but to configure the photo viewfinder using a value of 270 for CAMERA_IMGPROP_ROTATION 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. Note that this is consistent with the fact that this particular physical camera does not support capture rotation. Since we 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 user must rotate this buffer by 90 degrees (the native orientation) prior to being displayed on the screen.
CAMERA_OK when the function successfully completes, otherwise another camera_error_t value that provides the reason that the call failed.