Haptics Class

Extends IDisposable

Low-level API for the XR Haptics SDK runtime.

This class is provided where low-level control of the XR Haptics SDK runtime is required. Most applications probably do not require this class and HapticClipPlayer and HapticClip should be used instead.

In a nutshell, it wraps the C# Native SDK bindings of the Oculus.Haptics.Ffi class to be used by C# abstractions. None of the methods here are thread-safe and should only be called from the main (Unity) thread. Calling these methods from a secondary thread can cause undefined behaviour and memory leaks.

Constructors

Haptics ()

The constructor is protected to ensure that a class instance cannot be created directly and all consuming code must go through the Instance property. This design pattern ensures a singleton-like behavior, where only one instance of the Haptics class exists throughout the application.

Signature

Oculus.Haptics.Haptics.Haptics()

Protected Static Fields

instance : Haptics

Signature

Haptics Oculus.Haptics.Haptics.instance

Properties

Instance : Haptics [Get]	Returns the singleton instance of Haptics: either existing or new. The Haptics class provides access to haptic feedback functionality. This property returns the singleton instance of Haptics,creating a new instance if one does not already exist. Signature Haptics Oculus.Haptics.Haptics.Instance
IsPCMHaptics : bool [Get]	Whether PCM haptics are available and enabled for the current runtime. PCM haptics allow for high-quality haptic feedback. This property indicates whether PCM haptics are supported by the current runtime and whether they are enabled. Signature bool Oculus.Haptics.Haptics.IsPCMHaptics

Protected Methods

Dispose ( disposing )

Signature

virtual void Oculus.Haptics.Haptics.Dispose(bool disposing)

Parameters

disposing: bool

Returns

void

Methods

