Version: Skinetic SDK 1.5.0

Skinetic::SkineticSDK

Public Classes

	Name
struct	DeviceInfo Struct representing device information.
struct	EffectProperties Haptic Structure to describe how effect instances reproduce a pattern with variations.
struct	ExpAudioSettings Experimental - Struct containing settings for an audio connection.

Public Types

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

Public Functions

	Name
string	getSDKError(int error) Describe the error cause.
void	ConnectionClassCallback(ConnectionState status, int error, UInt32 serialNumber, IntPtr userData)
void	LogCallback(LogLevel level, string scope, string message)
String	GetDeviceSerialNumberAsString(UInt32 serialNumber) Convert serial number to a formatted string.
int	SetLogCallback(LogCallbackDelegate callback)
void	InitInstance() Initialize the device instance.
void	DeinitInstance() Deinitialize the device instance.
int	ScanDevices(OutputType output) Initialize a scanning routine to find all available devices.
int	ScanStatus() 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.
int	Connect(OutputType output, System.UInt32 serialNumber) Initialize an asynchronous connection to a device using the selected type of connection.
int	Disconnect() Disconnect the current device.
ConnectionState	ConnectionStatus() Check the current status of the connection. The asynchronous connection routine is terminated on failure.
delegate void	ConnectionCallbackDelegate(ConnectionState state, int error, System.UInt32 serialNumber) Delegate of the connection callback.
delegate void	LogCallbackDelegate(LogLevel level, string scope, string message) Delegate of the log callback.
int	SetConnectionCallback(ConnectionCallbackDelegate callback) Set a callback function fired upon connection changes.
String	GetSDKVersion() Get SDK version as a string.
String	GetDeviceVersion() Get the connected device's version as a string.
System.UInt32	GetDeviceSerialNumber() Get the connected device's serial number.
String	GetDeviceSerialNumberAsString() Get the connected device's serial number as string.
DeviceType	GetDeviceType() Get the connected device's type.
int	GetGlobalIntensityBoost() Get the amount of effect's intensity boost.
int	SetGlobalIntensityBoost(int globalBoost) Set the amount of global intensity boost.
int	LoadPatternFromJSON(String json) Load a pattern from a valid json into a local haptic asset and return the corresponding patternID.
int	UnloadPattern(int patternID) Unload the pattern from of the corresponding patternID.
int	GetPatternIntensityBoost(int patternID) Get the pattern boost value which serves as a default value for the playing effect.
int	SetAccumulationWindowToPattern(int mainPatternID, int fallbackPatternID, float timeWindow, int maxAccumulation) Enable the effect accumulation strategy on a targeted pattern.
int	EraseAccumulationWindowToPattern(int mainPatternID) Disable the effect accumulation strategy on a specific pattern if any set.
int	PlayEffect(int patternID, EffectProperties effectProperties) Play an haptic effect based on a loaded pattern and return the effectID of this instance.
int	StopEffect(int effectID, float time) Stop the effect instance identified by its effectID.
EffectState	GetEffectState(int effectID) Get the current state of an effect.
int	PauseAll() Pause all haptic effect that are currently playing.
int	ResumeAll() Resume the paused haptic effects.
int	StopAll() 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.
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.
int[]	Exp_GetSupportedStandardSampleRates(string outputName, string apiName) Get all supported standard sample rates of the output device identified by name and API.
void	Exp_EnableLegacyBackend(bool enable) Enable legacy backend.
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.
int	Exp_ConnectAudio(ExpAudioPreset audioPreset, ExpAudioSettings audioSettings) Initialize an asynchronous connection to an audio device using the provided settings.
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.
int	Exp_SetAshVolume(float volume) Set the volume of the ASH-generated haptic track.
float	Exp_GetAshVolume() Get the volume of the ASH-generated haptic track.

Public Types Documentation

enum OutputType

Enumerator	Value	Description
E_AUTODETECT	0	Try all available type of connection.
E_BLUETOOTH	1	Bluetooth connection.
E_USB	2	USB connection.
E_WIFI	3	Wifi connection.

Type of connection to device.

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

Bluetooth
USB
WIFI

enum DeviceType

Enumerator	Value	Description
E_UNKNOWN	~0x0	Type is Unknown or undefined.
E_SKINETICVEST	0x01100101	Skinetic Vest.
E_HSDMK2	0x0122FFFF	HSD mk.II development kit.

Type of device.

enum ConnectionState

