SDK for Android Developer's Guide

Customizing LiveSight

LiveSight is highly configurable allowing developers and designers to create many different and immersive experiences. The ARController class serves as a facade for overall LiveSight functionality and contains all the methods and callbacks available for controlling and customizing LiveSight behavior.

The methods used to customize LiveSight reside in the ARController and also the following inner classes:

ARController.UpViewParams
ARController.UpViewTransitionParams
ARController.DownViewParams
ARController.IntroAnimationParams
ARController.IconParams
ARController.InfoParams
ARController.CameraParams
ARController.FilterParams
ARController.SelectedItemParams

UpViewParams, UpViewTransitionParams, and DownViewParams

UpViewParams and DownViewParams encapsulate the customizable parameters that are applicable for the Up and Down views. UpViewTransitionParams encapsulates customizable parameters that are applicable when you move up from the down view and enter the camera view.

IntroAnimationParams

IntroAnimationParams encapsulates parameters about various intro animations. Intro animation refers to the animation that is used while the app is entering LiveSight. During LiveSight entry a few transition operations happen simultaneously, and each of these can be assigned a different animation style. These customizable transition operations are: map zoom (the map zooms in towards the ground level), heading change (the current heading changes to the current device heading), position change (the current position changes to the current device position or a LiveSight-specific position), and pitch change (the pitch changes according to the 3D orientation of the device).

IconParams and InfoParams

IconParams encapsulates customizable parameters for the front, back, and down icons. In addition to setting icon sizes, you can also set how icons animate when they first appear ("pop-up"), receive a tap, or appear while transitioning from the Down to Up view ("fly"). For more information on down, front, and back icons, consult section Adding and Interacting with LiveSight Content.

InfoParams allows you to customize how Info Views animate when they first appear ("pop-up"), receive a tap, or appear while transitioning from the Down to Up view ("fly").

CameraParams

CameraParams encapsulates parameters that are related to the camera-enabled Up view. CameraParams.setSize(Size) method allows you to set the camera resolution to be used for the LiveSight camera view. Note that using a high camera resolution may cause performance degradation. The default camera resolution is 680x480.

HeadingFilterParams, PitchFilterParams, and ZoomFilterParams

HeadingFilterParams, PitchFilterParams, and ZoomFilterParams are all instances of ARController.FilterParams class. These objects encapsulate the customizable parameters for the heading, pitch, and zoom data sampling. Methods in Filter allow you to customize how data samples are read from the device sensors.

SelectedItemParams

SelectedItemParams encapsulates parameters that control behavior when an ARObject is in the selected or unselected state. For example, you can increase the size of a selected icon. By default, objects are neither in the selected or unselected state. When an ARObject is selected, all other ARObjects are changed to the unselected state. When selection is canceled, all objects are returned to the neutral state.

Other ARController Settings

In addition to the previous parameter classes, you can use methods in ARController to customize the following areas in LiveSight:

Alternative Center Location — LiveSight is not only limited to the current device location. It is possible to use the ARController to set an alternative location ("space shift") for your LiveSight experience.
Icon Display Behavior — Adjust settings related to the icon display, e.g. only showing Front items or using Down icons in the map.
Device Orientation Behavior — Set whether the Down view is updated with the device sensor orientation data.
Layout Updates — By default LiveSight icons are set to be updated dynamically according to the current device position. However, you can set ARController so that the Layout (containing the front and back icons) does not update until the device position is changed significantly past a threshold.

External Sensor Data

LiveSight also provides the ability to switch from using integrated device sensor data to one or more data feeds provided by external sources. You may need to do this when more accuracy is required for object projection results in the Up state, or when you require a distributed LiveSight solution where data from multiple sensors are provided over TCP/IP.

ARController.ExternalSensors is the entry point for using external sensor data. You can enable or disable input from one or more external sensors by using this class with the values defined in ARController.SensorType enum, with the exception of CAMERA. For example:

arController.ExternalSensors.utilize(SensorType.GPS, true);

Note: This call should only be made when ARController is stopped or paused.

After the external sensor is enabled, the integrated device sensor data is no longer used, and you must start providing sensor data into the LiveSight engine using pushData(SensorType, double, double, double, long) method. Note that the parameters are treated differently if a different SensorType is used. For more information on providing data using this method, see the API reference.

