carb::input::IInput

struct IInput

Defines an input interface.

Input plugin allows user to listen to the input devices, but it is not intended to work with the input hardware. The input hardware processing is delegated to the input providers, which should be implemented as a separate plugins. Input providers create logical input devices. For example, a window may have a keyboard and mouse associated with it, i.e. a physical keyboard state may be different from a logical keyboard associated with a window, due to some physical key state changes being sent to a different window.

Everything to be used by input providers is put into the InputProvider struct in the separate file. All the functions from Input.h is meant to be used by input consumers (end user).

User can subscribe to the device events, as well as device connection events, and upon subscribing to device connection events, user immediately receives “connect” notifications for all already present events of the kind. Similar is true for unsubscribing - user will immediately get “disconnect” notifications for all still present events.

One notable feature of device handling is that there is no logical difference between a button(key) and an axis: both can be either polled by value, producing floating-point value, or by button flags, which allow to treat analog inputs as buttons (one example is treat gamepad stick as discrete d-pad).

The plugins also allows to map actions to device inputs, allowing to set up multiple slots per action mapping. Those actions could be polled in a similar manner (i.e. by value or as button flags).

Public Functions

inline SubscriptionId subscribeToInputEvents(InputDevice *device, EventTypeMask events, OnInputEventFn fn, void *userData, SubscriptionOrder order = kSubscriptionOrderDefault)

Subscribes plugin user to the input event stream for a specified device.

Parameters

device – Input device, or nullptr if subscription to events from all devices is desired.
events – A bit mask to event types to subscribe to. Currently kEventTypeAll is only supported.
fn – Callback function to be called on received event.
userData – Pointer to the user data to be passed into the callback.
order – Subscriber position hint [0..N-1] from the beginning, [-1, -N] from the end (-1 is default).

Returns

Subscription identifier.

Public Members

InputProvider *(*getInputProvider)()

Gets the input provider’s part of the input interface.

Return: Input provider interface.

void (*startup)(): Start processing input.

void (*shutdown)(): Shutdown and stop processing input.

const char *(*getKeyboardName)(Keyboard *keyboard)

Get keyboard logical device name.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use getDeviceName instead.

Param keyboard: Logical keyboard.
Return: Specified keyboard logical device name string.

SubscriptionId (*subscribeToKeyboardEvents)(Keyboard *keyboard, OnKeyboardEventFn fn, void *userData)

Subscribes plugin user to the keyboard event stream for a specified keyboard.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use subscribeToInputEvents instead.

Param keyboard: Logical keyboard, or nullptr if subscription to events from all keyboards is desired.
Param fn: Callback function to be called on received event.
Param userData: Pointer to the user data to be passed into the callback.
Return: Subscription identifier.

void (*unsubscribeToKeyboardEvents)(Keyboard *keyboard, SubscriptionId id)

Unsubscribes plugin user from the keyboard event stream for a specified keyboard.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use unsubscribeToInputEvents instead.

Param keyboard: Logical keyboard.
Param subscriptionId: Subscription identifier.

float (*getKeyboardValue)(Keyboard *keyboard, KeyboardInput input)

Gets the value for the specified keyboard input kind or number of keys that are pressed.

Param keyboard: Logical keyboard or nullptr to test all keyboards.
Param input: Keyboard input kind (key) to test, or KeyboardInput::eCount to count the number of keys down.
Return: Specified keyboard input value when key is specific, or count of keys pressed for KeyboardInput::eCount.

ButtonFlags (*getKeyboardButtonFlags)(Keyboard *keyboard, KeyboardInput input)

Gets the button flag for the specified keyboard input kind.

Each input is treated as button, based on the press threshold.

Param keyboard: Logical keyboard.
Param input: Keyboard input kind (key).
Return: Specified keyboard input as button flags.

const char *(*getMouseName)(Mouse *mouse)

Get mouse logical device name.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use getDeviceName instead.

Param mouse: Logical mouse.
Return: Specified mouse logical device name string.

float (*getMouseValue)(Mouse *mouse, MouseInput input)

Gets the value for the specified mouse input kind.

