Skip to main content
Version: Skinetic SDK 1.5.0

Skinetic::SkineticSDK

Public Classes

Name
structDeviceInfo
Struct representing device information.
structEffectProperties
Haptic Structure to describe how effect instances reproduce a pattern with variations.
structExpAudioSettings
Experimental - Struct containing settings for an audio connection.

Public Types

Name
enum classOutputType { E_AUTODETECT = 0, E_BLUETOOTH = 1, E_USB = 2, E_WIFI = 3}
Type of connection to device.
enum classDeviceType { E_UNKNOWN = ~0x0, E_SKINETICVEST = 0x01100101, E_HSDMK2 = 0x0122FFFF}
Type of device.
enum classConnectionState { E_RECONNECTING = 3, E_DISCONNECTING = 2, E_CONNECTING = 1, E_CONNECTED = 0, E_DISCONNECTED = -1}
Connection state.
enum classEffectState { E_PLAY = 2, E_MUTE = 1, E_INITIALIZED = 0, E_STOP = -1}
Effect's state.
enum classLogLevel { E_TRACE = 0, E_DEBUG = 1, E_INFO = 2, E_WARN = 3, E_ERR = 4}
Log levels definitions.
enum classExpAudioPreset { E_CUSTOMDEVICE = 0, E_SKINETIC = 1, E_HSDMKI = 2, E_HSDMKII = 3, E_HSD0 = 4}
Experimental - Preset of audio devices.

Public Functions

Name
stringgetSDKError(int error)
Describe the error cause.
voidConnectionClassCallback(ConnectionState status, int error, UInt32 serialNumber, IntPtr userData)
voidLogCallback(LogLevel level, string scope, string message)
StringGetDeviceSerialNumberAsString(UInt32 serialNumber)
Convert serial number to a formatted string.
intSetLogCallback(LogCallbackDelegate callback)
voidInitInstance()
Initialize the device instance.
voidDeinitInstance()
Deinitialize the device instance.
intScanDevices(OutputType output)
Initialize a scanning routine to find all available devices.
intScanStatus()
Check the status of the asynchronous scanning routine.
List< DeviceInfo >GetScannedDevices()
This function returns a list of all devices found during the scan which match the specified output type.
intConnect(OutputType output, System.UInt32 serialNumber)
Initialize an asynchronous connection to a device using the selected type of connection.
intDisconnect()
Disconnect the current device.
ConnectionStateConnectionStatus()
Check the current status of the connection. The asynchronous connection routine is terminated on failure.
delegate voidConnectionCallbackDelegate(ConnectionState state, int error, System.UInt32 serialNumber)
Delegate of the connection callback.
delegate voidLogCallbackDelegate(LogLevel level, string scope, string message)
Delegate of the log callback.
intSetConnectionCallback(ConnectionCallbackDelegate callback)
Set a callback function fired upon connection changes.
StringGetSDKVersion()
Get SDK version as a string.
StringGetDeviceVersion()
Get the connected device's version as a string.
System.UInt32GetDeviceSerialNumber()
Get the connected device's serial number.
StringGetDeviceSerialNumberAsString()
Get the connected device's serial number as string.
DeviceTypeGetDeviceType()
Get the connected device's type.
intGetGlobalIntensityBoost()
Get the amount of effect's intensity boost.
intSetGlobalIntensityBoost(int globalBoost)
Set the amount of global intensity boost.
intLoadPatternFromJSON(String json)
Load a pattern from a valid json into a local haptic asset and return the corresponding patternID.
intUnloadPattern(int patternID)
Unload the pattern from of the corresponding patternID.
intGetPatternIntensityBoost(int patternID)
Get the pattern boost value which serves as a default value for the playing effect.
intSetAccumulationWindowToPattern(int mainPatternID, int fallbackPatternID, float timeWindow, int maxAccumulation)
Enable the effect accumulation strategy on a targeted pattern.
intEraseAccumulationWindowToPattern(int mainPatternID)
Disable the effect accumulation strategy on a specific pattern if any set.
intPlayEffect(int patternID, EffectProperties effectProperties)
Play an haptic effect based on a loaded pattern and return the effectID of this instance.
intStopEffect(int effectID, float time)
Stop the effect instance identified by its effectID.
EffectStateGetEffectState(int effectID)
Get the current state of an effect.
intPauseAll()
Pause all haptic effect that are currently playing.
intResumeAll()
Resume the paused haptic effects.
intStopAll()
Stop all playing haptic effect.
string[]Exp_GetOutputDevicesNames()
Get names of available audio output devices.
string[]Exp_GetLoopbackDevicesNames()
Get names of available input loopback devices.
string[]Exp_GetOutputDeviceAPIs(string outputName)
Get available APIs for a given output device identified by name.
intExp_GetOutputDeviceInfo(string outputName, string apiName, ref int maxChannels, ref float defaultLowLatency, ref float defaultHighLatency)
Get settings extremum values of the output device identified by name and API.
int[]Exp_GetSupportedStandardSampleRates(string outputName, string apiName)
Get all supported standard sample rates of the output device identified by name and API.
voidExp_EnableLegacyBackend(bool enable)
Enable legacy backend.
intExp_ConnectAsh(OutputType output, System.UInt32 serialNumber, string loopbackInterface)
Initialize an asynchronous connection to a device and use the ASH-fx library for haptic generation.
intExp_ConnectAudio(ExpAudioPreset audioPreset, ExpAudioSettings audioSettings)
Initialize an asynchronous connection to an audio device using the provided settings.
intExp_ConnectAshAudio(ExpAudioPreset audioPreset, ExpAudioSettings audioSettings, string loopbackInterface)
Initialize an asynchronous connection to an audio device and use the ASH-fx library for haptic generation.
intExp_SetAshVolume(float volume)
Set the volume of the ASH-generated haptic track.
floatExp_GetAshVolume()
Get the volume of the ASH-generated haptic track.

