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_ListAshPresets() Get an ordered lists of available ASH-fx generation modes (presets). |
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. |
int | Exp_SetAshPreset(int presetIndex) Set the mode of generation for the ASH-fx library. |
int | Exp_GetAshPreset() Get the current mode of generation for the ASH-fx library. |
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.
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_ListAshPresets
static string[] Exp_ListAshPresets()
Get an ordered lists of available ASH-fx generation modes (presets).
Return: ordered list of preset names
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 Exp_GetOutputDevicesNames
static string[] Exp_GetOutputDevicesNames()
Get names of available audio output devices.
Return: list of device names
If no device is available, the list 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.
function Exp_SetAshPreset
int Exp_SetAshPreset(
int presetIndex
)
Set the mode of generation for the ASH-fx library.
Parameters:
- presetIndex index of the preset to use.
Return: 0 on success, an Error code on failure.
The list of available presets can be listed with ski_exp_listAshPresets
.
function Exp_GetAshPreset
int Exp_GetAshPreset()
Get the current mode of generation for the ASH-fx library.
Return: the current preset index
Updated on 2024-07-11 at 09:47:11 +0000