Torque3D Documentation / _generateds / Input

Input

More...

Classes:

class
ActionMap

ActionMaps assign platform input events to console commands.

Enumerations

enum
SDLJoystickType {
  Unknown 
  Controller 
  Wheel 
  Stick 
  Stick 
  Pad 
  Guitar 
  Kit 
  Pad 
  Throttle 
}

The type of device connected.

enum
SDLPowerEnum {
  Unknown 
  Empty 
  Low 
  Medium 
  Full 
  Wired 
  Max 
}

An enumeration of battery levels of a joystick.

Functions

void

activateDirectInput()

Activates DirectInput.

String

ControllerGetAxes(int sdlIndex)

Gets the current value for all controller axes.

String

ControllerGetButtons(int sdlIndex)

Gets the current value for all controller buttons.

string

ControllerNameForIndex(int sdlIndex)

Exposes SDL_GameControllerNameForIndex() to script.

void

deactivateDirectInput()

Disables DirectInput.

int

GameControllerAddMapping(string mappingString)

Exposes SDL_GameControllerAddMapping() to script.

int

GameControllerAddMappingsFromFile(string fileName)

Exposes SDL_GameControllerAddMappingsFromFile() to script.

String

GameControllerMapping(int sdlIndex)

Exposes SDL_GameControllerMapping() to script.

String

GameControllerMappingForGUID(string guidStr)

Exposes SDL_GameControllerMappingForGUID() to script.

String

GameControllerMappingForIndex(int mappingIndex)

Get the mapping at a particular index.

int

GameControllerNumMappings()

Get the number of mappings installed. Used with GameControllerMappingForIndex to iterate through all installed mappings.

ActionMap

getCurrentActionMap()

Returns the current ActionMap.

int

getDeviceOpenState(int sdlIndex)

Used to determine the current state of the N'th item in the SDL device list.

SDLJoystickType

GetDeviceType(int sdlIndex)

Exposes SDL_JoystickGetDeviceType() to script.

int

GetProduct(int sdlIndex)

Gets the USB product ID of a joystick device, if available.

int

GetProductVersion(int sdlIndex)

Gets the product version of a joystick device, if available.

string

getTorqueInstFromDevice(int sdlIndex)

Gets the T3D instance identifier for an open SDL joystick.

int

GetVendor(int sdlIndex)

Gets the USB vendor ID of a joystick device, if available.

bool

IsGameController(int sdlIndex)

Exposes SDL_IsGameController() to script.

String

JoystickGetAxes(int sdlIndex)

Gets the current value for all joystick axes.

String

JoystickGetButtons(int sdlIndex)

Gets the current value for all joystick buttons.

string

JoystickGetGUID(int sdlIndex)

Exposes SDL_JoystickGetDeviceGUID() to script.

String

JoystickGetHats(int sdlIndex)

Gets the current value for all POV hats.

String

JoystickGetSpecs(int sdlIndex)

A convenience function to reurn all of the data for a Joystick/Game Controller packed as fields in a tab separated string.

bool

JoystickIsHaptic(int sdlIndex)

Exposes SDL_JoystickIsHaptic() to script.

string

JoystickNameForIndex(int sdlIndex)

Exposes SDL_JoystickNameForIndex() to script.

int

JoystickNumAxes(int sdlIndex)

Exposes SDL_JoystickNumAxes() to script.

int

JoystickNumBalls(int sdlIndex)

Exposes SDL_JoystickNumBalls() to script.

int

JoystickNumButtons(int sdlIndex)

Exposes SDL_JoystickNumButtons() to script.

int

JoystickNumHats(int sdlIndex)

Exposes SDL_JoystickNumHats() to script.

SDLPowerEnum

JoystickPowerLevel(int sdlIndex)

Exposes SDL_JoystickCurrentPowerLevel() to script.

void

lockMouse(bool isLocked)

Lock or unlock the mouse to the window.

int

numJoysticks()

Returns the number of currently connected joystick devices.

Variables

bool

JoystickEnabled

If true, Joystick devices will be automatically opened.

bool

JoystickPOVButtons

If true, the pov hat will be treated as 4 buttons and make/break events will be generated for upov, dpov, lpov and rpov.

bool

JoystickPOVMask

If true, the pov hat will be treated as a single input with a 4 bit mask value. The povmask event will be generated with the current mask every time the mask value changes.

bool

JoystickSplitAxesLR

Split axis inputs on 4 axis joysticks. This has no effect on any other device.

bool

sdlControllerEnabled

If true, any Joystick device that SDL recognizes as a Game Controller will be automatically opened as a game controller.

Detailed Description

Enumerations

SDLJoystickType

Enumerator

Unknown
Controller
Wheel
Stick
Stick
Pad
Guitar
Kit
Pad
Throttle

The type of device connected.

SDLPowerEnum

Enumerator

Unknown
Empty

ShapeBaseImage is not loaded.

Low
Medium
Full
Wired
Max

An enumeration of battery levels of a joystick.

Functions

activateDirectInput()

Activates DirectInput.

Also activates any connected joysticks.

ControllerGetAxes(int sdlIndex)

Gets the current value for all controller axes.

