GvrBasePointer

This is an abstract class.

An abstract class for handling pointer based input.

Summary

This abstract class should be implemented for pointer based input, and used with the GvrPointerInputModule script.

It provides methods called on pointer interaction with in-game objects and UI, trigger events, and 'BaseInputModule' class state changes.

To have the methods called, an instance of this (implemented) class must be registered with the GvrPointerManager script in 'Start' by calling GvrPointerInputModule.OnPointerCreated.

This abstract class should be implemented by pointers doing 1 of 2 things:

  1. Responding to movement of the users head (Cardboard gaze-based-pointer).
  2. Responding to the movement of the daydream controller (Daydream 3D pointer).

Inheritance

Inherits from: MonoBehaviour, IGvrControllerInputDeviceReceiver
Direct Known Subclasses:GvrLaserPointer, GvrReticlePointer

Public types

RaycastMode{
  Camera,
  Direct,
  Hybrid
}
enum
The method by which GvrPointer perorms Raycasts.

Public attributes

overridePointerCamera
Determines the eventCamera for GvrPointerPhysicsRaycaster and GvrPointerGraphicRaycaster.
raycastMode = RaycastMode.Hybrid
Determines which raycast mode to use for this raycaster.

Properties

CameraRayIntersectionDistance
float
Gets the location where the ray from the pointer will intersect with the ray from the camera when using the Hybrid raycast mode.
ControllerInputDevice
Gets or sets the reference to the controller input device.
CurrentPointerRadius
float
Gets the current radius of the pointer.
CurrentRaycastResult
RaycastResult
Gets the current RaycastResult.
IsAvailable
bool
Gets a value indicating whether the pointer will be used for generating input events by GvrPointerInputModule.
IsPointerIntersecting
bool
Deprecated. Replaced by CurrentRaycastResult.gameObject != null.
Gets a value indicating whether the pointer raycast intersects any object.
IsTouching
bool
Gets a value indicating whether the user is currently touching the touchpad.
MaxPointerDistance
abstract float
Gets the max distance from the pointer that raycast hits will be detected.
MaxPointerEndPoint
Vector3
Gets the end point of the pointer when it is MaxPointerDistance away from the origin.
PointerCamera
Gets the camera used as the pointer.
PointerIntersection
Vector3
Deprecated. Replaced by CurrentRaycastResult.worldPosition.
Gets the pointer intersection.
PointerTransform
Transform
Gets the transform that represents this pointer.
ShouldUseExitRadiusForRaycast
bool
Gets or sets a value indicating whether the enterRadius should be used for the raycast or the exitRadius should be used.
TouchDown
bool
Gets a value indicating whether the user just started touching the touchpad.
TouchPos
Vector2
Gets the position of the current touch, if touching the touchpad.
TouchUp
bool
Gets a value indicating whether the user just stopped touching the touchpad.
TriggerDown
bool
Gets a value indicating whether the trigger was just pressed.
TriggerUp
bool
Gets a value indicating whether the trigger was just released.
Triggering
bool
Gets a value indicating whether the trigger is currently being pressed.

Public static functions

CalculateHybridRay(GvrBasePointer pointer, RaycastMode hybridMode)
Calculates the ray for the segment of the Hybrid raycast determined by the raycast mode passed in.
CalculateRay(GvrBasePointer pointer, RaycastMode mode)
Calculates the ray for a given Raycast mode.

Public functions

GetPointAlongPointer(float distance)
Vector3
Returns a point in worldspace a specified distance along the pointer.
GetPointerRadius(out float enterRadius, out float exitRadius)
virtual abstract void
Return the radius of the pointer.
GetRayForDistance(float distance)
Returns the ray used for projecting points out of the pointer for the given distance.
OnPointerClickDown()
virtual abstract void
Called when a click is initiated.
OnPointerClickUp()
virtual abstract void
Called when click is finished.
OnPointerEnter(RaycastResult raycastResult, bool isInteractive)
virtual abstract void
Called when the pointer is facing a valid GameObject.
OnPointerExit(GameObject previousObject)
virtual abstract void
Called when the pointer no longer faces an object previously intersected with a ray projected from the camera.
OnPointerHover(RaycastResult raycastResultResult, bool isInteractive)
virtual abstract void
Called every frame the user is still pointing at a valid GameObject.

