API
API
C++
API reference (Input) — Alpha (1.14.2)
DEFOLD
Home Features Showcase Learn Asset Portal Community Blog Support API Free Download Donate  

Defold Learn logo

Defold Learn logo

Input

Iterate the resolved actions from the most recent binding update. Action storage is private; getters read the iterator's current action. Getters require the last ActionIterateNext call to have returned true. Call only on the engine thread. Iterators and actions are borrowed until the next binding update starts or the context is destroyed. Reloading bindings preserves the completed batch. Iteration is read-only, allocation-free and independent between listeners.

Namespace: dmInput
Include: #include <dmsdk/input/input_gen.hpp>
TYPES
HContext input context handle
HInputContext input context handle
ENUMS
ActionSource resolved action source
InputActionSource resolved action source
STRUCTS
struct ActionIterator input action iterator
struct InputActionIterator input action iterator
FUNCTIONS
bool ActionGetGamepadIndex (const ActionIterator* iterator, uint32_t* out_index) read the gamepad index
dmhash_t ActionGetGamepadNameHash (const ActionIterator* iterator) read the gamepad name hash
dmhash_t ActionGetId (const ActionIterator* iterator) read the action identifier
ActionSource ActionGetSource (const ActionIterator* iterator) read the device category
float ActionGetValue (const ActionIterator* iterator) read the scalar binding value
bool ActionIsGamepadConnected (const ActionIterator* iterator) test a gamepad connection notification
bool ActionIsGamepadDisconnected (const ActionIterator* iterator) test a gamepad disconnection notification
bool ActionIsPressed (const ActionIterator* iterator) test the press transition
bool ActionIsReleased (const ActionIterator* iterator) test the release transition
bool ActionIsRepeated (const ActionIterator* iterator) test binding repeat
bool ActionIterateNext (ActionIterator* iterator) advance to the next resolved action
bool InputActionGetGamepadIndex (const InputActionIterator* iterator, uint32_t* out_index) read the gamepad index
dmhash_t InputActionGetGamepadNameHash (const InputActionIterator* iterator) read the gamepad name hash
dmhash_t InputActionGetId (const InputActionIterator* iterator) read the action identifier
InputActionSource InputActionGetSource (const InputActionIterator* iterator) read the device category
float InputActionGetValue (const InputActionIterator* iterator) read the scalar binding value
bool InputActionIsGamepadConnected (const InputActionIterator* iterator) test a gamepad connection notification
bool InputActionIsGamepadDisconnected (const InputActionIterator* iterator) test a gamepad disconnection notification
bool InputActionIsPressed (const InputActionIterator* iterator) test the press transition
bool InputActionIsReleased (const InputActionIterator* iterator) test the release transition
bool InputActionIsRepeated (const InputActionIterator* iterator) test binding repeat
bool InputActionIterateNext (InputActionIterator* iterator) advance to the next resolved action
InputActionIterator InputIterateActions (HInputContext context) iterate resolved input actions
ActionIterator IterateActions (HContext context) iterate resolved input actions

Functions

ActionGetGamepadIndex

bool ActionGetGamepadIndex(const ActionIterator* iterator, uint32_t* out_index)

read the gamepad index

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext
uint32_t* out_index non-null output; unchanged for a non-gamepad action

RETURNS

bool true if the current action belongs to a gamepad

ActionGetGamepadNameHash

dmhash_t ActionGetGamepadNameHash(const ActionIterator* iterator)

Hash of the input mapping's device name, retained on disconnect. Identical names have the same hash; use the gamepad index to distinguish devices. The value can be retained; reverse lookup of the name is not guaranteed.

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

dmhash_t dmHashString64 of the name, or zero for a non-gamepad action or unavailable name

ActionGetId

dmhash_t ActionGetId(const ActionIterator* iterator)

read the action identifier

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

dmhash_t hashed binding name; zero for unnamed pointer or acceleration samples

ActionGetSource

ActionSource ActionGetSource(const ActionIterator* iterator)

read the device category

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

ActionSource device category, or ACTION_SOURCE_UNKNOWN

ActionGetValue

float ActionGetValue(const ActionIterator* iterator)

read the scalar binding value

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

float resolved scalar value, including zero on release

ActionIsGamepadConnected

bool ActionIsGamepadConnected(const ActionIterator* iterator)

True only when this action reports a connection transition, not while the device remains connected. Requires a GAMEPAD_CONNECTED input binding.

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

bool true for a connection notification; false for other actions

ActionIsGamepadDisconnected

bool ActionIsGamepadDisconnected(const ActionIterator* iterator)

True only when this action reports a disconnection transition. Requires a GAMEPAD_DISCONNECTED input binding. The gamepad index may later be reused.

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

bool true for a disconnection notification; false for other actions

ActionIsPressed

bool ActionIsPressed(const ActionIterator* iterator)

test the press transition

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

bool true if the binding became active this input update

ActionIsReleased

bool ActionIsReleased(const ActionIterator* iterator)

test the release transition

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

bool true if the binding became inactive this input update

ActionIsRepeated

bool ActionIsRepeated(const ActionIterator* iterator)

test binding repeat

PARAMETERS

const ActionIterator* iterator iterator positioned by a successful ActionIterateNext

RETURNS

bool true if repeat was triggered this input update

ActionIterateNext

bool ActionIterateNext(ActionIterator* iterator)

A false result invalidates the current action. Further advances remain false.

