VRTK_Pointer

extends VRTK_DestinationMarker

Overview

The VRTK Pointer class forms the basis of being able to emit a pointer from a game object (e.g. controller).

The concept of the pointer is it can be activated and deactivated and used to select elements utilising different button combinations if required.

The Pointer requires a Pointer Renderer which is the visualisation of the pointer in the scene.

A Pointer can also be used to extend the interactions of an interacting object such as a controller. This enables pointers to touch (and highlight), grab and use interactable objects.

The Pointer script does not need to go on a controller game object, but if it's placed on another object then a controller must be provided to determine what activates the pointer.

It extends the VRTK_DestinationMarker to allow for destination events to be emitted when the pointer cursor collides with objects.

Inspector Parameters

• Pointer Renderer: The specific renderer to use when the pointer is activated. The renderer also determines how the pointer reaches it's destination (e.g. straight line, bezier curve).
• Activation Button: The button used to activate/deactivate the pointer.
• Hold Button To Activate: If this is checked then the Activation Button needs to be continuously held down to keep the pointer active. If this is unchecked then the Activation Button works as a toggle, the first press/release enables the pointer and the second press/release disables the pointer.
• Activate On Enable: If this is checked then the pointer will be toggled on when the script is enabled.
• Activation Delay: The time in seconds to delay the pointer being able to be active again.
• Selection Button: The button used to execute the select action at the pointer's target position.
• Select On Press: If this is checked then the pointer selection action is executed when the Selection Button is pressed down. If this is unchecked then the selection action is executed when the Selection Button is released.
• Selection Delay: The time in seconds to delay the pointer being able to execute the select action again.
• Select After Hover Duration: The amount of time the pointer can be over the same collider before it automatically attempts to select it. 0f means no selection attempt will be made.
• Interact With Objects: If this is checked then the pointer will be an extension of the controller and able to interact with Interactable Objects.
• Grab To Pointer Tip: If Interact With Objects is checked and this is checked then when an object is grabbed with the pointer touching it, the object will attach to the pointer tip and not snap to the controller.
• Controller: An optional controller that will be used to toggle the pointer. If the script is being applied onto a controller then this parameter can be left blank as it will be auto populated by the controller the script is on at runtime.
• Interact Use: An optional InteractUse script that will be used when using interactable objects with pointer. If this is left blank then it will attempt to get the InteractUse script from the same GameObject and if it cannot find one then it will attempt to get it from the attached controller.
• Custom Origin: A custom transform to use as the origin of the pointer. If no pointer origin transform is provided then the transform the script is attached to is used.

Class Events

• ActivationButtonPressed - Emitted when the pointer activation button is pressed.
• ActivationButtonReleased - Emitted when the pointer activation button is released.
• SelectionButtonPressed - Emitted when the pointer selection button is pressed.
• SelectionButtonReleased - Emitted when the pointer selection button is released.
• PointerStateValid - Emitted when the pointer is in a valid state.
• PointerStateInvalid - Emitted when the pointer is in an invalid state.

Unity Events

Adding the VRTK_Pointer_UnityEvents component to VRTK_Pointer object allows access to UnityEvents that will react identically to the Class Events.

• All C# delegate events are mapped to a Unity Event with the On prefix. e.g. MyEvent -> OnMyEvent.

Class Methods

IsActivationButtonPressed/0

public virtual bool IsActivationButtonPressed()

• Parameters
• none
• Returns
• bool - Returns true if the activationButton is being pressed.

The IsActivationButtonPressed method returns whether the configured activation button is being pressed.

IsSelectionButtonPressed/0

public virtual bool IsSelectionButtonPressed()

• Parameters
• none
• Returns
• bool - Returns true if the selectionButton is being pressed.

The IsSelectionButtonPressed method returns whether the configured activation button is being pressed.

PointerEnter/1

public virtual void PointerEnter(RaycastHit givenHit)

• Parameters
• RaycastHit givenHit - The valid collision.
• Returns
• none

The PointerEnter method emits a DestinationMarkerEnter event when the pointer first enters a valid object, it emits a DestinationMarkerHover for every following frame that the pointer stays over the valid object.

PointerExit/1

public virtual void PointerExit(RaycastHit givenHit)

• Parameters
• RaycastHit givenHit - The previous valid collision.
• Returns
• none

The PointerExit method emits a DestinationMarkerExit event when the pointer leaves a previously entered object.

CanActivate/0

public virtual bool CanActivate()

• Parameters
• none
• Returns
• bool - Returns true if the pointer can be activated.

The CanActivate method is used to determine if the pointer has passed the activation time limit.

CanSelect/0

public virtual bool CanSelect()

• Parameters
• none
• Returns
• bool - Returns true if the pointer can execute the select action.

The CanSelect method is used to determine if the pointer has passed the selection time limit.

IsPointerActive/0

public virtual bool IsPointerActive()

• Parameters
• none
• Returns
• bool - Returns true if the pointer is currently active.

The IsPointerActive method is used to determine if the pointer's current state is active or not.

ResetActivationTimer/1

public virtual void ResetActivationTimer(bool forceZero = false)

• Parameters
• bool forceZero - If this is true then the next activation time will be 0.
• Returns
• none

The ResetActivationTimer method is used to reset the pointer activation timer to the next valid activation time.

ResetSelectionTimer/1

public virtual void ResetSelectionTimer(bool forceZero = false)

• Parameters
• bool forceZero - If this is true then the next activation time will be 0.
• Returns
• none

The ResetSelectionTimer method is used to reset the pointer selection timer to the next valid activation time.

Toggle/1

public virtual void Toggle(bool state)

• Parameters
• bool state - If true the pointer will be enabled if possible, if false the pointer will be disabled if possible.
• Returns
• none

The Toggle method is used to enable or disable the pointer.

IsStateValid/0

public virtual bool IsStateValid()

• Parameters
• none
• Returns
• bool - Returns true if the pointer is in the valid state (showing the valid colour), returns false if the pointer is in the invalid state (showing the invalid colour).

The IsStateValid method is used to determine if the pointer is currently in a valid state (i.e. on it's valid colour).