Documentation

Hardware control

The Hardware control example series will show how you can use the hardware API. The example is split into four different parts which illustrate the different features of the API, both native and Javascript. At the end of the series, you will have a complete overview of the API.

Camera Switching

The third part uses the same POIs, but starts the augmented reality view with the default configuration.

The user can then switch between front facing and rear camera by pressing the button "Switch Camera". The button is defined in index.html and calls World.switchCam() on click:

    /*
     * Switch between front and back camera
     */
    switchCam: function switchCamFn() {
        if (AR.hardware.camera.position == AR.CONST.CAMERA_POSITION.FRONT) {
            AR.hardware.camera.position = AR.CONST.CAMERA_POSITION.BACK
        } else {
            AR.hardware.camera.position = AR.CONST.CAMERA_POSITION.FRONT            
        }
    }
view source code on GitHub

The Marker constructor function also sets the mirrored flag of the marker title and description. See marker.js for details about how this is implemented: the odd-numbered POIs have mirrored titles, and even-numbered POIs have mirrored descriptions.

This flag has no effect when viewing the AR scene through the rear camera. When using the front facing camera, all objects are mirrored like the camera image, except Label and HTMLDrawable object. By setting the mirrored flag you can override the default behaviour.

Advanced Features

The fourth example shows how to use the other functions of the hardware access API.

By pressing the button "Camera Info" the user can obtain information about which hardware feature are available on the device camera:

    // display camera info panel
    showCamInfo: function showCamInfoFn() {
        // update panel values
        var features = AR.hardware.camera.features;

        $("#camera-focus-modes").html(features.focusModes.join());
        $("#camera-positions").html(features.positions.join());
        $("#camera-zoom-max").html(Math.round(features.zoomRange.max));

        // show panel
        $("#panel-caminfo").panel("open", 123);
    }
view source code on GitHub

When the user presses the button "Camera Control" another panel is shown, with more controls available to the user.

  • Zoom initially set to 1: the zoom factor ranges between 1 and a maximum value, which depends on the device capabilities.
  • Autofocus: when checked, the continuous autofocus function of the camera is active. By disabling it, the camera locks the focus on the currently framed object.
  • Manual Focus Distance: initially set to 0: the manual focus distance ranges between 0.0 and 1.0.
  • Flashlight: by checking this box, the user can turn the flashlight on and off.

To use the camera zoom, you can read or change the value of AR.hardware.camera.zoom:

    // updates values shown in "control panel"
    updateRangeValues: function updateRangeValuesFn() {

        // get current slider value (0..100);
        var slider_value = $("#panel-zoom-range").val();

        // zoom level (1 up to max available)
        var maxRangeValue = Math.round((AR.hardware.camera.features.zoomRange.max - 1) * (slider_value / 100) + 1);

        // update UI labels accordingly
        $("#panel-zoom-value").html(maxRangeValue);

        AR.hardware.camera.zoom = maxRangeValue;
    },
view source code on GitHub

The value of AR.hardware.camera.focusMode represents the focusing mode of the camera and can be set to AR.CONST.CAMERA_FOCUS_MODE.CONTINUOUS or AR.CONST.CAMERA_FOCUS_MODE.ONCE.

Continuous mode is the default if the device supports it, in this mode the camera will try to refocus automatically when necessary.

By setting the focus mode to ONCE you can force the camera to refocus once on the current view. If you need to change focus you can set this value again. Each time the value ONCE is set, the camera tries to focus on the current scene again:

    // updates values shown in "control panel"
    updateFocusMode: function updateFocusModeFn() {

        // get current checkbox status
        var check_value = $("#panel-focus-auto").is(":checked");

        if (check_value) {
            AR.hardware.camera.focusMode = AR.CONST.CAMERA_FOCUS_MODE.CONTINUOUS;
        } else {
            AR.hardware.camera.focusMode = AR.CONST.CAMERA_FOCUS_MODE.ONCE;
        }
    },
view source code on GitHub

To use the manual focus distance, you can read or change the value of AR.hardware.camera.manualfocusdistance:

AR.hardware.camera.manualFocusDistance = parseInt(slider_value) / 100;

Not every device supports this feature, so you can use AR.hardware.camera.manualFocusAvailable to find out if manual focus is available. In our sample we use this to hide the slider if necessary.

if (!AR.hardware.camera.manualFocusAvailable) {
    document.getElementById("panel-focus-distance").style.display = "none";
}
view source code on GitHub

To access the flashlight, you can read or change the value of AR.hardware.camera.flashlight:

    // updates values shown in "control panel"
    updateFlashlight: function updateFlashlightFn() {

        // get current checkbox status
        var check_value = $("#panel-flashlight").is(":checked");
        AR.hardware.camera.flashlight = check_value;
    },
view source code on GitHub