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 InputActionIterateNext 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.

Include: #include <dmsdk/input/input.h>
TYPES
HInputContext input context handle
ENUMS
InputActionSource resolved action source
STRUCTS
struct InputActionIterator input action iterator
FUNCTIONS
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

Functions

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

Structs

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

HInputContext

void HInputContext()

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

PARAMETERS

Enums

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.