Structs

GvrBasePointer.PointerRay

Represents a ray segment for a series of intersecting rays.

Public types

RaycastMode

 RaycastMode

The method by which GvrPointer perorms Raycasts.

Camera is usually ideal at long range, Direct is usually ideal at close range, and Hybrid interpolates between the two depending on range.

Properties
Camera

Camera-based raycasting.

Detects collisions for the pointer from the Camera.

Casts a ray from the camera through the target of the pointer. This is ideal for reticles that are always rendered on top. The object that is selected will always be the object that appears underneath the reticle from the perspective of the camera. This also prevents the reticle from appearing to "jump" when it starts/stops hitting an object.

Recommended for reticles that are always rendered on top such as the GvrReticlePointer prefab which is used for cardboard apps.

Note: This will prevent the user from pointing around an object to hit something that is out of sight. This isn't a problem in a typical use case.

When used with the standard daydream controller, the hit detection will not account for the laser correctly for objects that are closer to the camera than the end of the laser. In that case, it is recommended to do one of the following things:

  1. Hide the laser.
  2. Use a full-length laser pointer in Direct mode.
  3. Use the Hybrid raycast mode.

Direct

Direct raycasting.

Detects collisions for the pointer from the Controller.

Cast a ray directly from the pointer origin.

Recommended for full-length laser pointers.

Hybrid

Hybrid raycasting.

Interpolates between Camera and Direct based on distance.

Default method for casting ray.

Combines the Camera and Direct raycast modes. Uses a Direct ray up until the CameraRayIntersectionDistance, and then switches to use a Camera ray starting from the point where the two rays intersect.

Recommended for use with the standard settings of the GvrControllerPointer prefab. This is the most versatile raycast mode. Like Camera mode, this prevents the reticle appearing jumpy. Additionally, it still allows the user to target objects that are close to them by using the laser as a visual reference.

Public attributes

overridePointerCamera

Camera overridePointerCamera

Determines the eventCamera for GvrPointerPhysicsRaycaster and GvrPointerGraphicRaycaster.

Additionaly, this is used to control what camera to use when calculating the Camera ray for the Hybrid and Camera raycast modes.

raycastMode

RaycastMode raycastMode = RaycastMode.Hybrid

Determines which raycast mode to use for this raycaster.

Supports the following modes:

  • Camera - Ray is cast from the camera through the pointer.
  • Direct - Ray is cast forward from the pointer.
  • Hybrid - Begins with a Direct ray and transitions to a Camera ray.

Properties

CameraRayIntersectionDistance

float CameraRayIntersectionDistance

Gets the location where the ray from the pointer will intersect with the ray from the camera when using the Hybrid raycast mode.

The location where the ray from the pointer will intersect with the ray from the camera when using the Camera raycast mode.

ControllerInputDevice

GvrControllerInputDevice ControllerInputDevice

Gets or sets the reference to the controller input device.

The reference to the controller input device.

CurrentPointerRadius

float CurrentPointerRadius

Gets the current radius of the pointer.

Gets the exitRadius if ShouldUseExitRadiusForRaycast is true, otherwise returns the enterRadius.

The current pointer radius.

CurrentRaycastResult

RaycastResult CurrentRaycastResult

Gets the current RaycastResult.

A convenience function for fetching the object the pointer is currently hitting.

The current raycast result.

IsAvailable

bool IsAvailable

Gets a value indicating whether the pointer will be used for generating input events by GvrPointerInputModule.

Value true if the pointer will be used for generating input events by GvrPointerInputModule, false.

IsPointerIntersecting

bool IsPointerIntersecting

Gets a value indicating whether the pointer raycast intersects any object.

Deprecated. Replaced by CurrentRaycastResult.gameObject != null.