Public Types Documentation

enum OutputType

EnumeratorValueDescription
E_AUTODETECT0Try all available type of connection.
E_BLUETOOTH1Bluetooth connection.
E_USB2USB connection.
E_WIFI3Wifi connection.

Type of connection to device.

E_AUTODETECT will try all available type of connection in the following order:

  • Bluetooth
  • USB
  • WIFI

enum DeviceType

EnumeratorValueDescription
E_UNKNOWN~0x0Type is Unknown or undefined.
E_SKINETICVEST0x01100101Skinetic Vest.
E_HSDMK20x0122FFFFHSD mk.II development kit.

Type of device.

enum ConnectionState

EnumeratorValueDescription
E_RECONNECTING3Device connection was broken, trying to reconnect.
E_DISCONNECTING2Device is disconnecting, releasing all resources.
E_CONNECTING1Connection to the device is being established, connection routine is active.
E_CONNECTED0Device is connected.
E_DISCONNECTED-1Device is disconnected.

Connection state.

enum EffectState

EnumeratorValueDescription
E_PLAY2Effect is playing.
E_MUTE1Effect is muted.
E_INITIALIZED0Effect is initialized and should play as soon as possible.
E_STOP-1Effect is stopped.

Effect's state.

enum LogLevel

EnumeratorValueDescription
E_TRACE0Trace level.
E_DEBUG1Debug level.
E_INFO2Info level.
E_WARN3Warning level.
E_ERR4Error level.

Log levels definitions.

enum ExpAudioPreset

EnumeratorValueDescription
E_CUSTOMDEVICE0Audio stream with a custom configuration.
E_SKINETIC1Autoconfiguration of the audioStream for the Skinetic device.
E_HSDMKI2Autoconfiguration of the audioStream for the HSD mk.I device.
E_HSDMKII3Autoconfiguration of the audioStream for the HSD mk.II device.
E_HSD04Autoconfiguration of the audioStream for the HSD 0 device.

Experimental - Preset of audio devices.

E_CUSTOMDEVICE is to be used for a custom configuration.

Public Functions Documentation

function getSDKError

static string getSDKError(
int error
)

Describe the error cause.

Parameters:

  • error value

Return: Error message.

function ConnectionClassCallback

static void ConnectionClassCallback(
ConnectionState status,
int error,
UInt32 serialNumber,
IntPtr userData
)

function LogCallback

static void LogCallback(
LogLevel level,
string scope,
string message
)