PARAMETERS

ActionIterator* iterator iterator initialized by IterateActions

RETURNS

bool true when positioned on an action; false when exhausted or empty

InputActionGetGamepadIndex

bool InputActionGetGamepadIndex(const InputActionIterator* iterator, uint32_t* out_index)

read the gamepad index

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext
uint32_t* out_index non-null output; unchanged for a non-gamepad action

RETURNS

bool true if the current action belongs to a gamepad

InputActionGetGamepadNameHash

dmhash_t InputActionGetGamepadNameHash(const InputActionIterator* iterator)

Hash of the input mapping's device name, retained on disconnect. Identical names have the same hash; use the gamepad index to distinguish devices. The value can be retained; reverse lookup of the name is not guaranteed.

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

dmhash_t dmHashString64 of the name, or zero for a non-gamepad action or unavailable name

InputActionGetId

dmhash_t InputActionGetId(const InputActionIterator* iterator)

read the action identifier

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

dmhash_t hashed binding name; zero for unnamed pointer or acceleration samples

InputActionGetSource

InputActionSource InputActionGetSource(const InputActionIterator* iterator)

read the device category

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

InputActionSource device category, or INPUT_ACTION_SOURCE_UNKNOWN

InputActionGetValue

float InputActionGetValue(const InputActionIterator* iterator)

read the scalar binding value

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

float resolved scalar value, including zero on release

InputActionIsGamepadConnected

bool InputActionIsGamepadConnected(const InputActionIterator* iterator)

True only when this action reports a connection transition, not while the device remains connected. Requires a GAMEPAD_CONNECTED input binding.

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

bool true for a connection notification; false for other actions

InputActionIsGamepadDisconnected

bool InputActionIsGamepadDisconnected(const InputActionIterator* iterator)

True only when this action reports a disconnection transition. Requires a GAMEPAD_DISCONNECTED input binding. The gamepad index may later be reused.

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

bool true for a disconnection notification; false for other actions

InputActionIsPressed

bool InputActionIsPressed(const InputActionIterator* iterator)

test the press transition

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

bool true if the binding became active this input update

InputActionIsReleased

bool InputActionIsReleased(const InputActionIterator* iterator)

test the release transition

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

bool true if the binding became inactive this input update

InputActionIsRepeated

bool InputActionIsRepeated(const InputActionIterator* iterator)

test binding repeat

PARAMETERS

const InputActionIterator* iterator iterator positioned by a successful InputActionIterateNext

RETURNS

bool true if repeat was triggered this input update

InputActionIterateNext

bool InputActionIterateNext(InputActionIterator* iterator)

A false result invalidates the current action. Further advances remain false.

PARAMETERS

InputActionIterator* iterator iterator initialized by InputIterateActions

RETURNS

bool true when positioned on an action; false when exhausted or empty

InputIterateActions

InputActionIterator InputIterateActions(HInputContext context)

Iterates the latest completed binding update, with text actions last. The iterator starts before the first action. Multiple iterators advance independently. The next binding update invalidates existing iterators and current actions.

PARAMETERS

HInputContext context live borrowed input context

RETURNS

InputActionIterator cursor positioned before the first action

IterateActions

ActionIterator IterateActions(HContext context)

Iterates the latest completed binding update, with text actions last. The iterator starts before the first action. Multiple iterators advance independently. The next binding update invalidates existing iterators and current actions.

PARAMETERS

HContext context live borrowed input context

RETURNS

ActionIterator cursor positioned before the first action

Structs

ActionIterator

TYPE

struct ActionIterator

Small value-type cursor with reserved opaque state. Do not access its members; initialize it with IterateActions and advance with ActionIterateNext. Its ABI occupies two uintptr_t words and requires no allocation or destruction.

InputActionIterator

TYPE

struct InputActionIterator

Small value-type cursor with reserved opaque state. Do not access its members; initialize it with InputIterateActions and advance with InputActionIterateNext. Its ABI occupies two uintptr_t words and requires no allocation or destruction.

Types

HContext

void HContext()

Borrowed engine-owned input context. Do not destroy it. Actions are empty before the first binding update.

PARAMETERS

HInputContext

void HInputContext()

Borrowed engine-owned input context. Do not destroy it. Actions are empty before the first binding update.

PARAMETERS

Enums

ActionSource

resolved action source

ACTION_SOURCE_UNKNOWN Unrecognized device category.
ACTION_SOURCE_KEYBOARD Keyboard binding.
ACTION_SOURCE_TEXT Text or marked-text binding.
ACTION_SOURCE_MOUSE Mouse binding or pointer movement.
ACTION_SOURCE_TOUCH Touch binding.
ACTION_SOURCE_GAMEPAD Gamepad binding or connectivity notification.
ACTION_SOURCE_ACCELEROMETER Accelerometer sample.

InputActionSource

resolved action source

INPUT_ACTION_SOURCE_UNKNOWN Unrecognized device category.
INPUT_ACTION_SOURCE_KEYBOARD Keyboard binding.
INPUT_ACTION_SOURCE_TEXT Text or marked-text binding.
INPUT_ACTION_SOURCE_MOUSE Mouse binding or pointer movement.
INPUT_ACTION_SOURCE_TOUCH Touch binding.
INPUT_ACTION_SOURCE_GAMEPAD Gamepad binding or connectivity notification.
INPUT_ACTION_SOURCE_ACCELEROMETER Accelerometer sample.