SkineticSDK

Functions

	Name
const char *	ski_serialNumberToString(uint32_t serialNumber) Convert Skinetic serial number to a formatted string.
int	ski_createSDKInstance(const char * logFileName) Instantiate a new Skinetic SDK.
void	ski_freeSDKInstance(int SKI_ID) Properly free the memory of the associated Skinetic instance.
int	ski_scanDevices(int SKI_ID, ski_output_t outputType) Initialize a scanning routine to find all available Skinetic device.
int	ski_scanStatus(int SKI_ID) Check the status of the asynchronous scanning routine.
ski_device_info_t *	ski_getFirstScannedDevice(int SKI_ID) Get linked list of all the Skinetic devices found during the scan which match the specified output type.
int	ski_connectDevice(int SKI_ID, ski_output_t outputType, uint32_t serialNumber) Initialize an asynchronous connection to a Skinetic device using the selected type of connection.
int	ski_disconnectDevice(int SKI_ID) Disconnect the current Skinetic device.
ski_connection_state_t	ski_connectionStatus(int SKI_ID) Check the current status of the connection.
int	ski_setConnectionCallback(int SKI_ID, ski_ConnectionCallback callback, void userData) Set a callback function fired upon connection changes.
const char *	ski_getSDKVersion(int SKI_ID) Get SDK version as a string.
uint32_t	ski_getSkineticSerialNumber(int SKI_ID) Get the connected device's serial number.
const char *	ski_getSkineticSerialNumberAsString(int SKI_ID) Get the connected device's serial number as string.
const char *	ski_getSkineticVersion(int SKI_ID) Get the connected device's version as a string.
ski_device_type_t	ski_getSkineticType(int SKI_ID) Get the connected device's type.
int	ski_getGlobalIntensityBoost(int SKI_ID) Get the amount of global intensity boost.
int	ski_setGlobalIntensityBoost(int SKI_ID, int globalBoost) Set the amount of global intensity boost.
int	ski_loadPatternFromJSON(int SKI_ID, const char * json) Load a pattern from a valid json into a local haptic asset and return the corresponding patternID.
int	ski_unloadPattern(int SKI_ID, int patternID) Unload the pattern from of the corresponding patternID.
int	ski_getPatternIntensityBoost(int SKI_ID, int patternID) Get the pattern boost value which serves as a default value for the playing effect.
int	ski_setAccumulationWindowToPattern(int SKI_ID, int mainPatternID, int fallbackPatternID, float timeWindow, int maxAccumulation) Enable the effect accumulation strategy on a targeted pattern.
int	ski_eraseAccumulationWindowToPattern(int SKI_ID, int mainPatternID) Disable the effect accumulation strategy on a specific pattern if any set.
void	ski_defaultEffectProperties(ski_effect_properties_t * effect_properties) Initialize the structure with default values.
int	ski_playEffect(int SKI_ID, int patternID, ski_effect_properties_t effectProperties) Play an haptic effect based on a loaded pattern and return the effectID of this instance.
int	ski_stopEffect(int SKI_ID, int effectID, float time) Stop the effect instance identified by its effectID.
ski_effect_state_t	ski_effectState(int SKI_ID, int effectID) Get the current state of an effect.
int	ski_pauseAll(int SKI_ID) Pause all haptic effect that are currently playing.
int	ski_resumeAll(int SKI_ID) Resume the paused haptic effects.
int	ski_stopAll(int SKI_ID)
int	ski_setLogCallback(ski_log_callback_t callback) Set the logging callback function. It should be set before initialisation of the SDK. This callback will be called every time a log message is produced by the SDK.
void	ski_exp_enableLegacyBackend(int SKI_ID, bool enable) Enable legacy backend.
int	ski_exp_connectAsh(int SKI_ID, ski_output_t outputType, uint32_t serialNumber, const char * loopbackInterface) Initialize an asynchronous connection to a Skinetic device and use the ASH-fx library for haptic generation.
void	ski_exp_defaultAudioSettings(ski_audio_settings_t * audioSettings) Initialize the structure with default values.
int	ski_exp_connectAudio(int SKI_ID, ski_audio_preset_t audioPreset, ski_audio_settings_t audioSettings) Initialize an asynchronous connection to an audio device using the provided settings.
int	ski_exp_connectAshAudio(int SKI_ID, ski_audio_preset_t audioPreset, ski_audio_settings_t audioSettings, const char * loopbackInterface) Initialize an asynchronous connection to an audio device and use the ASH-fx library for haptic generation.
int	ski_exp_setAshVolume(int SKI_ID, float volume) Set the volume of the ASH-generated haptic track.
float	ski_exp_getAshVolume(int SKI_ID) Get the volume of the ASH-generated haptic track.
int	ski_exp_getOutputDevicesNames(const char ** devicesNames, int nbDevices) Get names of available output devices.
int	ski_exp_getLoopbackDevicesNames(const char ** devicesNames, int nbDevices) Get names of available input loopback devices.
int	ski_exp_getOutputDeviceAPIs(const char * outputName, const char ** APIs, int nb_APIs) Get available APIs for a given output device identified by name.
int	ski_exp_getOutputDeviceInfo(const char outputName, const char API, int maxChannels, float defaultLowLatency, float * defaultHighLatency) Get settings extremum values of the output device identified by name and API.
int	ski_exp_getSupportedStandardSampleRates(const char outputName, const char API, uint32_t * sampleRates, int nbSampleRates) Get all supported standard sample rates for the output device identified by name and API.