Value true if the pointer raycast intersects any object, otherwise false.

IsTouching

bool IsTouching

Gets a value indicating whether the user is currently touching the touchpad.

Used by GvrPointerScrollInput to generate OnScroll events using Unity's event system. Defaults to ControllerInputDevice.GetButton(TouchPadTouch), can be overridden to change the input source.

Value true the user is currently touching the touchpad; otherwise, false.

MaxPointerDistance

abstract float MaxPointerDistance

Gets the max distance from the pointer that raycast hits will be detected.

The max pointer distance from the pointer that raycast hits will be detected.

MaxPointerEndPoint

Vector3 MaxPointerEndPoint

Gets the end point of the pointer when it is MaxPointerDistance away from the origin.

The end point of the pointer when it is MaxPointerDistance away from the origin.

PointerCamera

Camera PointerCamera

Gets the camera used as the pointer.

The camera used as the pointer.

PointerIntersection

Vector3 PointerIntersection

Gets the pointer intersection.

Deprecated. Replaced by CurrentRaycastResult.worldPosition.

The pointer intersection.

PointerTransform

Transform PointerTransform

Gets the transform that represents this pointer.

It is used by GvrBasePointerRaycaster as the origin of the ray.

The pointer transform.

ShouldUseExitRadiusForRaycast

bool ShouldUseExitRadiusForRaycast

Gets or sets a value indicating whether the enterRadius should be used for the raycast or the exitRadius should be used.

It is set by GvrPointerInputModule and doesn't need to be controlled manually.

Value true if enterRadius should be used for the racyast, false otherwise.

TouchDown

bool TouchDown

Gets a value indicating whether the user just started touching the touchpad.

This is an event flag; it is true for only one frame after the event happens, then reverts to false. Used by GvrPointerScrollInput to generate OnScroll events using Unity's event system. Defaults to ControllerInputDevice.GetButtonDown(TouchPadTouch), can be overridden to change the input source.

Value true if the user just started touching the touchpad, false otherwise.

TouchPos

Vector2 TouchPos

Gets the position of the current touch, if touching the touchpad.

If not touching, this is the position of the last touch (when the finger left the touchpad).

The X and Y range is from 0 to 1. (0, 0) is the top left of the touchpad and (1, 1) is the bottom right of the touchpad. Used by GvrPointerScrollInput to generate OnScroll events using Unity's event system. Defaults to ControllerInputDevice.TouchPos but translated to top-left-relative coordinates for backwards compatibility. Can be overridden to change the input source.

The touch position.

TouchUp

bool TouchUp

Gets a value indicating whether the user just stopped touching the touchpad.

This is an event flag; it is true for only one frame after the event happens, then reverts to false. Used by GvrPointerScrollInput to generate OnScroll events using Unity's event system. Defaults to ControllerInputDevice.GetButtonUp(TouchPadTouch), can be overridden to change the input source.

The touch up.

TriggerDown

bool TriggerDown

Gets a value indicating whether the trigger was just pressed.

This is an event flag. It will be true for only one frame after the event happens. Defaults to mouse button 0 down on Cardboard or ControllerInputDevice.GetButtonDown(TouchPadButton) on Daydream. Can be overridden to change the trigger.

Value true if the trigger was just pressed, false otherwise.

TriggerUp

bool TriggerUp

Gets a value indicating whether the trigger was just released.

This is an event flag; it will be true for only one frame after the event happens. Defaults to mouse button 0 up on Cardboard or ControllerInputDevice.GetButtonUp(TouchPadButton) on Daydream. Can be overridden to change the trigger.

Value true if the trigger was just released, false otherwise.

Triggering

bool Triggering

Gets a value indicating whether the trigger is currently being pressed.

This is not an event; it represents the trigger's state (it remains true while the trigger is being pressed). Defaults to mouse button 0 state on Cardboard or ControllerInputDevice.GetButton(TouchPadButton) on Daydream. Can be overridden to change the trigger.

Value true if the trigger is currently being pressed, false otherwise.

