Camera Features Library

Functions to take high dynamic range (HDR) photos.

This file defines functions that applications can use to take high dynamic range (HDR) photos.

HDR imaging is a process for increasing the dynamic range of a photograph. The dynamic range of a photograph is defined as the difference between the darkest and brightest areas in the image. The process involves taking multiple photographs in quick succession at different exposure levels and then compositing them for final output.

There are two ways to generate HDR photos:
  • Realtime HDR capture mode
  • Offline HDR rendering mode

Realtime HDR capture mode

Realtime HDR capture mode

In realtime HDR capture mode, the HDR session is explicitly bound to an open camera handle. This binding allows the HDR session to directly operate the camera and capture the necessary input images to produce an output HDR image. The camera must be initialized and configured for exposure bracketing mode (CAMERA_VFMODE_EV_BRACKETING) prior to using the HDR module. The following example code illustrates how to use realtime HDR capture mode:

    camera_hdr_t hdr_session = NULL;
    camera_error_t result;
    camera_handle_t camera_handle;

    // Open camera and start the viewfinder in EV bracketing mode
    // (not shown - refer to @c camera_api.h for details)

    // Create and initialize the HDR session
    result = camera_hdr_create(&hdr_session);

    // Bind the camera to the HDR session
    result = camera_hdr_bind_camera(hdr_session,
                                    camera_handle);

    // Trigger an HDR capture
    result = camera_hdr_take_photo(hdr_session,
                                   my_shutter_callback_function,
                                   NULL,   // raw callbacks are not supported
                                   my_postview_callback_function,
                                   my_image_callback_function,
                                   my_unprocessed_image_callback_function,
                                   NULL,   // raw callbacks are not supported
                                   (void*)my_arbitrary_context_arg,
                                   false);

    // clean up HDR session
    result = camera_hdr_destroy(hdr_session);
The above example code purposely omits implementation-specific details such as opening and configuring the camera, error checking, optional configuration, capability discovery, and the actual handling of output image buffers from the camera_hdr_take_photo() function.

Offline HDR rendering mode

Offline HDR rendering mode

In offline HDR rendering mode, the HDR module is explicitly given a series of input images at different exposure levels and then renders an output image. The details of how to acquire the input images is left as an implementation detail for the developer. Offline HDR rendering mode is provided to accommodate use cases where finer grained control over the capture conditions is desired. For example, an application may be designed to capture five exposure bracketed images as input and then provide the user with the option to render the final HDR image using any three of the five input images, or to render multiple HDR images for later consideration.

The following example code illustrates how to use offline HDR rendering mode:

    camera_hdr_t hdr_session = NULL;
    camera_error_t result;
    camera_buffer_t* underexposed_image;
    camera_buffer_t* normal_image;
    camera_buffer_t* overexposed_image;
    camera_buffer_t* rendered_image;

    // Acquire three images at different exposure levels (not shown)

    // Create and initialize the HDR session
    result = camera_hdr_create(&hdr_session);

    // Add the three images to the HDR session
    result = camera_hdr_add_image_to_session(hdr_session,
                                             &underexposed_image,
                                             -2.0);
    result = camera_hdr_add_image_to_session(hdr_session,
                                             &normal_image,
                                             0.0);
    result = camera_hdr_add_image_to_session(hdr_session,
                                             overexposed_image,
                                             +2.0);

    // render the HDR image
    result = camera_hdr_render(hdr_session,
                                     &rendered_image,
                                     CAMERA_HDR_RENDERTYPE_IMAGE);

    // Free the three input image buffers (not shown)

    // Save the rendered image to disk, or display on screen, etc. (not shown)

    // Free the rendered image buffer
    camera_hdr_free_buffer(rendered_image);

    // Clean up HDR session
    result = camera_hdr_destroy(hdr_session);
The above example code purposely omits implementation-specific details such as acquiring and releasing the input images, error checking, optional configuration and capability discovery.
Since:
BlackBerry 10.3.0

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus