Interhaptics Engine

Overview

This documentation provides an overview of the functions available in the Interhaptics Engine API. The API allows developers to interact with the Interhaptics Engine and control haptic effects, manage body parts, and control haptic events.

This SDK provides a comprehensive set of tools and resources for integrating the Interhaptics Engine into a game application on the various supported platforms. The next pages outline the necessary components and recommended steps for integration within the game engine.

Get Interhaptics for Game Engine SDK

Please enter the required information below to access the SDK

Access GitHub - Download Interhaptics Engine

Articles

Components

The Interhaptics Engine includes the following components required to do in-engine integration. Its two main components are the Haptic Engine and the Device Providers.

  1. Haptic Engine Libraries: These libraries, tailored for each supported architecture, provide the necessary functionality for haptic feedback.
  2. Haptic Engine C++ APIs: A set of C++ APIs that allow developers to interact with the Haptic Engine and control haptic effects within the game application.
  3. Device Provider Libraries: Libraries specific to each supported platform, enabling communication with haptic devices and providing necessary device-related functionality.
  4. Documentation: Detailed documentation explaining the integration process, API references, and usage guidelines.

Integration Process

To successfully integrate the Interhaptics Engine into a game application, the following steps are recommended:

  1. Interhaptics Engine Library Integration: This step involves integrating the Interhaptics Engine library into the game application. It includes packaging, loading, and initializing the library according to the targeted platform.
  2. Support for .haps File Assets: Enable support for Interhaptics’ proprietary haptic effects (.haps) as game assets, allowing the engine to load and unload these effects during gameplay.
  3. Device Providers Libraries Integration: Integrate the Device Provider libraries into the game application. This step includes packaging, loading, and initializing the libraries for the targeted platform, enabling communication with haptic devices.
  4. Rendering Loop and Provider Loop Integration: Integrate the rendering loop of the game engine with the Provider loop of the Interhaptics Engine. This synchronization ensures proper haptic feedback and maintains compatibility across the supported platforms.

By following these recommended steps, the game engine will gain the following capabilities:

  • Load and unload Interhaptics proprietary effects (.haps) during gameplay.
  • Control haptic sources based on game events.
  • Map the haptic experience across different supported platforms to ensure cross-platform compatibility.

For detailed instructions and guidelines on each integration step, please refer to the accompanying documentation provided with the Interhaptics Engine SDK.

Please note that the Interhaptics Engine SDK supports all platforms officially supported by Interhaptics as shown in the image below. Ensure compatibility with the target platform and refer to the platform-specific documentation for any additional integration requirements or considerations.

Interhaptics Engine Schema

Interhaptics Engine Libraries

The Interhaptics Engine Library is a precompiled C++ library that provides essential functionality for integrating haptic feedback into game applications. It is available for the following platforms:

  • Windows x64
  • PlayStation Prospero (on demand)
  • Xbox UWP (on demand)
  • Switch ARM (on demand)
  • iOS arm64 (on demand)
  • Android arm7 / arm64 (on demand)

Loading and Initialization

Before utilizing the Interhaptics Engine Library, it must be properly loaded and initialized in the game application. The initialization process ensures the library is ready for use and enables access to the available APIs.

Functionality

The Interhaptics Engine Library handles various aspects of haptic feedback, including:

  • Loading and unloading haptic effects: The library manages the loading and unloading of haptic effects, allowing game developers to dynamically control the haptic experience.
  • Control of haptic sources: Developers can utilize the library’s APIs to control haptic sources in response to game events, enhancing the immersive experience.
  • Haptic mixing: The library incorporates haptic mixing capabilities to combine multiple haptic effects and create complex feedback patterns.
  • Haptic rendering: The Interhaptics Engine Library facilitates the rendering of haptic effects, ensuring their accurate representation to provide realistic haptic feedback.

Device Providers

Device Providers are a collection of precompiled libraries responsible for establishing communication between the Interhaptics Engine and haptic APIs of various devices. These libraries facilitate the integration and interoperability between the Interhaptics Engine and supported devices.