Functions Documentation

function ski_serialNumberToString

 const char * ski_serialNumberToString(
    uint32_t serialNumber
)

Convert Skinetic serial number to a formatted string.

Parameters:

• serialNumber Serial number to convert.

Return: string representation of the serial number.

function ski_createSDKInstance

 int ski_createSDKInstance(
    const char * logFileName
)

Instantiate a new Skinetic SDK.

Parameters:

• logFileName Name of the file to log in. Leave blank to use the default SkineticSDK.log file. File path can be absolute or relative to the directory containing the library.

Return: ID of the instance, -1 if the instance was not created.

function ski_freeSDKInstance

 void ski_freeSDKInstance(
    int SKI_ID
)

Properly free the memory of the associated Skinetic instance.

Parameters:

• SKI_ID ID of the Skinetic instance.

function ski_scanDevices

 int ski_scanDevices(
    int SKI_ID,
    ski_output_t outputType
)

Initialize a scanning routine to find all available Skinetic device.

Parameters:

• SKI_ID ID of the Skinetic instance.
• outputType type of connection to introspect.

Return: 0 on success, an Error code on failure.

The state of the routine can be obtain from ski_scanStatus(). Once completed, the result can be accessed using ski_getFirstScannedDevice().

function ski_scanStatus

 int ski_scanStatus(
    int SKI_ID
)

Check the status of the asynchronous scanning routine.

The method returns:

• '1' if the scan is ongoing.
• '0' if the scan is completed.
• a negative error code if the scan failed. The asynchronous scan routine is terminated on failure. Once the scan is completed, the result can be obtain by calling ski_getFirstScannedDevice(). SKI_IDID of the Skinetic instance.

the current status or an error on failure.

function ski_getFirstScannedDevice

ski_device_info_t * ski_getFirstScannedDevice(
    int SKI_ID
)

Get linked list of all the Skinetic devices found during the scan which match the specified output type.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: a pointer to the first structure in the linked list, nullptr otherwise.

The ski_device_info_t.next field of the structure points to the next found device if any. It is equal to nullptr when the last device is reached.

The returned pointer should neither be modified nor memorized but have to be used immediately to retrieve the devices list. Its life span is only guarantied until scanDevices() is called again.

function ski_connectDevice

 int ski_connectDevice(
    int SKI_ID,
    ski_output_t outputType,
    uint32_t serialNumber
)