Animation Interpolators

The visual appearance of many of the LiveSight animations can be changed by using different animation interpolators. The available interpolator types include:

LINEAR - Linear interpolation
ACCELERATE - Starts slow and then accelerates
DECELERATE - Starts quick and then decelerates
ACCELERATE_DECELERATE - Starts and ends slowly but accelerates through the middle
OVERSHOOT - Flings forward and overshoots the last value, then comes back
ANTICIPATE - Starts backward, then flings forward
ANTICIPATE_OVERSHOOT - Starts forward, then flings forward and overshoots the target value, and finally goes back to the final value
BOUNCE - Rate of change 'bounces' at the end

Listeners provided by ARController

The ARController class provides a variety of listener classes that can be used to trigger event-driven code in your application. The listeners provided are:

Listener Name	Purpose
`OnCameraEnteredListener`	Listener for the Camera view-entered event. This event is triggered just before the camera frame is displayed.
`OnCameraExitedListener`	Listener for the Camera view-exited event. This event is triggered just after the camera frame is exited.
`OnCompassCalibrationChangedListener`	Listener for compass calibration changed event. This event is triggered by the system when the compass calibration status changes.
`OnMapEnteredListener`	Listener for the "Map view entered" event. This event is triggered just before the Map view is displayed.
`OnMapExitedListener`	Listener for the "Map view exited" event. This event is triggered just after the Map view is exited.
`OnObjectTappedListener`	Listener for object selection events.
`OnPanListener`	Listener for pan events.
`OnPoseListener`	Listener for pose update events.
`OnPreDrawListener`	Listener for pre-draw event. This event is triggered just before a draw is performed. This listener is useful in case a client wants to update things while in LiveSight Mode and serialize the update action with the LiveSight draw cycle. This callback is performed in both Map view and Camera view.
`OnPreDrawMapListener`	Listener for the map pre-draw event. This event is triggered just before the map is being drawn. This listener is useful in the case where the client wants to update things on the map and serialize the update action with the draw cycle.
`OnPrePresentListener`	Listener for the event that occurs before the frame is composited. This event occurs after the draw event.
`OnPostPresentListener`	Listener for the event that occurs after the frame is composited.
`OnLivesightStatusListener`	Listener for hardware and component errors related to LiveSight.
`OnPitchFunction`	Listener for pitch changes. Allows you to override the default LiveSight pitch/zoom curve.
`OnRadarUpdateListener`	Listener for radar update events.
`OnSensorCalibrationChangedListener`	Listener for sensor calibration events.
`OnTapListener`	Listener for tap events.
`OnTouchDownListener`	Listener for touch "down" events.
`OnTouchUpListener`	Listener for touch "up" events.

Note: OnPreDrawMapListener is a replacement for OnMapRenderListener.onPreDraw() callback, which is not triggered while in LiveSight Mode.

All of these Listeners are added and removed by way of their respective addOnXYZListener and removeOnXYZListener methods provided by the ARController.

Draw and Present Phases

To understand how to use OnPreDrawMapListener, OnPrePresentListener, and OnPostPresentListener, it is important to understand the order and differences between Present and Draw. The order of LiveSight phases and events is as follows:

Pre-Draw event
Draw phase
Pre-Present event
Present phase
Post-Present event

The Draw phase is the action of filling graphics buffers with the various components of the scene which are applicable for the current LiveSight View. In the Draw phase the LiveSight engine is composing different layers in a frame, such as a map and icons for the Down view, and the camera feed and icons for the Up view. This phase occurs before the Present phase, and since the Pre-Draw event is triggered before this phase, you should use the Pre-Draw event if you want, for example, for an icon to change for the next frame.

Note the absence of the Post-Draw event. If you want to do something just before presenting, use the Pre-Present event, which is the same as Post-Draw, since the Pre-Present event occurs after "Draw" but before the "Present" phase.

The Present phase refers to the composition of the buffers filled in the draw phase into the frame. In other words, this phase takes buffers and blends their contents into one buffer to be displayed. For example, this is how icons are placed on top of the camera frame. After the "Present" phase the Post-Present event is triggered.