Public static functions

CalculateHybridRay

PointerRay CalculateHybridRay(
  GvrBasePointer pointer,
  RaycastMode hybridMode
)

Calculates the ray for the segment of the Hybrid raycast determined by the raycast mode passed in.

Throws an exception if Hybrid is passed in.

Details
Parameters
pointer
Which pointer to project the ray from.
hybridMode
Which Raycast sub-mode to use within Hybrid mode. Must be Camera or Direct.
Returns
The PointerRay as projected from the GvrbasePointer in the given mode.

CalculateRay

PointerRay CalculateRay(
  GvrBasePointer pointer,
  RaycastMode mode
)

Calculates the ray for a given Raycast mode.

Will throw an exception if the raycast mode Hybrid is passed in. If you need to calculate the ray for the direct or camera segment of the Hybrid raycast, use CalculateHybridRay instead.

Details
Parameters
pointer
Which pointer to project the ray from.
mode
Which Raycast mode to use. Must be Camera or Direct.
Returns
The PointerRay as projected from the GvrbasePointer in the given mode.

Public functions

GetPointAlongPointer

Vector3 GetPointAlongPointer(
  float distance
)

Returns a point in worldspace a specified distance along the pointer.

What this point will be is different depending on the raycastMode.

Because raycast modes differ, use this function instead of manually calculating a point projected from the pointer.

Details
Parameters
distance
The distance along the pointer's laser.
Returns
A worlspace position along the pointer's laser.

GetPointerRadius

virtual abstract void GetPointerRadius(
  out float enterRadius,
  out float exitRadius
)

Return the radius of the pointer.

It is used by GvrPointerPhysicsRaycaster when searching for valid pointer targets. If a radius is 0, then a ray is used to find a valid pointer target. Otherwise it will use a SphereCast.

The enterRadius is used for finding new targets while the exitRadius is used to see if you are still nearby the object currently pointed at to avoid a flickering effect when just at the border of the intersection.

NOTE: This is only works with GvrPointerPhysicsRaycaster. To use it with uGUI, add 3D colliders to your canvas elements.

Details
Parameters
enterRadius
Used for finding new targets.
exitRadius
Used to see if the pointer is still nearby the object currently pointed at. This exists to avoid a flickering effect when just at the border of the intersection.

GetRayForDistance

PointerRay GetRayForDistance(
  float distance
)

Returns the ray used for projecting points out of the pointer for the given distance.

In Hybrid raycast mode, the ray will be different depending upon the distance. In Camera or Direct raycast mode, the ray will always be the same.

Details
Parameters
distance
The distance to check.
Returns
Either the Camera or Controller's PointerRay. For Hybrid mode, this will return Camera at large distances and Controller at close distances. For other modes, the ray will always be the mode's associated ray (Camera=Camera, Direct=Controller).

OnPointerClickDown

virtual abstract void OnPointerClickDown()

Called when a click is initiated.

OnPointerClickUp

virtual abstract void OnPointerClickUp()

Called when click is finished.

OnPointerEnter

virtual abstract void OnPointerEnter(
  RaycastResult raycastResult,
  bool isInteractive
)

Called when the pointer is facing a valid GameObject.

This can be a 3D or UI element.

Details
Parameters
raycastResult
The hit detection result for the object being pointed at.
isInteractive
Value true if the object being pointed at is interactive.

OnPointerExit

virtual abstract void OnPointerExit(
  GameObject previousObject
)

Called when the pointer no longer faces an object previously intersected with a ray projected from the camera.

This is also called just before OnInputModuleDisabled previousObject will be null in this case.

Details
Parameters
previousObject
The object that was being pointed at the previous frame.

OnPointerHover

virtual abstract void OnPointerHover(
  RaycastResult raycastResultResult,
  bool isInteractive
)

Called every frame the user is still pointing at a valid GameObject.

This can be a 3D or UI element.

Details
Parameters
raycastResultResult
The hit detection result for the object being pointed at.
isInteractive
Value true if the object being pointed at is interactive.