Param mouse: Logical mouse.
Param input: Mouse input kind (button/axis).
Return: Specified mouse input value.

ButtonFlags (*getMouseButtonFlags)(Mouse *mouse, MouseInput input)

Gets the button flag for the specified mouse input kind.

Each input is treated as button, based on the press threshold.

Param mouse: Logical mouse.
Param input: Mouse input kind (button/axis).
Return: Specified mouse input as button flags.

Float2 (*getMouseCoordsNormalized)(Mouse *mouse)

Gets the mouse coordinates for the specified mouse, normalized by the associated window size.

Param mouse: Logical mouse.
Return: Coordinates.

Float2 (*getMouseCoordsPixel)(Mouse *mouse)

Gets the absolute mouse coordinates for the specified mouse.

Param mouse: Logical mouse.
Return: Coordinates.

SubscriptionId (*subscribeToMouseEvents)(Mouse *mouse, OnMouseEventFn fn, void *userData)

Subscribes plugin user to the mouse event stream for a specified mouse.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use subscribeToInputEvents instead.

Param mouse: Logical mouse, or nullptr if subscription to events from all mice is desired.
Param fn: Callback function to be called on received event.
Param userData: Pointer to the user data to be passed into the callback.
Return: Subscription identifier.

void (*unsubscribeToMouseEvents)(Mouse *mouse, SubscriptionId id)

Unsubscribes plugin user from the mouse event stream for a specified mouse.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use unsubscribeToInputEvents instead.

Param mouse: Logical mouse.
Param subscriptionId: Subscription identifier.

const char *(*getGamepadName)(Gamepad *gamepad)

Get gamepad logical device name.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use getDeviceName instead.

Param gamepad: Logical gamepad.
Return: Specified gamepad logical device name string.

const char *(*getGamepadGuid)(Gamepad *gamepad)

Get gamepad GUID.

Param gamepad: Logical gamepad.
Return: Specified gamepad logical device GUID.

float (*getGamepadValue)(Gamepad *gamepad, GamepadInput input)

Gets the value for the specified gamepad input kind.

Param gamepad: Logical gamepad.
Param input: Gamepad input kind (button/axis).
Return: Specified gamepad input value.

ButtonFlags (*getGamepadButtonFlags)(Gamepad *gamepad, GamepadInput input)

Gets the button flag for the specified gamepad input kind.

Each input is treated as button, based on the press threshold.

Param gamepad: Logical gamepad.
Param input: Gamepad input kind (button/axis).
Return: Specified gamepad input as button flags.

SubscriptionId (*subscribeToGamepadEvents)(Gamepad *gamepad, OnGamepadEventFn fn, void *userData)

Subscribes plugin user to the gamepad event stream for a specified gamepad.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use subscribeToInputEvents instead.

Param gamepad: Logical gamepad, or nullptr if subscription to events from all gamepads is desired.
Param fn: Callback function to be called on received event.
Param userData: Pointer to the user data to be passed into the callback.
Return: Subscription identifier.

void (*unsubscribeToGamepadEvents)(Gamepad *gamepad, SubscriptionId id)

Unsubscribes plugin user from the gamepad event stream for a specified gamepad.

Deprecated since version 100.1: This method is deprecated and will be removed soon, please use unsubscribeToInputEvents instead.

Param gamepad: Logical gamepad.
Param subscriptionId: Subscription identifier.

SubscriptionId (*subscribeToGamepadConnectionEvents)(OnGamepadConnectionEventFn fn, void *userData)

Subscribes plugin user to the gamepad connection event stream.

Once subscribed callback is called for all previously created gamepads.

Param fn: Callback function to be called on received event.
Param userData: Pointer to the user data to be passed into the callback.
Return: Subscription identifier.

void (*unsubscribeToGamepadConnectionEvents)(SubscriptionId id)

Unsubscribes plugin user from the gamepad connection event stream.

Unsubscription triggers callback to be called with all devices left as being destroyed.

Param subscriptionId: Subscription identifier.

void (*distributeBufferedEvents)()

Processes buffered events queue and sends unconsumed events as device events, action mapping events, and updates device states.

Clears buffered events queues.

ActionMappingSetHandle (*createActionMappingSet)(const char *settingsPath)

Create action mapping set - a place in settings where named action mappings are stored.

When finished with the returned ActionMappingSet, call destroyActionMappingSet() to release it.

Param settingsPath: Path in settings where the set mappings are stored.
Return: Handle to the action mapping set.

ActionMappingSetHandle (*getActionMappingSetByPath)(const char *settingsPath)

Get existing action mapping set from the settings path provided.

Param settingsPath: Path in settings where the set mappings are stored.
Return: Handle to the action mapping set.

void (*destroyActionMappingSet)(ActionMappingSetHandle actionMappingSet)

Destroy action mapping set.

This function will wait to return until all references to actionMappingSet are released.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet().

size_t (*getActionCount)(const ActionMappingSetHandle actionMappingSet)

Get total action count registered in the plugin with 1 or more action mapping.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Return: The number of the actions.

const char *const *(*getActions)(const ActionMappingSetHandle actionMappingSet)

Get array of all actions.

The size of an array is equal to the Input::getActionCount().

Warning

A ScopedRead should be held when calling this function and while the return value is used. This will prevent other threads from unsafely modifying the data.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Return: The array of action names. This is valid as long as no threads modify the actionMappingSet.

size_t (*addActionMapping)(ActionMappingSetHandle actionMappingSet, const char *actionName, const ActionMappingDesc &desc)

Adds action mapping to the specified action.

Each action keeps a list of mappings. This function push mapping to the end of the list.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Param desc: Action mapping description.
Return: The index of added mapping.

void (*setActionMapping)(ActionMappingSetHandle actionMappingSet, const char *actionName, size_t index, const ActionMappingDesc &desc)

Sets and overrides the indexed action mapping for the specified action.

Each action keeps a list of mappings. This function sets list item according by the index.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Param index: The index of mapping to override. It should be in range [0, mapping count).
Param desc: Action mapping description.

void (*removeActionMapping)(ActionMappingSetHandle actionMappingSet, const char *actionName, size_t index)

Remove indexed action mapping for the specified action.

Each action keeps a list of mappings. This function removes list item by the index.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Param index: The index of mapping to remove. It should be in range [0, mapping count).

void (*clearActionMappings)(ActionMappingSetHandle actionMappingSet, const char *actionName)

Clears and removes all mappings associated with the action.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.

size_t (*getActionMappingCount)(const ActionMappingSetHandle actionMappingSet, const char *actionName)

Get mappings count associated with the action.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Return: The number of the mapping in the list for an action.

const ActionMappingDesc *(*getActionMappings)(const ActionMappingSetHandle actionMappingSet, const char *actionName)

Get array of mappings associated with the action.

The size of an array is equal to the Input::getMappingCount().

Warning

A ScopedRead should be held when calling this function and while the return value is used. This will prevent other threads from unsafely modifying the data.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Return: The array of mappings for an action. This is valid as long as no threads modify or destroy the action mapping. It is recommended to hold a ScopedRead while using this return value.

float (*getActionValue)(const ActionMappingSetHandle actionMappingSet, const char *actionName)

Gets the value for the specified action.

If multiple mapping are associated with the action the biggest value is returned.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Return: Specified action value.

ButtonFlags (*getActionButtonFlags)(const ActionMappingSetHandle actionMappingSet, const char *actionName)

Gets the button flag for the specified action.

Each mapping is treated as button, based on the press threshold.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Return: Specified action value as button flags.

SubscriptionId (*subscribeToActionEvents)(ActionMappingSetHandle actionMappingSet, const char *actionName, OnActionEventFn fn, void *userData)

Subscribes plugin user to the action event stream for a specified action.

Event is triggered on any action value change.

Param actionMappingSet: A handle to a ActionMappingSet, such as returned by createActionMappingSet() or getActionMappingSetByPath().
Param actionName: Action string identifier.
Param fn: Callback function of type OnActionEventFn to be called on received event.
Param userData: Pointer to the user data to be passed into the callback.
Return: Subscription identifier.