Functionality

The device providers handle the following tasks:

  • Device Initialization: If required, the device providers initialize the connected haptic devices, preparing them for interaction with the Interhaptics Engine.
  • Subscription to Rendering Output: The providers subscribe to the Interhaptics Engine’s rendering output, ensuring that haptic feedback is appropriately delivered to the connected devices.
  • Transcoding: The device providers handle the necessary transcoding of haptic data between the Interhaptics Engine and the targeted haptic APIs, ensuring compatibility and seamless communication.

Refer to the Key Concepts section of this documentation for more detailed information on loading, unloading, and rendering processes related to the Interhaptics Engine and device providers, respectively.

Please consult the accompanying documentation for comprehensive instructions and usage guidelines on integrating the Interhaptics Engine Library and supported device providers into your game application.

.haps Files

.haps files are standard text files that store haptic parameters for designed haptic effects. These files utilize the JSON (JavaScript Object Notation) format to represent the haptic effect’s configuration and properties. The Interhaptics Engine relies on .haps files to load and apply specific haptic effects during gameplay.

File Structure and Format

The structure and format of .haps files follows the guidelines specified in the Haptic Composer documentation. You can find comprehensive information about the structure and contents of .haps files by referring to the Interhaptics online documentation at the following link.

Please consult the online documentation to thoroughly understand the .haps file format and how to design haptic effects using the Haptic Composer tool.

Ensure that the .haps files in your game application adhere to the specified structure and format to guarantee proper loading and application of haptic effects by the Interhaptics Engine.

Key Concepts

Articles

Interhaptics Engine and Providers Initialization

To use the Interhaptics Engine, it must be initialized. The following Engine API should be used for initialization:

				
					/// <summary>
	/// Initializes the different components and modules of the Interhaptics Engine:
	/// - Haptic Material Manager: module in charge of loading and storing haptic effects
	/// - Human Avatar Manager: module in charge of mapping between device, human avatar, and experience
	/// - Haptic Event Manager: module in charge of the control of haptic sources
	/// </summary>
	/// <returns>Always true even if a module is not properly initialized.</returns>
	DLLExport bool Init();

To properly finalize the usage of the Interhaptics Engine, it is essential to de-initialize it before quitting the application. The following Engine API is used for de-initialization:

				
						/// <summary>
	/// Cleans the different components and modules of the Interhaptics Engine.
	/// To be called before the application is quit.
	/// </summary>
	DLLExport void Quit();

After initializing the Interhaptics Engine, the device providers must also be initialized. All Provider implementations follow a consistent interface that exposes the following APIs:

				
					extern "C"
{
	DLLExport bool ProviderInit();
	DLLExport bool ProviderIsPresent();
	DLLExport bool ProviderClean();
	DLLExport void ProviderRenderHaptics();
}

ProviderInit handles the initialization process of the specific device’s COM , haptic settings for rendering, and subscription to the Interhaptics Engine. It returns false if the initialization process fails.

ProviderClean is responsible for de-initializing the device’s COM, if necessary, and unsubscribing the provider from the Interhaptics Engine. It returns false if the de-initialization process fails.

Please ensure that the Interhaptics Engine and device providers are initialized and de-initialized correctly to guarantee the proper functioning of the haptic system within the application.

Loading .haps Files

Before the Interhaptics Engine can render a haptic effect, the corresponding .haps file must be loaded into the engine. This requires the ability of the game engine to open and read the contents of the .haps file during runtime. It is recommended to treat .haps files as game assets, similar to sound effects and graphical assets.

To load a haptic effect from a .haps file, use the following Engine API call:

				
						/// <summary>
	/// Adds the content of an .haps file to the Interhaptics Engine for future use.
	/// </summary>
	/// <param name="_content">JSON content of the .haps file to be loaded. Needs to follow Interhaptics .haps format.</param>
	/// <returns>ID of the haptic effect to be used in other engine calls. -1 if loading failed.</returns>
	DLLExport int AddHM(const char* _content);

