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.
ARControllerand also the following inner classes:
UpViewParams, UpViewTransitionParams, and DownViewParams
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 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 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
HeadingFilterParams, PitchFilterParams, and ZoomFilterParams
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 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
ARControllerto 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
ARControllerto 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
ARControllerso 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:
ARControlleris 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.
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
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 for the Camera view-entered event. This event is triggered just before the camera frame is displayed.|
| ||Listener for the Camera view-exited event. This event is triggered just after the camera frame is exited.|
| ||Listener for compass calibration changed event. This event is triggered by the system when the compass calibration status changes.|
| ||Listener for the "Map view entered" event. This event is triggered just before the Map view is displayed.|
| ||Listener for the "Map view exited" event. This event is triggered just after the Map view is exited.|
| ||Listener for object selection events.|
| ||Listener for pan events.|
| ||Listener for pose update events.|
| ||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.|
| ||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.|
| ||Listener for the event that occurs before the frame is composited. This event occurs after the draw event.|
| ||Listener for the event that occurs after the frame is composited.|
| ||Listener for hardware and component errors related to LiveSight.|
| ||Listener for pitch changes. Allows you to override the default LiveSight pitch/zoom curve.|
| ||Listener for radar update events.|
| ||Listener for sensor calibration events.|
| ||Listener for tap events.|
| ||Listener for touch "down" events.|
| ||Listener for touch "up" events.|
OnPreDrawMapListeneris 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
removeOnXYZListener methods provided by the
Draw and Present Phases
To understand how to use
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.