Initialize an asynchronous connection to a Skinetic device using the selected type of connection.

Parameters:

• SKI_ID ID of the Skinetic instance.
• outputType type of connection
• serialNumber serial number of the Skinetic device to connect to

Return: 0 on success, an Error code on failure.

The state of the routine can be obtain from ski_connectionStatus(). If the serial number is set to 0, the connection will be performed on the first found device.

function ski_disconnectDevice

 int ski_disconnectDevice(
    int SKI_ID
)

Disconnect the current Skinetic device.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: 0 on success, an Error code on failure.

The disconnection is effective once all resources are released. The state of the routine can be obtain from ski_connectionStatus().

function ski_connectionStatus

ski_connection_state_t ski_connectionStatus(
    int SKI_ID
)

Check the current status of the connection.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: the current status of the connection.

The asynchronous connection routine is terminated on failure.

function ski_setConnectionCallback

 int ski_setConnectionCallback(
    int SKI_ID,
    ski_ConnectionCallback * callback,
    void * userData
)

Set a callback function fired upon connection changes.

Parameters:

• SKI_ID ID of the Skinetic instance.
• callback client's callback.
• userData client's supplied pointer.

Return: 0 on success, an Error code on failure.

Functions of type ski_ConnectionCallback are implemented by clients.

The callback is fired at the end of the connection routine whether it succeed or failed. It is also fired if a connection issue arise upon disconnection. The callback is not fired if none was passed to setConnectionCallback().

'userData' is a client supplied pointer which is passed back when the callback function is called. It could for example, contain a pointer to an class instance that will process the callback.

function ski_getSDKVersion

 const char * ski_getSDKVersion(
    int SKI_ID
)

Get SDK version as a string.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: the version string.

The format of the string is: major.minor.revision

function ski_getSkineticSerialNumber

 uint32_t ski_getSkineticSerialNumber(
    int SKI_ID
)

Get the connected device's serial number.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: the serial number of the connected Skinetic device if any, 0xFFFFFFFF otherwise.

function ski_getSkineticSerialNumberAsString

 const char * ski_getSkineticSerialNumberAsString(
    int SKI_ID
)

Get the connected device's serial number as string.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: the serial number as string of the connected Skinetic device if any, "noDeviceConnected" otherwise.

function ski_getSkineticVersion

 const char * ski_getSkineticVersion(
    int SKI_ID
)

Get the connected device's version as a string.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: the version string if a Skinetic device is connected, "noDeviceConnected" otherwise.

The format of the string is: major.minor.revision

function ski_getSkineticType

ski_device_type_t ski_getSkineticType(
    int SKI_ID
)

Get the connected device's type.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: the type of the connected Skinetic device if it is connected, ski_device_type_t::eUnknown otherwise.

function ski_getGlobalIntensityBoost

 int ski_getGlobalIntensityBoost(
    int SKI_ID
)

Get the amount of global intensity boost.

Return: the global intensity boost, an ERROR otherwise.

The boost increase the overall intensity of all haptic effects. However, the higher the boost activation is, the more the haptic effects are degraded. The global boost is meant to be set by the user as an application setting.

function ski_setGlobalIntensityBoost

 int ski_setGlobalIntensityBoost(
    int SKI_ID,
    int globalBoost
)

Set the amount of global intensity boost.

Parameters:

• globalBoost global boost value.

Return: 0 on success, an ERROR otherwise.

The boost increase the overall intensity of all haptic effects. However, the higher the boost activation is, the more the haptic effects are degraded. The global boost is meant to be set by the user as an application setting.

function ski_loadPatternFromJSON

 int ski_loadPatternFromJSON(
    int SKI_ID,
    const char * json
)

Load a pattern from a valid json into a local haptic asset and return the corresponding patternID.

Parameters:

• SKI_ID ID of the Skinetic instance.
• json describing the pattern.