Haptic Rendering and Provider Loop

The core logic of the Interhaptics Engine involves two main elements: haptic rendering and the device provider loop.

Haptic Rendering

Haptic rendering refers to the computation of haptic buffers during each iteration of the rendering loop, based on the game events. To trigger the rendering of haptic buffers, use the following Engine API call:

				
						/// <summary>
	/// To be called in the application main loop to trigger the rendering of all haptic buffers
	/// at a specific time. The Interhaptics Engine will compare the current time with the last
	/// know value to build buffers large enough to cover frame drops. 
	/// Can be called from the main thread or in a parallel loop. 
	/// Must be called at least once before triggering the device update event. 
	/// </summary>
	/// <param name="_curTime">Current time in seconds.</param>
	/// <returns></returns>
	DLLExport void ComputeAllEvents(double _curTime);

It is important to call ComputeAllEvents() every iteration of the rendering loop, either in the main thread or a parallel thread. This ensures that haptic buffers are generated in real-time based on the subscribed Providers. If no device has subscribed, no buffer will be generated. Refer to the section Interhaptics Engine and Providers Initialization for information on device subscription.

Provider Loop

The provider loop is responsible for rendering the haptic buffers on the devices for playback. All provider implementations follow a common interface, exposing the following APIs:

				
					extern "C"
{
	DLLExport bool ProviderInit();
	DLLExport bool ProviderIsPresent();
	DLLExport bool ProviderClean();
	DLLExport void ProviderRenderHaptics();
}

The ProviderRenderHaptics() API triggers the rendering process for the provider by retrieving the necessary haptic buffers, transcoding them if required, and playing them back on the associated device. This API must be called for all targeted devices.

It is mandatory to call ComputeAllEvents() from the Interhaptics Engine before calling ProviderRenderHaptics() for synchronized haptic rendering. Typically, both APIs are implemented in the same loop, with ComputeAllEvents() called before the ProviderRenderHaptics() calls.

Additionally, you can use ProviderIsPresent() to check the availability of the device before triggering haptic playback. This optional step can help improve performance.

Haptic Sources and Targets

Haptic Sources are essential for linking the Interhaptics Engine to the game mechanics. Similar to audio sources, Haptic sources contain references to haptic effects, a list of targets within range of the source, and parameters such as volumes and offsets.

A haptic source must be linked to a loaded haptic effect. Refer to the section Loading .haps Files for details on loading .haps files.

Stopping a source transitions it to an inactive state, where parameters and targets do not need to be redefined when restarting the source. To completely remove a source, use the related ClearEvent APIs.

A target represents a virtual reference to the location of the haptic event. Instead of targeting a specific device, a haptic source targets a region on the human avatar, which can be a single body part or a group of body parts. This system acts as a mapping layer between the haptic experience and the cross-platform ecosystem of haptic devices. It ensures that a implemented haptic experience can be ported to a different haptic system without the need for re-implementing the experience.

Providers declare to the game engine which targets they support. If a haptic source is playing on a target not referenced by any provider, the output can either be ignored or remapped based on requirements.

For more details on the control of haptic sources and construction of targets, please refer to section Engine Control of the documentation.

Engine Control

Articles

Init 

				
					bool Init();

Initializes the different components and modules of the Interhaptics Engine. This function should be called before any other API function is used.

Returns: Always returns true, even if a module is not properly initialized.

Quit 

				
					void Quit();

Cleans up the different components and modules of the Interhaptics Engine. This function should be called before the application is quit.

AddHM 

				
					int AddHM(const char* _content);
  • Adds the content of a .haps file to the Interhaptics Engine for future use.

Parameters

  • _content: JSON content of the .haps file to be loaded. It needs to follow the Interhaptics .haps format.

Returns: The ID of the haptic effect if loading is successful, or -1 if loading failed.

