HIDFunc:
Filter:
Classes | External Control > HID

HIDFunc : AbstractResponderFunc : Object

Fast responder for incoming data from human input devices (HID)
Source: HIDFunc.sc
Subclasses: HIDdef

Description

Human input devices can be used as controllers for making music. This class provides you with access to them in a way similar to OSCFunc and MIDIFunc.

HIDFunc (and its subclass HIDdef) registers one or more functions to respond to an incoming HID message. Many of its methods are inherited from its superclass AbstractResponderFunc.

NOTE: HIDFuncs are removed on Cmd-. by default. This can be overridden using either of the fix or permanent methods.

The development of this SuperCollider implementation of HID access was funded by the SuperCollider community and BEK, Bergen Elektronisk Kunst, Bergen, Norway, http://www.bek.no

Class Methods

HIDFunc.defaultDispatchers

HIDFunc.defaultDispatchers = value

Get or set an IdentityDictionary containing the default dispatcher objects for HIDFuncs of different types (these are what you get if you pass nil as the dispatcher argument to *new). These objects will decide if any of their registered HIDFuncs should respond to an incoming HID message. The dictionary should have the keys [\usage, \usageID, \device, \proto, \element] and values of an appropriate subclass of AbstractDispatcher for each message type. By default these will be instances of HIDUsageDispatcher, HIDElementProtoDispatcher, HIDDeviceDispatcher, HIDElementProtoDispatcher and HIDElementDispatcher respectively.

Returns:

The getter returns an IdentityDictionary.

HIDFunc.usage(func, elUsageName, devUsageName, deviceInfo, argTemplate, argTemplateType, dispatcher)

A convenience method to filter an incoming HID value based on the name of its control usage. E.g. the name of an X-axis of a joystick or the horizontal movement of a mouse has the name \X. These usage names are standardized by manufacturers and are looked up in usage tables based on the information coming from the device. If you have an open HID device, you can look up the available usages with: ~hid.postUsages.

Arguments:

func

A Function or similar object which will respond to the incoming message. It will be passed...

elUsageName

The name of the usage to look for. This can be one usage name, or an array of usage names. If nil, it will match any usage.

devUsageName

The name of the device usage to look for, e.g. \GamePad or \Mouse. If left blank, the HIDFunc will match any device.

deviceInfo

An IdentityDictionary or HIDProto with a more detailed filtering for a device.

argTemplate

This should be an object that implements the method matchItem. Depending on the argTemplateType, it will be passed either the rawValue of the value of the element to be matched.

argTemplateType

If the argTemplateType is \rawValue (the default) then the matching is done based on the incoming raw value of the element (not mapped according to the logical min and max). Otherwise the matching is done according to the mapped value.

dispatcher

An optional instance of an appropriate subclass of AbstractDispatcher. This can be used to allow for customised dispatching. Normally this should not be needed. The default for this type of HIDFunc is HIDUsageDispatcher

Returns:

A new instance of HIDFunc which responds to a specific element usage and device type.

HIDFunc.device(func, elUsageName, deviceName, deviceInfo, argTemplate, argTemplateType, dispatcher)

A convenience method to filter an incoming HID value based on the name of the device. This type of HIDFunc differs from HIDFunc.usage in that it filter specifically by device name, rather than device usage, otherwise the arguments are the same.

Arguments:

func

A Function or similar object which will respond to the incoming message. It will be passed...

elUsageName

The name of the usage to look for. This can be one usage name, or an array of usage names.

deviceName

The name of the device to look for, note that this has to match the string as returned by the device exactly. You can look this string up in the device list: HID.postAvailable

deviceInfo

An IdentityDictionary or HIDProto with a more detailed filtering for a device.

argTemplate

This should be an object that implements the method matchItem. Depending on the argTemplateType, it will be passed either the rawValue of the value of the element to be matched.

argTemplateType

If the argTemplateType is \rawValue (the default) then the matching is done based on the incoming raw value of the element (not mapped according to the logical min and max). Otherwise the matching is done according to the mapped value.

dispatcher

An optional instance of an appropriate subclass of AbstractDispatcher. This can be used to allow for customised dispatching. Normally this should not be needed. The default for this type of HIDFunc is HIDDeviceDispatcher

Returns:

A new instance of HIDFunc which responds to a specific element usage for a specific device.

HIDFunc.usageID(func, elUsageID, elPageID, deviceName, deviceInfo, argTemplate, argTemplateType, dispatcher)

A convenience method to filter an incoming HID value based on the number of its control usage. If the device is using a non-standard usage number, then this method can be used to look for it. A controls usage is fully specified by the combination of its usage ID and its usage page.

Arguments:

func

A Function or similar object which will respond to the incoming message. It will be passed...usage

elUsageID

The id (an Integer) of the usage to look for. This can be one usage id, or an array of usage ids. If nil, it will match any usage id.