Return: positive patternID on success, an ERROR otherwise.

The patternID is a positive index.

function ski_unloadPattern

 int ski_unloadPattern(
    int SKI_ID,
    int patternID
)

Unload the pattern from of the corresponding patternID.

Parameters:

• SKI_ID ID of the Skinetic instance.
• patternID the patternID of the pattern to unload.

Return: 0 on success, an ERROR otherwise.

function ski_getPatternIntensityBoost

 int ski_getPatternIntensityBoost(
    int SKI_ID,
    int patternID
)

Get the pattern boost value which serves as a default value for the playing effect.

Parameters:

• SKI_ID ID of the Skinetic instance.
• patternID the ID of the targeted pattern.

Return: the pattern intensity boost of the pattern if it exists, 0 otherwise.

The value is ranged in [-100; 100]. If the pattern ID is invalid, zero is still returned.

function ski_setAccumulationWindowToPattern

 int ski_setAccumulationWindowToPattern(
    int SKI_ID,
    int mainPatternID,
    int fallbackPatternID,
    float timeWindow,
    int maxAccumulation
)

Enable the effect accumulation strategy on a targeted pattern.

Parameters:

• SKI_ID ID of the Skinetic instance.
• mainPatternID the patternID of the main pattern.
• fallbackPatternID the patternID of the fallback pattern
• timeWindow the time window during which the accumulation should happen.
• maxAccumulation max number of extra accumulated effect instances.

Return: 0 on success, an ERROR otherwise.

Whenever an effect is triggered on the main pattern, the fallback one is used instead, if the main is already playing. More details can be found the additional documentation. For the maxAccumulation, setting to 0 removes the limit.

If a new call to this function is done for a specific pattern, the previous association is overridden.

function ski_eraseAccumulationWindowToPattern

 int ski_eraseAccumulationWindowToPattern(
    int SKI_ID,
    int mainPatternID
)

Disable the effect accumulation strategy on a specific pattern if any set.

Parameters:

• SKI_ID ID of the Skinetic instance.
• mainPatternID the patternID of the main pattern.

Return: 0 on success, an ERROR otherwise.

function ski_defaultEffectProperties

 void ski_defaultEffectProperties(
    ski_effect_properties_t * effect_properties
)

Initialize the structure with default values.

Parameters:

• effect_properties ptr to ski_effect_properties_t structure

priority: 5 volume: 100 speed: 1 repeatCount: 1 repeatDelay: 0 playAtTime:0 maxDuration: 0 effectBoost: 0 overridePatternBoost: false height: 0 heading: 0 tilting: 0 frontBackInversion: false upDownInversion: false rightLeftInversion: false frontBackAddition: false upDownAddition: false rightLeftAddition: false

function ski_playEffect

 int ski_playEffect(
    int SKI_ID,
    int patternID,
    ski_effect_properties_t effectProperties
)

Play an haptic effect based on a loaded pattern and return the effectID of this instance.

Parameters:

• SKI_ID ID of the Skinetic instance.
• patternID pattern used by the effect instance.
• effectProperties struct to specialized the effect.

Return: positive effectID on success, an ERROR otherwise.

The instance index is positive. Each call to playEffect() using the same patternID generates a new haptic effect instance totally uncorrelated to the previous ones. The instance is destroyed once it stops playing.

The haptic effect instance reproduces the pattern with variations describes in the structure ski_effect_properties_t. More information on these parameters and how to used them can be found in the structure's description. Transformation and boolean operations are not applicable to actuator-based patterns.

If the pattern is unloaded, the haptic effect is not interrupted.

function ski_stopEffect

 int ski_stopEffect(
    int SKI_ID,
    int effectID,
    float time
)

Stop the effect instance identified by its effectID.

Parameters:

• SKI_ID ID of the Skinetic instance.
• effectID index identifying the effect.
• time duration of the fadeout in second.

Return: 0 on success, an ERROR otherwise.