AddParametricEffect 

				
					int AddParametricEffect(double* _amplitude, int _amplitudeSize, double* _pitch, int _pitchSize, double _pitchMin, double _pitchMax, double* _transient, int _transientSize, bool _isLooping);
  • Creates a haptic effect by processing parameters such as amplitude, pitch, and transients. This function generates a haptic effect based on the given input parameters and can optionally loop iy.
Parameters
  • double* _amplitude: An array of amplitude values. The array should be formatted as Time – Value pairs, where each Value is between 0 and 1.
  • int _amplitudeSize: The size of the amplitude array.
  • double* _pitch: An array of pitch values. The array should be formatted as Time – Value pairs, where each Value is between 0 and 1.
  • int _pitchSize: The size of the pitch array.
  • double _freqMin: The minimum value for the frequency range.
  • double _freqMax: The maximum value for the frequency range.
  • double* _transient: An array of transient values. The array should be formatted as Time – Amplitude – Pitch triplets, with both Amplitude and Pitch values ranging between 0 and 1.
  • int _transientSize: The size of the transient array.
  • bool _isLooping: Indicates whether the audio effect should loop.
Returns
  • ID of the haptic effect created.

UpdateHM 

				
					bool UpdateHM(int _hMaterialID, const char* _content);

Replaces the content of an already loaded haptic effect. This function is useful when the ID of the haptic effect needs to be persistent.

Parameters

  • _hMaterialID: ID of the haptic effect to be replaced.
  • _content: JSON content of the .haps file to be loaded. It needs to follow the Interhaptics .haps format.

Returns: true if the effect was properly updated, false otherwise.

GetGlobalIntensity 

				
					double GetGlobalIntensity();
  • Gets the global rendering intensity factor for the whole engine.

Returns: The global intensity. -1 if mixer is not initialized.

SetGlobalIntensity 

				
					void SetGlobalIntensity(double _intensity);
  • Sets the global rendering intensity factor for the whole engine.

Parameters

  • _intensity: Positive value. 0 is nothing. Base value is 1.

 

Shared Types

The SharedTypes.h file defines various enumerations and a structure within the Interhaptics::HapticBodyMapping namespace. These types are used to represent shared types and constants related to haptic body mapping.

Articles

Operator

This enumeration represents operators used in the haptic body mapping. The possible values are:

  • Minus: Represents a minus operator (-1)
  • Neutral: Represents a neutral operator (0)
  • Plus: Represents a plus operator (1)

LateralFlag

This enumeration represents the lateral position of a body part. The possible values are:

  • Unknown_position: Represents an unknown position (-1)
  • Global: Represents the global position (0)
  • Right: Represents the right position (1)
  • Left: Represents the left position (2)
  • Center: Represents the center position (3)

GroupID

The GroupID enumeration represents the group IDs for different body parts. Each group has a unique ID assigned to it for grouping purposes. The following are some of the groups and their corresponding IDs:

  • Unknown: Represents an unknown group. ID: -1
  • All: Represents all body parts. ID: 0
  • Top: Represents the top portion of the body. ID: 100
  • Down: Represents the lower portion of the body. ID: 101
  • Arm: Represents the arm group. ID: 200
  • Head: Represents the head group. ID: 201
  • Chest: Represents the chest group. ID: 202
  • Waist: Represents the waist group. ID: 203
  • Leg: Represents the leg group. ID: 204
  • Upper_arm: Represents the upper arm group. ID: 300
  • Lower_arm: Represents the lower arm group. ID: 301
  • Hand: Represents the hand group. ID: 302
  • Skull: Represents the skull group. ID: 303
  • Neck: Represents the neck group. ID: 304
  • Upper_leg: Represents the upper leg group. ID: 305
  • Lower_leg: Represents the lower leg group. ID: 306
  • Foot: Represents the foot group. ID: 307
  • Palm: Represents the palm group. ID: 400
  • Finger: Represents the finger group. ID: 401
  • Sole: Represents the sole group. ID: 402
  • Toe: Represents the toe group. ID: 403
  • Thumb: Represents the thumb group. ID: 500
  • Index: Represents the index finger group. ID: 501
  • Middle: Represents the middle finger group. ID: 502
  • Ring: Represents the ring finger group. ID: 503
  • Pinky: Represents the pinky finger group. ID: 504
  • Hallux: Represents the hallux group. ID: 505
  • Index_toe: Represents the index toe group. ID: 506
  • Middle_toe: Represents the middle toe group. ID: 507
  • Ring_toe: Represents the ring toe group. ID: 508
  • Pinky_toe: Represents the pinky toe group. ID: 509
  • First: Represents the first segment group. ID: 600
  • Second: Represents the second segment group. ID: 601
  • Third: Represents the third segment group. ID: 602

