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.
Returns the singleton instance of Haptics: either existing or new.
Protected Functions
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.
virtual void Dispose
( bool disposing )
Member Functions
int LoadClip
( string clipJson )
Loads haptic data from a JSON string.
Parameters
clipJson
The UTF-8-encoded JSON string containing haptic data (.haptic format).
Returns
A haptic clip ID if the data is parsed successfully; Ffi.InvalidId otherwise.
Exceptions
FormatException
If the format of the haptic clip data is not valid; or the data is not UTF-8 encoded.
bool ReleaseClip
( int 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.
Parameters
clipId
The ID of the haptic clip to be released.
Returns
true if the clip was released successfully; false if the clip was already released or the call was unsuccessful.
int 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().
Returns
The player ID, if the player was created successfully; Ffi.InvalidId if something went wrong.
void SetHapticPlayerClip
( int playerId,
int 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).
Parameters
playerId
The ID of the clip player.
clipId
The ID of the haptic clip to be released.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the clip ID was invalid.
void PlayHapticPlayer
( int playerId,
Controller controller )
Starts playback on the player with the specified player ID on the specified controller.
Parameters
playerId
The ID of the clip player to start playback on.
controller
The controller to play on. Can be Left, Right or Both controllers.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If an invalid controller was selected for playback.
The ID of the haptic clip to be queried for its duration.
Returns
The duration of the haptic clip in seconds if the call was successful; 0.0 otherwise.
Exceptions
ArgumentException
If the clip ID was invalid.
void LoopHapticPlayer
( int playerId,
bool enabled )
Enables or disables a clip player's loop state.
Parameters
playerId
The ID of the clip player.
enabled
true if the clip player should loop; false to disable looping.
Exceptions
ArgumentException
If the player ID was invalid.
bool IsHapticPlayerLooping
( int playerId )
Gets a clip player's loop state (if it loops or not).
Parameters
playerId
The ID of the clip player.
Returns
The current loop state, if getting the state was successful, and the default value of false otherwise.
Exceptions
ArgumentException
If the player ID was invalid.
void SetAmplitudeHapticPlayer
( int playerId,
float amplitude )
Sets the clip player's amplitude.
Parameters
playerId
The ID of the clip player.
amplitude
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.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the amplitude argument is out of range (has to be non-negative).
float GetAmplitudeHapticPlayer
( int playerId )
Get the clip player's amplitude.
Parameters
playerId
The ID of the clip player.
Returns
The current player amplitude, if getting amplitude was successful; and the default value (1.0) otherwise.
Exceptions
ArgumentException
If the player ID was invalid.
void SetFrequencyShiftHapticPlayer
( int playerId,
float amount )
Sets the clip player's frequency shift.
Parameters
playerId
ID of the clip player.
amount
A value between -1.0 and 1.0 (inclusive). Values outside this range will cause an exception.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the frequency shift amount is out of range.
float GetFrequencyShiftHapticPlayer
( int playerId )
Gets the clip player's current frequency shift based on it's player ID.
Parameters
playerId
The ID of the clip player.
Returns
The current player frequency shift if getting frequency shift was successful; the default value (0.0) otherwise.
Exceptions
ArgumentException
If the player ID was invalid.
void SetPriorityHapticPlayer
( int playerId,
uint 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.
Parameters
playerId
ID of the clip player.
value
A value between 0 and 255 (inclusive). Values outside this range will cause an exception.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the priority value is out of range.
uint GetPriorityHapticPlayer
( int playerId )
Gets the clip player's current playback priority value based on its player ID.
Parameters
playerId
The ID of the clip player.
Returns
The current priority value if successful; the default value (128) otherwise.
true if release was successful; false if the player does not exist, was already released, or the call was unsuccessful.
void Dispose ( )
Call this to explicitly release the haptics runtime.
This will also result in any HapticClipPlayers and HapticClips loaded into the runtime getting 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 to get released via ~Haptics on shutdown. However if you do have a particular reason to release it explicitly, creating a new HapticClipPlayer will produce a new one.