The effect is stop in "time" seconds with a fadeout to prevent abrupt transition. If "time" is set to 0, no fadeout are applied and the effect is stopped as soon as possible. Once an effect is stopped, its instance is destroyed and its effectID invalidated.

function ski_effectState

ski_effect_state_t ski_effectState(
    int SKI_ID,
    int effectID
)

Get the current state of an effect.

Parameters:

• SKI_ID ID of the Skinetic instance.
• effectID index identifying the effect.

Return: the current state of the effect.

If the effectID is invalid, the 'stop' state will be return.

function ski_pauseAll

 int ski_pauseAll(
    int SKI_ID
)

Pause all haptic effect that are currently playing.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: 0 on success, an ERROR otherwise.

function ski_resumeAll

 int ski_resumeAll(
    int SKI_ID
)

Resume the paused haptic effects.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: 0 on success, an ERROR otherwise.

function ski_stopAll

 int ski_stopAll(
    int SKI_ID
)

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: 0 on success, an ERROR otherwise.

Stop all playing haptic effect.

function ski_setLogCallback

 int ski_setLogCallback(
    ski_log_callback_t callback
)

Set the logging callback function. It should be set before initialisation of the SDK. This callback will be called every time a log message is produced by the SDK.

The callback function takes the following arguments:

• ski_log_level_t level: the level of the log message
• const char* scope: string giving information about the SDK scope that send the log
• const char* msg: string containing the log message Set the callback to NULL to disable logging. callbackthe callback function.

function ski_exp_enableLegacyBackend

 void ski_exp_enableLegacyBackend(
    int SKI_ID,
    bool enable
)

Enable legacy backend.

Parameters:

• SKI_ID ID of the Skinetic instance.
• enable set to true to enable, false otherwise.

If boolean is set to true, the legacy backend is used instead of the default backend.

function ski_exp_connectAsh

 int ski_exp_connectAsh(
    int SKI_ID,
    ski_output_t outputType,
    uint32_t serialNumber,
    const char * loopbackInterface
)

Initialize an asynchronous connection to a Skinetic device and use the ASH-fx library for haptic generation.

Parameters:

• SKI_ID ID of the Skinetic instance.
• outputType type of connection.
• serialNumber serial number of the Skinetic device to connect to
• loopbackInterface input loopback interface.

Return: 0 on success, an Error otherwise.

The ASH-fx library generates haptic signals based on the audio of the targeted input loopback interface. The loopback interfaces can be queried by calling getLoopbackDevicesNames(). Setting loopbackInterface to NULL selects the default audio output device of the system.

function ski_exp_defaultAudioSettings

 void ski_exp_defaultAudioSettings(
    ski_audio_settings_t * audioSettings
)

Initialize the structure with default values.

Parameters:

• audioSettings ptr to ski_audio_settings_t structure

deviceName: "default_output" audioAPI: "any_API" sampleRate: 48000 bufferSize: 256 nbStreamChannel: -1 suggestedLatency: 0

function ski_exp_connectAudio

 int ski_exp_connectAudio(
    int SKI_ID,
    ski_audio_preset_t audioPreset,
    ski_audio_settings_t audioSettings
)

Initialize an asynchronous connection to an audio device using the provided settings.

Parameters:

• SKI_ID ID of the Skinetic instance.
• audioPreset preset of audio device.
• audioSettings audio stream configuration to use.

Return: 0 on success, an Error code on failure.

If audioPreset is set to anything else other than ski_audioPreset_t::eCustomDevice, the provided settings are ignored and the ones corresponding to the preset are used instead.

Notice that this connection is not compatible with the legacy backend.

function ski_exp_connectAshAudio

 int ski_exp_connectAshAudio(
    int SKI_ID,
    ski_audio_preset_t audioPreset,
    ski_audio_settings_t audioSettings,
    const char * loopbackInterface
)

Initialize an asynchronous connection to an audio device and use the ASH-fx library for haptic generation.

