Meta Developers

	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.
void	Dispose ( bool disposing )

Public Member Functions

int	LoadClip ( string clipJson ) Loads haptic data from a JSON string.
bool	ReleaseClip ( int clipId ) Releases ownership of a loaded haptic clip.
int	CreateHapticPlayer ( ) Creates a haptic clip player.
void	SetHapticPlayerClip ( int playerId, int clipId ) Sets the clip that is used by the given player.
void	PlayHapticPlayer ( int playerId, Controller controller ) Starts playback on the player with the specified player ID on the specified controller.
void	StopHapticPlayer ( int playerId ) Stops playback that was previously started with PlayHapticPlayer().
float	GetClipDuration ( int clipId ) Returns the duration of the loaded haptic clip.
void	LoopHapticPlayer ( int playerId, bool enabled ) Enables or disables a clip player's loop state.
bool	IsHapticPlayerLooping ( int playerId ) Gets a clip player's loop state (if it loops or not).
void	SetAmplitudeHapticPlayer ( int playerId, float amplitude ) Sets the clip player's amplitude.
float	GetAmplitudeHapticPlayer ( int playerId ) Get the clip player's amplitude.
void	SetFrequencyShiftHapticPlayer ( int playerId, float amount ) Sets the clip player's frequency shift.
float	GetFrequencyShiftHapticPlayer ( int playerId ) Gets the clip player's current frequency shift based on it's player ID.
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.
uint	GetPriorityHapticPlayer ( int playerId ) Gets the clip player's current playback priority value based on its player ID.
bool	ReleaseHapticPlayer ( int playerId ) Releases a clip player that was previously created with CreateHapticPlayer().
void	Dispose ( ) Call this to explicitly release the haptics runtime.

Details

Detailed Description

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

Haptics Oculus.Haptics.Haptics.instance
No description available.

Properties

Haptics Oculus.Haptics.Haptics.Instance
Returns the singleton instance of Haptics: either existing or new.

Object Data

Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.Dispose ( bool disposing )
No description available.

Member Functions

int Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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.

bool Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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).

void Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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.

void Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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 Oculus.Haptics.Haptics.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.

void Oculus.Haptics.Haptics.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?