Parameters:

sdlIndex

The SDL index for this device.

return:

A tab separated string that can be parsed from script with getField()/getFields(). Game controllers always have 6 axes in the following order: 0-LX, 1-LY, 2-RX, 3-RY, 4-LT, 5-RT.

ControllerGetButtons(int sdlIndex)

Gets the current value for all controller buttons.

Parameters:

sdlIndex

The SDL index for this device.

return:

A tab separated string that can be parsed from script with getField()/getFields(). Game controllers always have 15 buttons in the following order: 0-A, 1-B, 2-X, 3-Y, 4-Back, 5-Guide, 6-Start, 7-Left Stick, 8-Right Stick, 9-Left Shoulder, 10-Right Shoulder, 11-DPad Up, 12-DPad Down, 13-DPad Left, 14-DPad Right.

ControllerNameForIndex(int sdlIndex)

Exposes SDL_GameControllerNameForIndex() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the implementation dependent name for the game controller, or NULL if there is no name or the index is invalid.

see:

https://wiki.libsdl.org/SDL_GameControllerNameForIndex

deactivateDirectInput()

Disables DirectInput.

Also deactivates any connected joysticks.

GameControllerAddMapping(string mappingString)

Exposes SDL_GameControllerAddMapping() to script.

Use this function to add support for controllers that SDL is unaware of or to cause an existing controller to have a different binding. Parameters:

mappingString

The new mapping string to apply. Full details on the format of this string are available at the linked SDL wiki page.

return:

Returns 1 if a new mapping is added, 0 if an existing mapping is updated, -1 on error.

see:

https://wiki.libsdl.org/SDL_GameControllerAddMapping

GameControllerAddMappingsFromFile(string fileName)

Exposes SDL_GameControllerAddMappingsFromFile() to script.

Use this function to load a set of Game Controller mappings from a file, filtered by the current SDL_GetPlatform(). A community sourced database of controllers is available at https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt Parameters:

fileName

The file to load mappings from.

return:

Returns the number of mappings added or -1 on error.

see:

https://wiki.libsdl.org/SDL_GameControllerAddMappingsFromFile

GameControllerMapping(int sdlIndex)

Exposes SDL_GameControllerMapping() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns a string that has the controller's mapping or NULL if no mapping is available or it does not exist.

see:

https://wiki.libsdl.org/SDL_JoystickNameForIndex

GameControllerMappingForGUID(string guidStr)

Exposes SDL_GameControllerMappingForGUID() to script.

Parameters:

guidStr

The GUID for which a mapping is desired.

return:

Returns a mapping string or NULL on error.

see:

https://wiki.libsdl.org/SDL_GameControllerMappingForGUID

GameControllerMappingForIndex(int mappingIndex)

Get the mapping at a particular index.

Parameters:

mappingIndex

The index for which a mapping is desired.

return:

Returns a mapping string or NULL if the index is out of range.

GameControllerNumMappings()

Get the number of mappings installed. Used with GameControllerMappingForIndex to iterate through all installed mappings.

getCurrentActionMap()

Returns the current ActionMap.

see:

ActionMap

getDeviceOpenState(int sdlIndex)

Used to determine the current state of the N'th item in the SDL device list.

Parameters:

sdlIndex

The SDL index for this device.

return:

values: -1 if the device does not exist (invalid sdlIndex passed) 0 The device is closed 1 The device is open as a Joystick 2 The device is open as a Game Controller

GetDeviceType(int sdlIndex)

Exposes SDL_JoystickGetDeviceType() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

The type of device connected. Possible return strings are: "Unknown", "Game Controller", "Wheel", "Arcade Stick", "Flight Stick", "Dance Pad", "Guitar", "Drum Kit", "Arcade Pad" and "Throttle"

see:

https://wiki.libsdl.org/SDL_JoystickGetDeviceType

GetProduct(int sdlIndex)

Gets the USB product ID of a joystick device, if available.

Parameters:

sdlIndex

The SDL index for this device.

return:

The USB product ID. If the product ID isn't available this function returns 0.

see:

https://wiki.libsdl.org/SDL_JoystickGetDeviceProduct

see:

https://wiki.libsdl.org/SDL_JoystickGetProduct

see:

https://wiki.libsdl.org/SDL_GameControllerGetProduct

GetProductVersion(int sdlIndex)

Gets the product version of a joystick device, if available.

Parameters:

sdlIndex

The SDL index for this device.

return:

The product version. If the product version isn't available this function returns 0.

see:

https://wiki.libsdl.org/SDL_JoystickGetDeviceProductVersion

see:

https://wiki.libsdl.org/SDL_JoystickGetProductVersion

see:

https://wiki.libsdl.org/SDL_GameControllerGetProductVersion

getTorqueInstFromDevice(int sdlIndex)

Gets the T3D instance identifier for an open SDL joystick.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the T3D instance ID used for mapping this device or Null if it does not exist.

GetVendor(int sdlIndex)

Gets the USB vendor ID of a joystick device, if available.

Parameters:

sdlIndex

The SDL index for this device.

return:

The USB vendor ID. If the vendor ID isn't available this function returns 0.

see:

https://wiki.libsdl.org/SDL_JoystickGetDeviceVendor

see:

https://wiki.libsdl.org/SDL_JoystickGetVendor

see:

https://wiki.libsdl.org/SDL_GameControllerGetVendor

IsGameController(int sdlIndex)

Exposes SDL_IsGameController() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns true if the given joystick is supported by the game controller interface, false if it isn't or it's an invalid index.

see:

https://wiki.libsdl.org/SDL_IsGameController

JoystickGetAxes(int sdlIndex)

Gets the current value for all joystick axes.

Parameters:

sdlIndex

The SDL index for this device.

return:

A tab separated string that can be parsed from script with getField()/getFields(). Each axis is one field, so a 4 axis device will have 4 fields.

JoystickGetButtons(int sdlIndex)

Gets the current value for all joystick buttons.

Parameters:

sdlIndex

The SDL index for this device.

return:

A tab separated string that can be parsed from script with getField()/getFields(). Each button is one field. 0 - SDL_JoystickNumButtons() fields.

JoystickGetGUID(int sdlIndex)

Exposes SDL_JoystickGetDeviceGUID() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

GUID for the indexed device or Null if it does not exist.

see:

https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID

JoystickGetHats(int sdlIndex)

Gets the current value for all POV hats.

Parameters:

sdlIndex

The SDL index for this device.

return:

A tab separated string that can be parsed from script with getField()/getFields(). Each hat is one field. 0 - SDL_JoystickNumHats() fields. The value is a 4 bit bitmask. If no bits are set, the hat is centered. Bit 0 is up, 1 is right, 2 is down and 3 is left.

JoystickGetSpecs(int sdlIndex)

A convenience function to reurn all of the data for a Joystick/Game Controller packed as fields in a tab separated string.

There is overhead involved in querying joystick data, especially if the device is not open. If more than one field is required, it is more efficient to call JoystickGetSpecs() and parse the data out of the return string than to call the console method for each. Parameters:

sdlIndex

The SDL index for this device.

return:

A tab separated string that can be parsed from script with getField()/getFields().

Field 0: Number of Axes 1: Number of Buttons 2: Number of POV Hats 3: Number of Trackballs 4: SDL_IsGameController() (Boolean) 5: SDL_JoystickIsHaptic() (Boolean) 6: Power Level (String) 7: Device Type (String)

JoystickIsHaptic(int sdlIndex)

Exposes SDL_JoystickIsHaptic() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns true if the joystick is haptic.

see:

https://wiki.libsdl.org/SDL_JoystickIsHaptic

JoystickNameForIndex(int sdlIndex)

Exposes SDL_JoystickNameForIndex() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the name of the selected joystick or Null if it does not exist.

see:

https://wiki.libsdl.org/SDL_JoystickNameForIndex

JoystickNumAxes(int sdlIndex)

Exposes SDL_JoystickNumAxes() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the number of axis controls/number of axes on success or zero on failure.

see:

https://wiki.libsdl.org/SDL_JoystickNumAxes

JoystickNumBalls(int sdlIndex)

Exposes SDL_JoystickNumBalls() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the number of trackballs on success or zero on failure.

see:

https://wiki.libsdl.org/SDL_JoystickNumBalls

JoystickNumButtons(int sdlIndex)

Exposes SDL_JoystickNumButtons() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the number of buttons on success or zero on failure.

see:

https://wiki.libsdl.org/SDL_JoystickNumButtons

JoystickNumHats(int sdlIndex)

Exposes SDL_JoystickNumHats() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the number of POV hats on success or zero on failure.

see:

https://wiki.libsdl.org/SDL_JoystickNumHats

JoystickPowerLevel(int sdlIndex)

Exposes SDL_JoystickCurrentPowerLevel() to script.

Parameters:

sdlIndex

The SDL index for this device.

return:

Returns the current battery level or "Wired" if it's a connected device.

see:

https://wiki.libsdl.org/SDL_JoystickCurrentPowerLevel

lockMouse(bool isLocked)

Lock or unlock the mouse to the window.

When true, prevents the mouse from leaving the bounds of the game window.

numJoysticks()

Returns the number of currently connected joystick devices.

Game Controllers are a sub-set of joysticks and are included in the joystick count. See https://wiki.libsdl.org/SDL_NumJoysticks for more details.

Variables

bool JoystickEnabled

If true, Joystick devices will be automatically opened.

bool JoystickPOVButtons

If true, the pov hat will be treated as 4 buttons and make/break events will be generated for upov, dpov, lpov and rpov.

bool JoystickPOVMask

If true, the pov hat will be treated as a single input with a 4 bit mask value. The povmask event will be generated with the current mask every time the mask value changes.

bool JoystickSplitAxesLR

Split axis inputs on 4 axis joysticks. This has no effect on any other device.

4 Axis joysticks use IDs 0-3 which get mapped to xaxis, yaxis, zaxis and rxaxis. When true, this will increment IDs 2 and 3 so the inputs map to xaxis, yaxis, rxaxis and ryaxis.

bool sdlControllerEnabled

If true, any Joystick device that SDL recognizes as a Game Controller will be automatically opened as a game controller.