Vuforia Engine 5 merges the digital eyewear APIs, which had been in Beta for Vuforia Engine 4, into the public production APIs for the Vuforia Engine platform. Support for video see-through digital eyewear devices is enabled as part of the Mobile SDK, while optical see-through devices will still require a Digital Eyewear SDK license. This is because of the unique requirements of optical see-through devices.

This article describes a few changes to the Vuforia APIs that have been introduced with Vuforia Engine 5. These primarily address additions to the digital eyewear APIs along with a change to the Cloud Recognition updateSearchResults method.

Also See:
How To Migrate Your Existing Apps

Unity Refactoring

The Unity APIs and the project structure for the Vuforia Unity extension and samples have been refactored to harmonize their references with those of the current Vuforia Engine platform and to simplify the folder hierarchy in Unity.

Changes:

Extension and Samples
The Qualcomm Augmented Reality folder has been renamed to Vuforia?

API Changes

Updates to the Eyewear APIs

Recommended Framerate API

Vuforia Engine 5 introduces an API that enables you to dynamically adjust the framerate of your digital eyewear app in response to its runtime requirements. This API enables you to balance runtime performance against computational load and power consumption, giving you control of your app's performance characteristics. The recommended framerate API is intended for use with video see-through eyewear devices, to adjust the framerate between AR and VR modes in mixed reality apps.

See: Framerate Optimization for Mixed Reality Apps

Viewer APIs

The digital eyewear API has been extended to allow the developer to tell Vuforia Engine when their app is transitioning to a VR mode. These new APIs are used for both Cardboard and the Gear VR OVR SDK. They provide an explicit interface for setting and detecting viewers.
The first API call enables Vuforia Engine developers to tell the SDK when the device has been inserted into the Cardboard of Gear VR viewer. Once this has been accomplished, Eyewear.isDeviceDetected and Eyewear.isStereoCapable will return TRUE.

/// Inform Vuforia that the device has been inserted into a headset
    /**
     * <br><b>In order to use optimal camera settings you should call this
     * method before starting the camera. If the camera is already started
     * you should stop, deinitialize, initialize and restart it.</b><br>
     * Known identifier strings: "GearVR", "Cardboard"
     * \param id the identifier string for the headset (case insensitive)
     * \return true if successful, false if the detected device is a dedicated eyewear device.
     */
    virtual bool setHeadsetPresent(const char* id) = 0;

To return to standard Vuforia Engine behavior for use outside a headset the developer may call the following new API:

/// Inform Vuforia that the device has been removed from a headset.
    /**
     * \return true if successful, false if the detected device is a dedicated eyewear device.
     */
    virtual bool setHeadsetNotPresent() = 0;

Setting clipping planes for occluded devices

Vuforia 5 provides a method for setting the near and far clipping plane distances for video see-through devices. This method will have no effect on optical see-through devices.

/// Specify the near and far planes used in the projection matrix
    /**
     * At this time these values are only used for generating the
     * projection matrix on occluded devices (video see-through).
     */
    virtual void setProjectionClippingPlanes(const CameraCalibration& cameraCalibration,
                                             float nearPlane, float farPlane) = 0;

Scene Scale API deprecated

The Eyewear.getDefaultSceneScale method has been deprecated as it is no longer necessary. This API was only applicable to video see-through devices in the Vuforia Engine 4 Beta release.

Scene scale is now calculated automatically by comparing the field-of-view (FOV) of the lenses of the viewer with that of the device camera. We have also introduced a new method to the CameraCalibration API to read the camera s FOV.

Updates to CameraCalibration class

Vuforia Engine 5 has introduced a new method for determining the field-of-view (FOV) of the device camera. This dimension is use to perform scene scale calculations for digital eyewear, but it is not exclusive to digitial eyewear devices.
The result is a Vector providing the FOV in x and y dimensions as a value in radians.

/// Returns the field of view in x- and y-direction as 2D vector.
    virtual Vec2F getFieldOfViewRads() const = 0;

Cloud Reco API Changes

New Cloud Reco Filter Mode

Vuforia Engine 5 introduces the ability to modify the filter applied to Cloud Recognition search results. This functionality is intended for diagnostic purposes only, and is not recommended for use in production apps.

The updateSearchResult method now accepts a filter setting value of either FILTER_NONE ( disable filtering ) or FILTER_CURRENTLY_TRACKED ( enable filtering for targets being tracked ). The latter is the default behavior of the TargetFinder.
By default, Cloud Reco query results are not returned for targets that are currently being tracked. If the FILTER_NONE argument is used, these results will be returned, regardless of whether the same target has already been enabled for tracking. The purpose of removing this filter is to enable developers to determine if reco event are unexpectedly occurring on the same target due to user behavior. Developers should make sure that they do not re-enable the target for tracking as this will interrupt the tracking process.

See below for the updated API:

/// Filter modes to be passed into updateSearchResults() function
    enum
    {
        FILTER_NONE = 0,///< No results are filtered, all successful queries are returned
        FILTER_CURRENTLY_TRACKED = 1  ///< Filter out targets that are currently being tracked (Most Common)
    };

/**
     *  Clears and rebuilds the list of TargetSearchResults with results found
     *  since the last call to updateSearchResults(). Returns the status code
     *  UPDATE_RESULTS_AVAILABLE if new search results have been found.
     *  By default, targets that are already enabled for tracking are not included
     *  in the list of TargetSearchResults unless the target or its associated
     *  meta data has been updated since they were last enabled for tracking.
     */
    virtual int updateSearchResults(int filter = FILTER_CURRENTLY_TRACKED) = 0;