Parameters:

• SKI_ID ID of the Skinetic instance.
• audioPreset preset of audio device (for output).
• audioSettings audio stream configuration to use (for output).
• loopbackInterface input loopback interface.

Return: 0 on success, an Error code on failure.

The ASH-fx library generates haptic signals based on the audio of the targeted input loopback interface. The loopback interfaces can be queried by calling getLoopbackDevicesNames(). Setting loopbackInterface to NULL selects the default audio output device of the system.

function ski_exp_setAshVolume

 int ski_exp_setAshVolume(
    int SKI_ID,
    float volume
)

Set the volume of the ASH-generated haptic track.

Parameters:

• SKI_ID ID of the Skinetic instance.
• volume normalized haptic volume.

Return: 0 on success, an Error code on failure.

The volume is normalized and ranged between [0; 1]. Values above 1 can be used but might produce clipping.

function ski_exp_getAshVolume

 float ski_exp_getAshVolume(
    int SKI_ID
)

Get the volume of the ASH-generated haptic track.

Parameters:

• SKI_ID ID of the Skinetic instance.

Return: positive normalized haptic volume, an Error code on failure.

function ski_exp_getOutputDevicesNames

 int ski_exp_getOutputDevicesNames(
    const char *** devicesNames,
    int * nbDevices
)

Get names of available output devices.

Parameters:

• devicesNames pointer to array of const char*.
• nbDevices number of char* in the array.

Return: 0 if the output values have been set successfully, an Error otherwise.

If no device is available, the array will contain "noDevice". This function will set the pointer array of const char *, as well as the size of the array as they are passed by reference.

function ski_exp_getLoopbackDevicesNames

 int ski_exp_getLoopbackDevicesNames(
    const char *** devicesNames,
    int * nbDevices
)

Get names of available input loopback devices.

Parameters:

• devicesNames pointer to array of const char*.
• nbDevices number of char* in the array.

Return: 0 if the output values has been set successfully, an Error otherwise.

This will work only on Windows with the WASAPI API. Each input loopback device correspond to a real output device.

If no device is available, the array will contain "noDevice". This function will set the pointer array of const char *, as well as the size of the array as they are passed by reference.

function ski_exp_getOutputDeviceAPIs

 int ski_exp_getOutputDeviceAPIs(
    const char * outputName,
    const char *** APIs,
    int * nb_APIs
)

Get available APIs for a given output device identified by name.

Parameters:

• outputName name of the output.
• APIs pointer to array of const char*.
• nb_APIs number of char* in the array.

Return: 0 if the output values have been set successfully, an Error otherwise.

If no API is available, the array will contain "noAPI". This function will set the pointer array of const char *, as well as the size of the array as they are passed by reference.

function ski_exp_getOutputDeviceInfo

 int ski_exp_getOutputDeviceInfo(
    const char * outputName,
    const char * API,
    int * maxChannels,
    float * defaultLowLatency,
    float * defaultHighLatency
)

Get settings extremum values of the output device identified by name and API.

Parameters:

• outputName name of the output.
• API name of the API.
• max_channels max number of channel
• default_low_latency minimum latency of the output device
• default_high_latency maximum latency of the output device

Return: 0 if the output values have been set successfully, an Error otherwise.

function ski_exp_getSupportedStandardSampleRates

 int ski_exp_getSupportedStandardSampleRates(
    const char * outputName,
    const char * API,
    uint32_t ** sampleRates,
    int * nbSampleRates
)

Get all supported standard sample rates for the output device identified by name and API.

Parameters:

• outputName name of the output.
• API name of the API.
• sampleRates pointer to array of float.
• nb_sampleRates number of float in the array.

Return: 0 if the output values have been set successfully, an Error otherwise.

This function will set the pointer array of float, as well as the size of the array as they are passed by reference. If the outputName or the API are not valid, an error is returned and the array is filled with all standard sample rates.