void (*unsubscribeToActionEvents)(SubscriptionId id)

Unsubscribes plugin user from the action event stream for a specified action.

Param id: Subscription identifier.

void (*filterBufferedEvents)(InputEventFilterFn fn, void *userData)

Filters all buffered events by calling the specified filter function on each event.

The given fn may modify events in-place and/or may add additional events via the InputProvider obtained from getInputProvider(). Any additional events that are added during a call to filterBufferedEvents() will not be passed to fn during that call. However, future calls to filterBufferedEvents() will pass the events to fn. Any new buffered events added by InputProvider during fn will be added to the end of the event list. Events modified during fn remain in their relative position in the event list.

The outcome of an event is based on what fn returns for that event. If FilterResult::eConsume is returned, the event is considered processed and is removed from the list of buffered events. Future calls to filterBufferedEvents() will not receive the event and it will not be sent when distributeBufferedEvents() is called. If FilterResult::eRetain is returned, the (possibly modified) event remains in the list of buffered events. Future calls to filterBufferedEvents() will receive the event and it will be sent when distributeBufferedEvents() is called.

This function may be called multiple times to re-filter events. For instance, the given fn may be interested in only certain types of events.

The remaining buffered events are sent when distributeBufferedEvents() is called, at which point the list of buffered events is cleared.

Thread Safety: An internal lock is held while fn is called on all events, which synchronizes-with distributeBufferedEvents() and the various InputProvider functions to buffer events. Although the lock provides thread safety to synchronize these operations, if buffered events are added from other threads it is conceivable that events could be added between filterBufferedEvents() and distributeBufferedEvents(), causing them to be sent before being filtered. If this is a cause for concern, use of an external lock is recommended.

Warning

Calling filterBufferedEvents() or distributeBufferedEvents() from fn is expressly disallowed.

Param fn: A pointer to a callback function to be called on each input event.
Param userData: A pointer to the user data to be passed into the callback.

const char *(*getDeviceName)(InputDevice *device)

Get input device name.

Param device: Input device.
Return: Specified input device name string. If device is not valid, nullptr is returned.

DeviceType (*getDeviceType)(InputDevice *device)

Get input device type.

Param device: Input device.
Return: Specified input device type or DeviceType::eUnknown.

void (*unsubscribeToInputEvents)(SubscriptionId id)

Unsubscribes plugin user from the input event stream for a specified device.

Param subscriptionId: Subscription identifier.

KeyboardModifierFlags (*getModifierFlags)(KeyboardModifierFlags modifierFlags, const InputDevice *const *devices, size_t nDevices, const DeviceType *const deviceTypes, size_t nDeviceTypes, const MouseInput *mouseButtons, size_t numMouseButtons)

Gets the modifier state on specific devices and/or device-types.

Note

To ignore all mouse buttons, specify a non-nullptr value for mouseButtons with numMouseButtons as zero.

Param modifierFlags: The modifiers to check against, or 0 to check against all modifiers.
Param devices: An array of InputDevice pointers.
Param nDevices: The number of devices in the devices array.
Param deviceTypes: An array of device-types to check against.
Param nDeviceTypes: The number of device-types in the devices array.
Param mouseButtons: An array of mouse buttons to test against. If nullptr all mouse buttons are tested against.
Param numMouseButtons: The number of buttons in the mouseButtons array.
Return: KeyboardModifierFlags for all devices queried.

KeyboardModifierFlags (*getGlobalModifierFlags)(KeyboardModifierFlags modifierFlags, const MouseInput *mouseButtons, size_t numMouseButtons)

Gets the modifier state on all known keyboard and mouse devices.

Note

To ignore all mouse buttons, specify a non-nullptr value for mouseButtons with numMouseButtons as zero.

Param modifierFlags: The modifiers to check against, or 0 to check against all modifiers.
Param mouseButtons: An array of mouse buttons to test against. If nullptr all mouse buttons are tested against.
Param numMouseButtons: The number of buttons in the mouseButtons array.
Return: KeyboardModifierFlags for all devices queried.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.