function GetDeviceSerialNumberAsString

static String GetDeviceSerialNumberAsString(
UInt32 serialNumber
)

Convert serial number to a formatted string.

Parameters:

  • serialNumber serial number to convert

Return: string representation of the serial number

function SetLogCallback

static int SetLogCallback(
LogCallbackDelegate callback
)

function InitInstance

void InitInstance()

Initialize the device instance.

function DeinitInstance

void DeinitInstance()

Deinitialize the device instance.

function ScanDevices

int ScanDevices(
OutputType output
)

Initialize a scanning routine to find all available devices.

Parameters:

  • output

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

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

function ScanStatus

int ScanStatus()

Check the status of the asynchronous scanning routine.

Return: the current status or an error on failure.

The method returns:

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

function GetScannedDevices

List< DeviceInfo > GetScannedDevices()

This function returns a list of all devices found during the scan which match the specified output type.

Return: a list of devices, empty if no match or an error occurs.

function Connect

int Connect(
OutputType output,
System.UInt32 serialNumber
)

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

Parameters:

  • output output type
  • serialNumber serial number of the device to connect to

Return: 0 on success, an error otherwise.

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

function Disconnect

int Disconnect()

Disconnect the current device.

Return: 0 on success, an error otherwise.

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

function ConnectionStatus

ConnectionState ConnectionStatus()

Check the current status of the connection. The asynchronous connection routine is terminated on failure.

Return: the current status of the connection.

function ConnectionCallbackDelegate

delegate void ConnectionCallbackDelegate(
ConnectionState state,
int error,
System.UInt32 serialNumber
)

Delegate of the connection callback.

Parameters:

  • state status of the connection
  • error of error occurring
  • serialNumber serial number of the device firing the callback

Functions of type ski_ConnectionCallback are implemented by clients. The callback is fired at the end of the connection routine whether it succeeds or failed. It is also fired if a connection issue arise.

function LogCallbackDelegate

delegate void LogCallbackDelegate(
LogLevel level,
string scope,
string message
)

Delegate of the log callback.

Parameters:

  • level level of the log message
  • scope string giving information about the SDK scope that send the log
  • message string containing the log message

Functions of type ski_LogCallback are implemented by clients. The callback is fired for each logging entry.

function SetConnectionCallback

int SetConnectionCallback(
ConnectionCallbackDelegate callback
)

Set a callback function fired upon connection changes.

Parameters:

  • callback client's callback

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. 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 GetSDKVersion

String GetSDKVersion()

Get SDK version as a string.

Return: The version string.

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

function GetDeviceVersion

String GetDeviceVersion()

Get the connected device's version as a string.

Return: The version string if a device is connected, an error message otherwise.

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

function GetDeviceSerialNumber

System.UInt32 GetDeviceSerialNumber()

Get the connected device's serial number.

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

function GetDeviceSerialNumberAsString

String GetDeviceSerialNumberAsString()

Get the connected device's serial number as string.

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

function GetDeviceType

DeviceType GetDeviceType()

Get the connected device's type.

Return: The type of the connected device if it is connected, an ERROR message otherwise.

function GetGlobalIntensityBoost

int GetGlobalIntensityBoost()

Get the amount of effect's intensity boost.

Return: The percentage of effect's 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 SetGlobalIntensityBoost

int SetGlobalIntensityBoost(
int globalBoost
)

Set the amount of global intensity boost.

Parameters:

  • globalBoost boostPercent percentage of the boost.

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 LoadPatternFromJSON

int LoadPatternFromJSON(
String json
)

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

Parameters:

  • json describing the pattern

Return: Positive patternID on success, an error otherwise.

The patternID is a positive index.

function UnloadPattern

int UnloadPattern(
int patternID
)

Unload the pattern from of the corresponding patternID.

Parameters:

  • patternID the patternID of the pattern to unload.

Return: 0 on success, an error otherwise.

function GetPatternIntensityBoost

int GetPatternIntensityBoost(
int patternID
)

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

Parameters:

  • 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 SetAccumulationWindowToPattern

int SetAccumulationWindowToPattern(
int mainPatternID,
int fallbackPatternID,
float timeWindow,
int maxAccumulation
)