This enumeration consists of various group IDs that help categorize different body parts based on their grouping characteristics.

CommandData 

				
					// recommended constructor 
CommandData(Operator _sign, GroupID _group, LateralFlag _side = Global)
	{
		Sign = _sign;
		Group = _group;
		Side = _side;
	}

This structure represents an instruction that is useful for finding the body part to render. It contains the following members:

  • Sign: Represents the sign of the operation (+/-) of type Operator.
  • Group: Represents the group targeted of type GroupID.
  • Side: Represents the side targeted of type LateralFlag.

The structure provides a recommended constructor to initialize the members.

Engine Events

Articles

PlayEvent 

				
					void PlayEvent(int _hMaterialID, double _vibrationOffset, double _textureOffset, double _stiffnessOffset);

Starts the rendering playback of a haptic source. It sets the starting time to 0 plus different offsets. If the event is already playing, it restarts with the new offsets. If the source does not already exist, it will be created.

Parameters

  • _hMaterialID: ID of the source to play, which is the same as the attached haptic effect.
  • _vibrationOffset: Vibration offset for the source.
  • _textureOffset: Texture offset for the source.
  • _stiffnessOffset: Stiffness offset for the source.

StopEvent 

				
					void StopEvent(int _hMaterialID);

Stops the rendering playback of a haptic source.

Parameters

  • _hMaterialID: ID of the source to stop, which is the same as the attached haptic effect.

 

StopAllEvents 

				
					void StopAllEvents();
  • Stops the rendering playback of all haptic sources.

AddTargetToEvent 

				
					void AddTargetToEvent(int _hMaterialID, std::vector<CommandData> _target);

Adds a target within the range of the source. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.

Parameters

  • _hMaterialID: ID of the source to add a target to, which is the same as the attached haptic effect.
  • _target: Vector of CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags.

 

AddTargetToEventMarshal 

				
					void AddTargetToEventMarshal(int _hMaterialID, CommandData* _target, int _size);

Marshal version of the AddTargetToEvent function. Adds a target within the range of the source. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.

Parameters

  • _hMaterialID: ID of the source to add a target to, which is the same as the attached haptic effect.
  • _target: Pointer of CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags. Memory must be allocated before calling this entry point.
  • _size: Size of the _target array.

RemoveTargetFromEvent 

				
					void RemoveTargetFromEvent(int _hMaterialID, std::vector<CommandData> _target);

Removes a target from a source range. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.

Parameters

  • _hMaterialID: ID of the source to remove a target from, which is the same as the attached haptic effect.
  • _target: Vector of CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags. Only perfectly matching targets will be removed.

 

RemoveTargetFromEventMarshal 

				
					void RemoveTargetFromEventMarshal(int _hMaterialID, CommandData* _target, int _size);

Marshal version of the RemoveTargetFromEvent function. Removes a target from a source range. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.

Parameters

  • _hMaterialID: ID of the source to remove a target from, which is the same as the attached haptic effect.
  • _target: Pointer of CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags. Only perfectly matching targets will be removed. Memory must be allocated before calling this entry point.
  • _size: Size of the _target array.

RemoveAllTargetsFromEvent 

				
					void RemoveAllTargetsFromEvent(int _hMaterialID);

 

Removes all targets from a source range. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.

Parameters

  • _hMaterialID: ID of the source to remove all targets from, which is the same as the attached haptic effect.

 