elPageID

The id (an Integer) of the page of the usage to look for. This can be one page id, or an array of page ids.

deviceName

Since this type of HIDFunc is meant for non-standardized controls, you can filter by a specific device name, rather than a general usage, similar to HIDFunc.device

deviceInfo

An IdentityDictionary or HIDProto with a more detailed filtering for a device.

argTemplate

This should be an object that implements the method matchItem. Depending on the argTemplateType, it will be passed either the rawValue of the value of the element to be matched.

argTemplateType

If the argTemplateType is \rawValue (the default) then the matching is done based on the incoming raw value of the element (not mapped according to the logical min and max). Otherwise the matching is done according to the mapped value.

dispatcher

An optional instance of an appropriate subclass of AbstractDispatcher. This can be used to allow for customised dispatching. Normally this should not be needed. The default for this type of HIDFunc is HIDElementProtoDispatcher

Returns:

A new instance of HIDFunc which responds to a specific element usage id for a specific device.

HIDFunc.proto(func, protoElement, deviceInfo, argTemplate, argTemplateType, dispatcher)

A convenience method to filter an incoming HID value based on a matching template of an element (a HIDElementProto). If you have number of conditions for the element that should be matched, then this method can be used to look for it.

Arguments:

func

A Function or similar object which will respond to the incoming message. It will be passed...usage

protoElement

The id (an Integer) of the usage to look for. This can be one usage id, or an array of usage ids.

deviceInfo

An IdentityDictionary or HIDProto with a more detailed filtering for a device.

argTemplate

This should be an object that implements the method matchItem. Depending on the argTemplateType, it will be passed either the rawValue of the value of the element to be matched.

argTemplateType

If the argTemplateType is \rawValue (the default) then the matching is done based on the incoming raw value of the element (not mapped according to the logical min and max). Otherwise the matching is done according to the mapped value.

dispatcher

An optional instance of an appropriate subclass of AbstractDispatcher. This can be used to allow for customised dispatching. Normally this should not be needed. The default for this type of HIDFunc is HIDElementProtoDispatcher

Returns:

A new instance of HIDFunc which responds to a specific prototype element.

HIDFunc.element(func, elID, deviceName, deviceInfo, argTemplate, argTemplateType, dispatcher)

A convenience method to filter an incoming HID value based on the index of its element. If the device is using something non-standard, or you want to access keyboard elements directly, then this method can be used to look for it. Note that the element index is not necessarily the same across different operating systems (i.e. it may vary between Linux and macOS and Windows).

Arguments:

func

A Function or similar object which will respond to the incoming message. It will be passed...

elID

The id (an Integer) of the element to look for. This can be one element id, or an array of element ids.

deviceName

Since this type of HIDFunc is meant for non-standardized elements, you can filter by a specific device name, rather than a general usage, similar to HIDFunc.device

deviceInfo

An IdentityDictionary or HIDProto with a more detailed filtering for a device.

argTemplate

This should be an object that implements the method matchItem. Depending on the argTemplateType, it will be passed either the rawValue of the value of the element to be matched.

argTemplateType

If the argTemplateType is \rawValue (the default) then the matching is done based on the incoming raw value of the element (not mapped according to the logical min and max). Otherwise the matching is done according to the mapped value.

dispatcher

An optional instance of an appropriate subclass of AbstractDispatcher. This can be used to allow for customised dispatching. Normally this should not be needed. The default for this type of HIDFunc is HIDElementDispatcher

Returns:

A new instance of HIDFunc which responds to a specific element id for a specific device.

Debugging

HIDFunc.trace(bool: true)

A convenience method which dumps all incoming HID messages.

Arguments:

bool

A Boolean indicating whether dumping is on or off.

Inherited class methods

Instance Methods

.type

The type of HIDFunc.

Returns:

a Symbol, one of \usage, \device, \usageID, \proto or \element.

.elUsage

The usage name, usage id, or element id of the element/control to match, depending on the type of HIDFunc

.elementTemplate

An instance of HIDElementProto, describing the template for the element to match.

.devUsage

The device usage or device name of the element/control to match, depending on the type of HIDFunc

.deviceTemplate

An instance of HIDProto, describing the template for the device to match.

.argTemplate

This should be an object that implements the method matchItem. Depending on the argTemplateType, it will be passed either the rawValue of the value of the element to be matched.

.argTemplateType

If the argTemplateType is \rawValue (the default) then the matching is done based on the incoming raw value of the element (not mapped according to the logical min and max). Otherwise the matching is done according to the mapped value.

Inherited instance methods

Examples

For all the examples below here, you will need to have initialized an HID device (see also Working with HID). The examples below should work with a standard USB mouse.

Filtering based on usage

Filtering based on usage ID

Filtering based on a device

Filtering based on a prototype element

Filtering based on an element ID