Enumerator	Value	Description
E_RECONNECTING	3	Device connection was broken, trying to reconnect.
E_DISCONNECTING	2	Device is disconnecting, releasing all resources.
E_CONNECTING	1	Connection to the device is being established, connection routine is active.
E_CONNECTED	0	Device is connected.
E_DISCONNECTED	-1	Device is disconnected.

Connection state.

enum EffectState

Enumerator	Value	Description
E_PLAY	2	Effect is playing.
E_MUTE	1	Effect is muted.
E_INITIALIZED	0	Effect is initialized and should play as soon as possible.
E_STOP	-1	Effect is stopped.

Effect's state.

enum LogLevel

Enumerator	Value	Description
E_TRACE	0	Trace level.
E_DEBUG	1	Debug level.
E_INFO	2	Info level.
E_WARN	3	Warning level.
E_ERR	4	Error level.

Log levels definitions.

enum ExpAudioPreset

Enumerator	Value	Description
E_CUSTOMDEVICE	0	Audio stream with a custom configuration.
E_SKINETIC	1	Autoconfiguration of the audioStream for the Skinetic device.
E_HSDMKI	2	Autoconfiguration of the audioStream for the HSD mk.I device.
E_HSDMKII	3	Autoconfiguration of the audioStream for the HSD mk.II device.
E_HSD0	4	Autoconfiguration 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.

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.

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

Skinetic::SkineticSDK

Public Classes​

Public Types​

Public Functions​

Public Types Documentation​

enum OutputType​

enum DeviceType​

enum ConnectionState​

enum EffectState​

enum LogLevel​

enum ExpAudioPreset​

Public Functions Documentation​

function getSDKError​

function ConnectionClassCallback​

function LogCallback​

function GetDeviceSerialNumberAsString​

function SetLogCallback​

function InitInstance​

function DeinitInstance​

function ScanDevices​

function ScanStatus​

function GetScannedDevices​

function Connect​

function Disconnect​

function ConnectionStatus​

function ConnectionCallbackDelegate​

function LogCallbackDelegate​

function SetConnectionCallback​

function GetSDKVersion​

function GetDeviceVersion​

function GetDeviceSerialNumber​

function GetDeviceSerialNumberAsString​

function GetDeviceType​

function GetGlobalIntensityBoost​

function SetGlobalIntensityBoost​

function LoadPatternFromJSON​

function UnloadPattern​

function GetPatternIntensityBoost​

function SetAccumulationWindowToPattern​

function EraseAccumulationWindowToPattern​

function PlayEffect​

function StopEffect​

function GetEffectState​

function PauseAll​

function ResumeAll​

function StopAll​

function Exp_GetOutputDevicesNames​

function Exp_GetLoopbackDevicesNames​

function Exp_GetOutputDeviceAPIs​

function Exp_GetOutputDeviceInfo​

function Exp_GetSupportedStandardSampleRates​

function Exp_EnableLegacyBackend​

function Exp_ConnectAsh​

function Exp_ConnectAudio​

function Exp_ConnectAshAudio​

function Exp_SetAshVolume​

function Exp_GetAshVolume​

Public Classes

Public Types

Public Functions

Public Types Documentation

enum OutputType

enum DeviceType

enum ConnectionState

enum EffectState

enum LogLevel

enum ExpAudioPreset

Public Functions Documentation

function getSDKError

function ConnectionClassCallback

function LogCallback

function GetDeviceSerialNumberAsString

function SetLogCallback

function InitInstance

function DeinitInstance

function ScanDevices

function ScanStatus

function GetScannedDevices

function Connect

function Disconnect

function ConnectionStatus

function ConnectionCallbackDelegate

function LogCallbackDelegate

function SetConnectionCallback

function GetSDKVersion

function GetDeviceVersion

function GetDeviceSerialNumber

function GetDeviceSerialNumberAsString

function GetDeviceType

function GetGlobalIntensityBoost

function SetGlobalIntensityBoost

function LoadPatternFromJSON

function UnloadPattern

function GetPatternIntensityBoost

function SetAccumulationWindowToPattern

function EraseAccumulationWindowToPattern

function PlayEffect

function StopEffect

function GetEffectState

function PauseAll

function ResumeAll

function StopAll

function Exp_GetOutputDevicesNames

function Exp_GetLoopbackDevicesNames

function Exp_GetOutputDeviceAPIs

function Exp_GetOutputDeviceInfo

function Exp_GetSupportedStandardSampleRates

function Exp_EnableLegacyBackend

function Exp_ConnectAsh

function Exp_ConnectAudio

function Exp_ConnectAshAudio

function Exp_SetAshVolume

function Exp_GetAshVolume