ComputeAllEvents 

				
					void ComputeAllEvents(double _curTime);

To be called in the application main loop to trigger the rendering of all haptic buffers at a specific time. The Interhaptics Engine will compare the current time with the last known value to build a buffer large enough to cover frame drops. This function can be called from the main thread or in a parallel loop. It must be called at least once before triggering the device update event.

Parameters

  • _curTime: Current time in seconds.

 

UpdateEventPositions 

				
					void UpdateEventPositions(int _hMaterialID, std::vector<CommandData> _target, double _texturePosition, double _stiffnessPosition);

Updates spatial positions for a specific source target.

Parameters

  • _hMaterialID: ID of the source, which is the same as the attached haptic effect.
  • _target: Vector of CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags. Only perfectly matching targets will be updated.
  • _texturePosition: New texture position.
  • _stiffnessPosition: New stiffness position.

 

UpdateEventPositionsMarshal 

				
					void UpdateEventPositionsMarshal(int _hMaterialID, CommandData* _target, int _size, double _texturePosition, double _stiffnessPosition);

Marshal version of the UpdateEventPositions function. Updates spatial positions for a specific source target.

Parameters

  • _hMaterialID: ID of the source, which is the same as the attached haptic effect.
  • _target: Pointer of CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags. Only perfectly matching targets will be updated. Memory must be allocated before calling this function.
  • _size: Size of the _target array.
  • _texturePosition: New texture position.
  • _stiffnessPosition: New stiffness position.

SetEventIntensity 

				
					void SetEventIntensity(int _hMaterialID, double _intensity);
  • Sets the haptics intensity factor for a specific haptic source.

Parameters

  • int _hMaterialID: The identifier of the haptic effect.
  • double _intensity: The new intensity factor for the haptic effect, which is always clamped to be above 0.

SetTargetIntensity 

				
					void SetTargetIntensity(int _hMaterialID, std::vector<CommandData> _target, double _intensity);

Sets the haptics intensity factor for a specific target within a haptic source.

Parameters

  • int _hMaterialID: The identifier of the haptic source.
  • std::vector<CommandData> _target: The target for the intensity change.
  • double _intensity: The new intensity factor for the target, always clamped to be above 0.

SetTargetIntensityMarshal 

				
					void SetTargetIntensityMarshal(int _hMaterialID, CommandData* _target, int _size, double _intensity);
  • Sets the haptics intensity factor for a specific target of a source using a marshaling technique.

Parameters

  • int _hMaterialID: The identifier of the haptic source.
  • CommandData* _target: The pointer to the target data array.
  • int _size: The size of the target data array.
  • double _intensity: The new intensity factor for the target, always clamped to be above 0.

SetEventLoop 

				
					void SetEventLoop(int _hMaterialID, bool _isLooping);

Sets the loop flag for a specific haptic effect.

Parameters

  • int _hMaterialID: The identifier of the haptic effect.
  • bool _isLooping: A boolean value indicating whether the haptic effect should loop.

SetEventOffsets 

				
					void SetEventOffsets(int _hMaterialID, double _vibrationOffset, double _textureOffset, double _stiffnessOffset);

Sets the offsets for a specific haptic source.

Parameters

  • _hMaterialID: ID of the source, which is the same as the attached haptic effect.
  • _vibrationOffset: Vibration offset.
  • _textureOffset: Texture offset.
  • _stiffnessOffset: Stiffness offset.

 

ClearInactiveEvents 

				
					void ClearInactiveEvents();

Clears all inactive sources from memory. Inactive sources are kept in memory to avoid deletion and re-creation when playing and stopping a source.

ClearActiveEvents 

				
					void ClearActiveEvents();

Clears all active sources from memory. Deleted sources can be recreated by calling the PlayEvent function.

 

ClearEvent 

				
					void ClearEvent(int _hMaterialID);

Clears a specific haptic source, whether it is active or not.

Parameters:

  • _hMaterialID: ID of the source, which is the same as the attached haptic effect.