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.

Object Data for protected-static-attrib

static Haptics instance[Get]

Properties

static Haptics Instance[Get]

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.

InvalidOperationException

If the player has no clip loaded.

void StopHapticPlayer

( int playerId )

Stops playback that was previously started with PlayHapticPlayer().

Parameters

playerId

The ID of the clip player to stop playback on.

Exceptions

ArgumentException

If the player ID was invalid.

InvalidOperationException

If the player has no clip loaded.

float GetClipDuration

( int clipId )

Returns the duration of the loaded haptic clip.

Parameters

clipId

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.

Exceptions

ArgumentException

If the player ID was invalid.

bool ReleaseHapticPlayer

( int playerId )

Releases a clip player that was previously created with CreateHapticPlayer().

Parameters

playerId

ID of the clip player to be released.

Returns

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.

Did you find this page helpful?