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.
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 ARObject
s are changed to the unselected state. When selection is canceled, all objects are returned to the neutral state.
Other ARController Settings
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);
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. |
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.