Enable the effect accumulation strategy on a targeted pattern.

Parameters:

  • 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 EraseAccumulationWindowToPattern

int EraseAccumulationWindowToPattern(
int mainPatternID
)

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

Parameters:

  • mainPatternID the patternID of the main pattern.

Return: 0 on success, an ERROR otherwise.

function PlayEffect

int PlayEffect(
int patternID,
EffectProperties effectProperties
)

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

Parameters:

  • 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 StopEffect

int StopEffect(
int effectID,
float time
)

Stop the effect instance identified by its effectID.

Parameters:

  • 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 fade out 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, it is instance is destroyed and its effectID invalidated.

function GetEffectState

EffectState GetEffectState(
int effectID
)

Get the current state of an effect.

Parameters:

  • effectID index identifying the effect.

Return: the current state of the effect.

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

function PauseAll

int PauseAll()

Pause all haptic effect that are currently playing.

Return: 0 on success, an error otherwise.

function ResumeAll

int ResumeAll()

Resume the paused haptic effects.

Return: 0 on success, an error otherwise.

function StopAll

int StopAll()

Stop all playing haptic effect.

Return: 0 on success, an error otherwise.

function Exp_GetOutputDevicesNames

static string[] Exp_GetOutputDevicesNames()

Get names of available audio output devices.

Return: array of device names

If no device is available, the array will contain "noDevice". This allows to select which device to use if initializing the context with eCustomDevice.

function Exp_GetLoopbackDevicesNames

static string[] Exp_GetLoopbackDevicesNames()

Get names of available input loopback devices.

Return: array of device names

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".

function Exp_GetOutputDeviceAPIs

static string[] Exp_GetOutputDeviceAPIs(
string outputName
)

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

Parameters:

  • outputName name of the output

Return: array of api names

If no API is available, the array will contain "noAPI".

function Exp_GetOutputDeviceInfo

static int Exp_GetOutputDeviceInfo(
string outputName,
string apiName,
ref int maxChannels,
ref float defaultLowLatency,
ref float defaultHighLatency
)

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

Parameters:

  • outputName name of the output
  • apiName name of the API
  • maxChannels max number of channel
  • defaultLowLatency minimum latency of the output device
  • defaultHighLatency maximum latency of the output device

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

function Exp_GetSupportedStandardSampleRates

static int[] Exp_GetSupportedStandardSampleRates(
string outputName,
string apiName
)

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

Parameters:

  • outputName name of the output
  • apiName name of the API

Return: array of available frame rates

If the outputName or the API are not valid, the array is filled with all standard sample rates.

function Exp_EnableLegacyBackend

void Exp_EnableLegacyBackend(
bool enable
)

Enable legacy backend.

Parameters:

  • 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 Exp_ConnectAsh

int Exp_ConnectAsh(
OutputType output,
System.UInt32 serialNumber,
string loopbackInterface
)

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

Parameters:

  • output output type
  • serialNumber serial number of the 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 Exp_ConnectAudio

int Exp_ConnectAudio(
ExpAudioPreset audioPreset,
ExpAudioSettings audioSettings
)

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

Parameters:

  • audioPreset preset of audio device.
  • audioSettings stream settings

Return: 0 on success, an error otherwise.

If audioPreset is set to anything else other than ExpAudioPreset.E_CUSTOMDEVICE, 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 Exp_ConnectAshAudio

int Exp_ConnectAshAudio(
ExpAudioPreset audioPreset,
ExpAudioSettings audioSettings,
string loopbackInterface
)

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

Parameters:

  • audioPreset preset of audio device.
  • audioSettings stream settings
  • 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. If audioPreset is set to anything else other than ExpAudioPreset.E_CUSTOMDEVICE, the provided settings are ignored and the ones corresponding to the preset are used instead.

function Exp_SetAshVolume

int Exp_SetAshVolume(
float volume
)

Set the volume of the ASH-generated haptic track.

Parameters:

  • volume haptic normalized volume

Return: 0 on success, an error otherwise.

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

function Exp_GetAshVolume

float Exp_GetAshVolume()

Get the volume of the ASH-generated haptic track.

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


Updated on 2024-06-05 at 16:05:52 +0000