CreateHapticPlayer ()	Creates a haptic clip player. To play a haptic clip with a created player, the haptic clip must first be loaded using LoadClip(), assigned to the player using SetHapticPlayerClip(), and finally playback is started using PlayHapticPlayer(). Signature int Oculus.Haptics.Haptics.CreateHapticPlayer() Returns `int` The player ID, if the player was created successfully; Ffi.InvalidId if something went wrong.
Dispose ()	Call this to explicitly release the haptics runtime. This method has the haptics runtime released while ensuring that the garbage collector doesn't kick in., which will also result in any loaded HapticClipPlayers and HapticClips being released from memory. In general, you shouldn't need to explicitly release the haptics runtime as it is intended to run for the duration of your application and gets released via `~Haptics` on shutdown. However, if you have a particular reason to release it explicitly, call Dispose() to do so. If you need to use the haptics runtime again after having released it simply create a new HapticClipPlayer and a new runtime will be instantiated implicitly. summary>Releases the haptics runtime and its associated resources. Signature void Oculus.Haptics.Haptics.Dispose() Returns `void`
GetAmplitudeHapticPlayer ( playerId )	Get the clip player's amplitude. Signature float Oculus.Haptics.Haptics.GetAmplitudeHapticPlayer(int playerId) Parameters `playerId: int` The ID of the clip player. Returns `float` The current player amplitude, if getting amplitude was successful; and the default value (1.0) otherwise. Throws `ArgumentException` If the player ID was invalid.
GetClipDuration ( clipId )	Returns the duration of the loaded haptic clip. Signature float Oculus.Haptics.Haptics.GetClipDuration(int clipId) Parameters `clipId: int` The ID of the haptic clip to be queried for its duration. Returns `float` The duration of the haptic clip in seconds if the call was successful; 0.0 otherwise. Throws `ArgumentException` If the clip ID was invalid.
GetFrequencyShiftHapticPlayer ( playerId )	Gets the clip player's current frequency shift based on it's player ID. Signature float Oculus.Haptics.Haptics.GetFrequencyShiftHapticPlayer(int playerId) Parameters `playerId: int` The ID of the clip player. Returns `float` The current player frequency shift if getting frequency shift was successful; the default value (0.0) otherwise. Throws `ArgumentException` If the player ID was invalid.
GetPriorityHapticPlayer ( playerId )	Gets the clip player's current playback priority value based on its player ID. Signature uint Oculus.Haptics.Haptics.GetPriorityHapticPlayer(int playerId) Parameters `playerId: int` The ID of the clip player. Returns `uint` The current priority value if successful; the default value (128) otherwise. Throws `ArgumentException` If the player ID was invalid.
IsHapticPlayerLooping ( playerId )	Gets a clip player's loop state (if it loops or not). Signature bool Oculus.Haptics.Haptics.IsHapticPlayerLooping(int playerId) Parameters `playerId: int` The ID of the clip player. Returns `bool` The current loop state, if getting the state was successful, and the default value of `false` otherwise. Throws `ArgumentException` If the player ID was invalid.
LoadClip ( clipJson )	Loads haptic data from a JSON string. Signature int Oculus.Haptics.Haptics.LoadClip(string clipJson) Parameters `clipJson: string` The UTF-8-encoded JSON string containing haptic data (.haptic format). Returns `int` A haptic clip ID if the data is parsed successfully; Ffi.InvalidId otherwise. Throws `FormatException` If the format of the haptic clip data is not valid; or the data is not UTF-8 encoded.
LoopHapticPlayer ( playerId , enabled )	Enables or disables a clip player's loop state. Signature void Oculus.Haptics.Haptics.LoopHapticPlayer(int playerId, bool enabled) Parameters `playerId: int` The ID of the clip player. `enabled: bool` `true` if the clip player should loop; `false` to disable looping. Returns `void` Throws `ArgumentException` If the player ID was invalid.
PauseHapticPlayer ( playerId )	Pauses playback on the player with the specified player ID. Signature void Oculus.Haptics.Haptics.PauseHapticPlayer(int playerId) Parameters `playerId: int` The ID of the clip player to pause playback on. Returns `void` Throws `ArgumentException` If the player ID was invalid. `InvalidOperationException` If the player has no clip loaded.
PlayHapticPlayer ( playerId , controller )	Starts playback on the player with the specified player ID on the specified controller. Signature void Oculus.Haptics.Haptics.PlayHapticPlayer(int playerId, Controller controller) Parameters `playerId: int` The ID of the clip player to start playback on. `controller: Controller` The controller to play on. Can be `Left`, `Right` or `Both` controllers. Returns `void` Throws `ArgumentException` If the player ID was invalid. `ArgumentException` If an invalid controller was selected for playback. `InvalidOperationException` If the player has no clip loaded.
ReleaseClip ( clipId )	Releases ownership of a loaded haptic clip. Releasing the clip means that the API no longer maintains a handle to the clip. However resources won't be freed until all clip players that are playing the clip have also been destroyed. Signature bool Oculus.Haptics.Haptics.ReleaseClip(int clipId) Parameters `clipId: int` The ID of the haptic clip to be released. Returns `bool` `true` if the clip was released successfully; `false` if the clip was already released or the call was unsuccessful.
ReleaseHapticPlayer ( playerId )	Releases a clip player that was previously created with CreateHapticPlayer(). Signature bool Oculus.Haptics.Haptics.ReleaseHapticPlayer(int playerId) Parameters `playerId: int` ID of the clip player to be released. Returns `bool` `true` if release was successful; `false` if the player does not exist, was already released, or the call was unsuccessful.
ResumeHapticPlayer ( playerId )	Resumes playback on the player with the specified player ID. Signature void Oculus.Haptics.Haptics.ResumeHapticPlayer(int playerId) Parameters `playerId: int` The ID of the clip player to resume playback on. Returns `void` Throws `ArgumentException` If the player ID was invalid. `InvalidOperationException` If the player has no clip loaded.
SeekPlaybackPositionHapticPlayer ( playerId , time )	Seeks the current playback position. Signature void Oculus.Haptics.Haptics.SeekPlaybackPositionHapticPlayer(int playerId, float time) Parameters `playerId: int` The ID of the clip player to move the playback position on. `time: float` The target playback position in seconds. Returns `void` Throws `ArgumentException` If the player ID was invalid. `InvalidOperationException` If the player has no clip loaded to seek. `ArgumentOutOfRangeException` If the target playback position is out of range. A valid playback position needs to be on a range of 0.0 to the currently loaded clip's duration in seconds. To get the duration of the currently loaded clip, see GetClipDuration.
SetAmplitudeHapticPlayer ( playerId , amplitude )	Sets the clip player's amplitude. Signature void Oculus.Haptics.Haptics.SetAmplitudeHapticPlayer(int playerId, float amplitude) Parameters `playerId: int` The ID of the clip player. `amplitude: float` A positive integer value for the amplitude of the clip player. All individual amplitudes within the clip are scaled by this value. Each individual value is clipped to one. Returns `void` Throws `ArgumentException` If the player ID was invalid. `ArgumentOutOfRangeException` If the amplitude argument is out of range (has to be non-negative).
SetFrequencyShiftHapticPlayer ( playerId , amount )	Sets the clip player's frequency shift. Signature void Oculus.Haptics.Haptics.SetFrequencyShiftHapticPlayer(int playerId, float amount) Parameters `playerId: int` ID of the clip player. `amount: float` A value between -1.0 and 1.0 (inclusive). Values outside this range will cause an exception. Returns `void` Throws `ArgumentException` If the player ID was invalid. `ArgumentOutOfRangeException` If the frequency shift amount is out of range.
SetHapticPlayerClip ( playerId , clipId )	Sets the clip that is used by the given player. If the player is currently playing, it will stop. Other properties like amplitude, frequency shift, looping and priority are kept. The clip must have been previously loaded by calling LoadClip() (see above). Signature void Oculus.Haptics.Haptics.SetHapticPlayerClip(int playerId, int clipId) Parameters `playerId: int` The ID of the clip player. `clipId: int` The ID of the haptic clip to be released. Returns `void` Throws `ArgumentException` If the player ID was invalid. `ArgumentException` If the clip ID was invalid.
SetPriorityHapticPlayer ( playerId , value )	Sets the clip player's current playback priority value based on its player ID. The priority values range from 0 (high priority) to 255 (low priority), with 128 being the default. Signature void Oculus.Haptics.Haptics.SetPriorityHapticPlayer(int playerId, uint value) Parameters `playerId: int` ID of the clip player. `value: uint` A value between 0 and 255 (inclusive). Values outside this range will cause an exception. Returns `void` Throws `ArgumentException` If the player ID was invalid. `ArgumentException` If the priority value is out of range.
StopHapticPlayer ( playerId )	Stops playback that was previously started with PlayHapticPlayer(). Signature void Oculus.Haptics.Haptics.StopHapticPlayer(int playerId) Parameters `playerId: int` The ID of the clip player to stop playback on. Returns `void` Throws `ArgumentException` If the player ID was invalid. `InvalidOperationException` If the player has no clip loaded.