Haptic API
The Haptic module manages haptic playback on a TESLASUIT device.
It provides functions to create playable objects from preloaded haptic assets or instant touch parameters, control their playback (play, stop, pause, loop), and scale haptic output using master or per-playable multipliers and the global haptic power parameter. Channels used by playables are obtained from the Mapping API module.
Functions#
ts_haptic_is_player_running#
TsStatusCode ts_haptic_is_player_running(TsDeviceHandle* dev, bool* is_running);Checks whether the haptic player is currently running.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose haptic player state is queried.
is_running: bool*, out
Receives true if the player is actively running, or false if it is stopped.
Returns: TsStatusCode
TsStatusCode indicating whether the state was retrieved successfully.
ts_haptic_stop_player#
TsStatusCode ts_haptic_stop_player(TsDeviceHandle* dev);Stops the haptic player for the device.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose haptic player should be stopped.
Returns: TsStatusCode
TsStatusCode indicating whether the player was stopped successfully.
ts_haptic_get_player_paused#
TsStatusCode ts_haptic_get_player_paused(TsDeviceHandle* dev, bool* is_paused);Checks whether the haptic player is currently paused.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose haptic player state is queried.
is_paused: bool*, out
Receives true if the player is paused, or false if it is active.
Returns: TsStatusCode
TsStatusCode indicating whether the state was retrieved successfully.
ts_haptic_set_player_paused#
TsStatusCode ts_haptic_set_player_paused(TsDeviceHandle* dev, bool is_paused);Pauses or resumes the haptic player.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose haptic player is toggled.
is_paused: bool, in
Pass true to pause playback, or false to resume it.
Returns: TsStatusCode
TsStatusCode indicating whether the pause state was applied successfully.
ts_haptic_get_player_muted#
TsStatusCode ts_haptic_get_player_muted(TsDeviceHandle* dev, bool* is_muted);Checks whether the haptic player is currently muted.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose haptic player state is queried.
is_muted: bool*, out
Receives true if the player is muted, or false if output is enabled.
Returns: TsStatusCode
TsStatusCode indicating whether the state was retrieved successfully.
ts_haptic_set_player_muted#
TsStatusCode ts_haptic_set_player_muted(TsDeviceHandle* dev, bool is_muted);Mutes or unmutes the haptic player.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose haptic player is muted or unmuted.
is_muted: bool, in
Pass true to mute output, or false to unmute it.
Returns: TsStatusCode
TsStatusCode indicating whether the mute state was applied successfully.
ts_haptic_get_player_time#
TsStatusCode ts_haptic_get_player_time(TsDeviceHandle* dev, uint64_t* time);Gets the elapsed playback time of the haptic player.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose haptic player time is queried.
time: uint64_t*, out
Receives the elapsed player time in milliseconds since the player started.
Returns: TsStatusCode
TsStatusCode indicating whether the time was retrieved successfully.
ts_haptic_get_number_of_master_multipliers#
TsStatusCode ts_haptic_get_number_of_master_multipliers(TsDeviceHandle* dev, uint64_t* number_of_multipliers);Gets the number of haptic master multipliers.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose master multiplier count is queried.
number_of_multipliers: uint64_t*, out
Receives the number of master multipliers exposed by the player.
Returns: TsStatusCode
TsStatusCode indicating whether the count was retrieved successfully.
See also: ts_haptic_get_master_multipliers
ts_haptic_get_master_multipliers#
TsStatusCode ts_haptic_get_master_multipliers(TsDeviceHandle* dev, TsHapticParamMultiplier* multipliers, uint64_t number_of_multipliers);Gets the haptic player's master multipliers.
Preconditions
ts_initialize or ts_initialize_with_path, ts_haptic_get_number_of_master_multipliers
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose master multipliers are queried.
multipliers: TsHapticParamMultiplier*, out
Preallocated array that receives the master multiplier type/value pairs.
number_of_multipliers: uint64_t, in
Number of elements available in the multipliers array.
Returns: TsStatusCode
TsStatusCode indicating whether the multipliers were retrieved successfully.
ts_haptic_set_master_multipliers#
TsStatusCode ts_haptic_set_master_multipliers(TsDeviceHandle* dev, const TsHapticParamMultiplier* multipliers, uint64_t number_of_multipliers);Sets the haptic player's master multipliers.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose master multipliers are updated.
multipliers: const TsHapticParamMultiplier*, in
Array of master multiplier type/value pairs to apply.
number_of_multipliers: uint64_t, in
Number of elements in the multipliers array.
Returns: TsStatusCode
TsStatusCode indicating whether the multipliers were applied successfully.
See also: ts_haptic_get_master_multipliers
ts_haptic_create_playable_from_asset#
TsStatusCode ts_haptic_create_playable_from_asset(TsDeviceHandle* dev, TsAsset* haptic_asset, bool is_looped, uint64_t* playable_id);Creates a haptic playable object from a preloaded asset.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that will host the new playable.
haptic_asset: TsAsset*, in
Handle to the preloaded haptic asset to wrap in a playable object.
is_looped: bool, in
Pass true to have the playable loop continuously once started, or false to play it once.
playable_id: uint64_t*, out
Receives the identifier of the newly created playable, used in subsequent playable calls.
Returns: TsStatusCode
TsStatusCode indicating whether the playable was created successfully.
See also: ts_haptic_play_playable, ts_haptic_remove_playable
ts_haptic_is_playable_exists#
TsStatusCode ts_haptic_is_playable_exists(TsDeviceHandle* dev, uint64_t playable_id, bool* is_exists);Checks whether a haptic playable object still exists in the haptic player.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose playable queue is checked.
playable_id: uint64_t, in
Identifier of the playable to look up.
is_exists: bool*, out
Receives true if a playable with this ID is still present, or false otherwise.
Returns: TsStatusCode
TsStatusCode indicating whether the check completed successfully.
ts_haptic_play_playable#
TsStatusCode ts_haptic_play_playable(TsDeviceHandle* dev, uint64_t playable_id);Starts playback of a haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the playable to start playing.
Returns: TsStatusCode
TsStatusCode indicating whether playback was started successfully.
See also: ts_haptic_stop_playable
ts_haptic_play_touch#
TsStatusCode ts_haptic_play_touch(TsDeviceHandle* dev, TsHapticParam* params, uint64_t size, const TsMapping2dBoneContent* channels, uint64_t number_of_channels, uint64_t duration);Immediately plays a one-off haptic touch with the given parameters.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that will render the touch.
params: TsHapticParam*, in
Array of haptic parameters (such as amplitude, period, and pulse width) that define the touch waveform.
size: uint64_t, in
Number of elements in the params array.
channels: const TsMapping2dBoneContent*, in
Array of channel handles, obtained from Mapping API, that identify where on the body the touch is felt.
number_of_channels: uint64_t, in
Number of elements in the channels array.
duration: uint64_t, in
Duration of the touch in milliseconds.
Returns: TsStatusCode
TsStatusCode indicating whether the touch was started successfully.
See also: ts_haptic_create_touch, ts_haptic_stop_playable
ts_haptic_create_touch#
TsStatusCode ts_haptic_create_touch(TsDeviceHandle* dev, TsHapticParam* params, uint64_t params_size, const TsMapping2dBoneContent* channels, uint64_t number_of_channels, uint64_t duration, uint64_t* playable_id);Creates a haptic touch playable without starting playback.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that will own the new playable.
params: TsHapticParam*, in
Array of haptic parameters (such as amplitude, period, and pulse width) that define the touch waveform.
params_size: uint64_t, in
Number of elements in the params array.
channels: const TsMapping2dBoneContent*, in
Array of channel handles, obtained from Mapping API, that identify where on the body the touch is felt.
number_of_channels: uint64_t, in
Number of elements in the channels array.
duration: uint64_t, in
Duration of the touch in milliseconds.
playable_id: uint64_t*, out
Receives the identifier of the newly created touch playable.
Returns: TsStatusCode
TsStatusCode indicating whether the touch playable was created successfully.
ts_haptic_create_material_asset#
TsAsset* ts_haptic_create_material_asset(TsAsset* touch_sequence, TsAsset* effect);Creates a haptic material asset from a touch sequence and an effect.
Preconditions
Parameters
touch_sequence: TsAsset*, in
Handle to the touch sequence asset providing the base haptic waveform.
effect: TsAsset*, in
Handle to the effect asset providing the material's haptic effect behavior.
See also: ts_haptic_create_playable_from_asset
ts_haptic_is_playable_playing#
TsStatusCode ts_haptic_is_playable_playing(TsDeviceHandle* dev, uint64_t playable_id, bool* is_playing);Checks whether a haptic playable object is currently playing.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to query.
is_playing: bool*, out
Receives true if the playable is currently playing, or false otherwise.
Returns: TsStatusCode
TsStatusCode indicating whether the state was retrieved successfully.
ts_haptic_stop_playable#
TsStatusCode ts_haptic_stop_playable(TsDeviceHandle* dev, uint64_t playable_id);Stops a haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to stop.
Returns: TsStatusCode
TsStatusCode indicating whether the playable was stopped successfully.
ts_haptic_remove_playable#
TsStatusCode ts_haptic_remove_playable(TsDeviceHandle* dev, uint64_t playable_id);Removes a haptic playable object from the haptic player.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded playable haptic object to remove.
Returns: TsStatusCode
TsStatusCode indicating whether the playable was removed successfully.
ts_haptic_get_playable_paused#
TsStatusCode ts_haptic_get_playable_paused(TsDeviceHandle* dev, uint64_t playable_id, bool* is_paused);Checks whether a haptic playable object is currently paused.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to query.
is_paused: bool*, out
Receives true if the playable is paused, or false otherwise.
Returns: TsStatusCode
TsStatusCode indicating whether the state was retrieved successfully.
ts_haptic_set_playable_paused#
TsStatusCode ts_haptic_set_playable_paused(TsDeviceHandle* dev, uint64_t playable_id, bool is_paused);Pauses or resumes a specific haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to pause or resume.
is_paused: bool, in
Pass true to pause the playable, or false to resume it.
Returns: TsStatusCode
TsStatusCode indicating whether the pause state was applied successfully.
ts_haptic_get_playable_muted#
TsStatusCode ts_haptic_get_playable_muted(TsDeviceHandle* dev, uint64_t playable_id, bool* is_muted);Checks whether a haptic playable object is currently muted.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to query.
is_muted: bool*, out
Receives true if the playable is muted, or false otherwise.
Returns: TsStatusCode
TsStatusCode indicating whether the state was retrieved successfully.
ts_haptic_set_playable_muted#
TsStatusCode ts_haptic_set_playable_muted(TsDeviceHandle* dev, uint64_t playable_id, bool is_muted);Mutes or unmutes a specific haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to mute or unmute.
is_muted: bool, in
Pass true to mute the playable, or false to unmute it.
Returns: TsStatusCode
TsStatusCode indicating whether the mute state was applied successfully.
ts_haptic_get_playable_looped#
TsStatusCode ts_haptic_get_playable_looped(TsDeviceHandle* dev, uint64_t playable_id, bool* is_looped);Checks whether a haptic playable object is set to loop.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to query.
is_looped: bool*, out
Receives true if the playable is set to loop, or false if it plays once.
Returns: TsStatusCode
TsStatusCode indicating whether the state was retrieved successfully.
ts_haptic_set_playable_looped#
TsStatusCode ts_haptic_set_playable_looped(TsDeviceHandle* dev, uint64_t playable_id, bool is_looped);Enables or disables looping for a haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to update.
is_looped: bool, in
Pass true to loop the playable continuously, or false to play it once.
Returns: TsStatusCode
TsStatusCode indicating whether the loop state was applied successfully.
ts_haptic_get_number_of_playable_multipliers#
TsStatusCode ts_haptic_get_number_of_playable_multipliers(TsDeviceHandle* dev, uint64_t playable_id, uint64_t* number_of_multipliers);Gets the number of parameter multipliers exposed by a haptic playable.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded playable whose multiplier count is queried.
number_of_multipliers: uint64_t*, out
Receives the number of parameter multipliers exposed by the playable.
Returns: TsStatusCode
TsStatusCode indicating whether the count was retrieved successfully.
ts_haptic_get_playable_multipliers#
TsStatusCode ts_haptic_get_playable_multipliers(TsDeviceHandle* dev, uint64_t playable_id, TsHapticParamMultiplier* multipliers, uint64_t number_of_multipliers);Gets the parameter multipliers for a specific haptic playable.
Preconditions
ts_initialize or ts_initialize_with_path, ts_haptic_get_number_of_playable_multipliers
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded playable whose multipliers are queried.
multipliers: TsHapticParamMultiplier*, out
Preallocated array that receives the playable's multiplier type/value pairs.
number_of_multipliers: uint64_t, in
Number of elements available in the multipliers array.
Returns: TsStatusCode
TsStatusCode indicating whether the multipliers were retrieved successfully.
ts_haptic_set_playable_multipliers#
TsStatusCode ts_haptic_set_playable_multipliers(TsDeviceHandle* dev, uint64_t playable_id, const TsHapticParamMultiplier* multipliers, uint64_t number_of_multipliers);Sets the parameter multipliers for a specific haptic playable.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded playable whose multipliers are updated.
multipliers: const TsHapticParamMultiplier*, in
Array of multiplier type/value pairs to apply to the playable.
number_of_multipliers: uint64_t, in
Number of elements in the multipliers array.
Returns: TsStatusCode
TsStatusCode indicating whether the multipliers were applied successfully.
See also: ts_haptic_get_playable_multipliers
ts_haptic_get_playable_local_time#
TsStatusCode ts_haptic_get_playable_local_time(TsDeviceHandle* dev, uint64_t playable_id, uint64_t* local_time);Gets the local playback position of a haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to query.
local_time: uint64_t*, out
Receives the playable's current relative playback position in milliseconds.
Returns: TsStatusCode
TsStatusCode indicating whether the position was retrieved successfully.
ts_haptic_set_playable_local_time#
TsStatusCode ts_haptic_set_playable_local_time(TsDeviceHandle* dev, uint64_t playable_id, uint64_t local_time);Seeks a haptic playable object to a specific local playback position.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to seek.
local_time: uint64_t, in
Target playback position relative to the playable's start, in milliseconds.
Returns: TsStatusCode
TsStatusCode indicating whether the seek was applied successfully.
ts_haptic_get_playable_duration#
TsStatusCode ts_haptic_get_playable_duration(TsDeviceHandle* dev, uint64_t playable_id, uint64_t* duration);Gets the total duration of a haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
playable_id: uint64_t, in
Identifier of the preloaded playable object to query.
duration: uint64_t*, out
Receives the total duration of the playable in milliseconds.
Returns: TsStatusCode
TsStatusCode indicating whether the duration was retrieved successfully.
ts_haptic_clear_all_playables#
TsStatusCode ts_haptic_clear_all_playables(TsDeviceHandle* dev);Removes all haptic playable objects from the haptic player.
Preconditions
Returns: TsStatusCode
TsStatusCode indicating whether all playables were removed successfully.
ts_haptic_add_channel_to_dynamic_playable#
TsStatusCode ts_haptic_add_channel_to_dynamic_playable(TsDeviceHandle* dev, const TsMapping2dBoneContent channel, uint64_t playable_id);Adds a channel to a dynamic haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
channel: const TsMapping2dBoneContent, in
Handle to the channel, obtained from Mapping API, to add to the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to add the channel to.
Returns: TsStatusCode
TsStatusCode indicating whether the channel was added successfully.
ts_haptic_remove_channel_from_dynamic_playable#
TsStatusCode ts_haptic_remove_channel_from_dynamic_playable(TsDeviceHandle* dev, const TsMapping2dBoneContent channel, uint64_t playable_id);Removes a channel from a dynamic haptic playable object.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
channel: const TsMapping2dBoneContent, in
Handle to the channel, obtained from Mapping API, to remove from the playable.
playable_id: uint64_t, in
Identifier of the preloaded haptic playable object to remove the channel from.
Returns: TsStatusCode
TsStatusCode indicating whether the channel was removed successfully.
ts_haptic_set_material_channel_impact#
TsStatusCode ts_haptic_set_material_channel_impact(TsDeviceHandle* dev, const TsMapping2dBoneContent channel, float impact, uint64_t playable_id);Sets the material impact value for a channel of a haptic material playable.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device that owns the playable.
channel: const TsMapping2dBoneContent, in
Handle to the channel, obtained from Mapping API, whose impact is being set.
impact: float, in
Impact value in the range [0..1] controlling the material's intensity on this channel.
playable_id: uint64_t, in
Identifier of the preloaded HapticMaterial playable to update.
Returns: TsStatusCode
TsStatusCode indicating whether the impact value was applied successfully.
ts_haptic_set_global_power#
TsStatusCode ts_haptic_set_global_power(TsDeviceHandle* dev, float value);Sets the Global Haptic Power parameter for the device.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose global haptic power is set.
value: float, in
Desired power value in the range [0..1]; values outside this range are clamped.
Returns: TsStatusCode
TsStatusCode indicating whether the power value was applied successfully.
ts_haptic_get_global_power#
TsStatusCode ts_haptic_get_global_power(TsDeviceHandle* dev, float* value);Gets the Global Haptic Power parameter for the device.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose global haptic power is queried.
value: float*, out
Receives the current Global Haptic Power value, in the range [0..1].
Returns: TsStatusCode
TsStatusCode indicating whether the value was retrieved successfully.
ts_haptic_set_multiplier_change_callback#
TsStatusCode ts_haptic_set_multiplier_change_callback(TsDeviceHandle* dev, void(*)() callback);Subscribes to the multiplier change event for a device.
Preconditions
Parameters
dev: TsDeviceHandle*, in
Handle to the target device whose multiplier changes are observed.
callback: void(*)(), in
Application-supplied function that is invoked whenever a multiplier changes.
Returns: TsStatusCode
TsStatusCode indicating whether the subscription was registered successfully.