Game Controller main interface

The main interface to use the Game Controller library.

Summary

Enumerations

Paddleboat_Buttons{
  PADDLEBOAT_BUTTON_DPAD_UP = (1U << 0),
  PADDLEBOAT_BUTTON_DPAD_LEFT = (1U << 1),
  PADDLEBOAT_BUTTON_DPAD_DOWN = (1U << 2),
  PADDLEBOAT_BUTTON_DPAD_RIGHT = (1U << 3),
  PADDLEBOAT_BUTTON_A = (1U << 4),
  PADDLEBOAT_BUTTON_B = (1U << 5),
  PADDLEBOAT_BUTTON_X = (1U << 6),
  PADDLEBOAT_BUTTON_Y = (1U << 7),
  PADDLEBOAT_BUTTON_L1 = (1U << 8),
  PADDLEBOAT_BUTTON_L2 = (1U << 9),
  PADDLEBOAT_BUTTON_L3 = (1U << 10),
  PADDLEBOAT_BUTTON_R1 = (1U << 11),
  PADDLEBOAT_BUTTON_R2 = (1U << 12),
  PADDLEBOAT_BUTTON_R3 = (1U << 13),
  PADDLEBOAT_BUTTON_SELECT = (1U << 14),
  PADDLEBOAT_BUTTON_START = (1U << 15),
  PADDLEBOAT_BUTTON_SYSTEM = (1U << 16),
  PADDLEBOAT_BUTTON_TOUCHPAD = (1U << 17),
  PADDLEBOAT_BUTTON_AUX1 = (1U << 18),
  PADDLEBOAT_BUTTON_AUX2 = (1U << 19),
  PADDLEBOAT_BUTTON_AUX3 = (1U << 20),
  PADDLEBOAT_BUTTON_AUX4 = (1U << 21),
  PADDLEBOAT_BUTTON_COUNT = 22
}
enum
Paddleboat controller buttons defined as bitmask values.
Paddleboat_ControllerButtonLayout{
  PADDLEBOAT_CONTROLLER_LAYOUT_STANDARD = 0,
  PADDLEBOAT_CONTROLLER_LAYOUT_SHAPES = 1,
  PADDLEBOAT_CONTROLLER_LAYOUT_REVERSE = 2,
  PADDLEBOAT_CONTROLLER_LAYOUT_ARCADE_STICK = 3,
  PADDLEBOAT_CONTROLLER_LAYOUT_MASK = 3
}
enum
The button layout and iconography of the controller buttons.
Paddleboat_ControllerStatus{
  PADDLEBOAT_CONTROLLER_INACTIVE = 0,
  PADDLEBOAT_CONTROLLER_ACTIVE = 1,
  PADDLEBOAT_CONTROLLER_JUST_CONNECTED = 2,
  PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED = 3
}
enum
Current status of a controller (at a specified controller index)
Paddleboat_Controller_Flags{
  PADDLEBOAT_CONTROLLER_FLAG_GENERIC_PROFILE = (0x0000000010),
  PADDLEBOAT_CONTROLLER_FLAG_VIBRATION = (0x08000000),
  PADDLEBOAT_CONTROLLER_FLAG_VIBRATION_DUAL_MOTOR = (0x10000000),
  PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD = (0x20000000),
  PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE = (0x40000000)
}
enum
Paddleboat controller device feature flags as bitmask values AND against Paddleboat_Controller_Info.controllerFlags to determine feature availability.
Paddleboat_ErrorCode{
  PADDLEBOAT_NO_ERROR = 0,
  PADDLEBOAT_ERROR_ALREADY_INITIALIZED = -2000,
  PADDLEBOAT_ERROR_NOT_INITIALIZED = -2001,
  PADDLEBOAT_ERROR_INIT_GCM_FAILURE = -2002,
  PADDLEBOAT_ERROR_INVALID_CONTROLLER_INDEX = -2003,
  PADDLEBOAT_ERROR_NO_CONTROLLER = -2004,
  PADDLEBOAT_ERROR_NO_MOUSE = -2005,
  PADDLEBOAT_ERROR_FEATURE_NOT_SUPPORTED = -2006,
  PADDLEBOAT_ERROR_INVALID_PARAMETER = -2007
}
enum
Paddleboat error code results.
Paddleboat_Ignored_Axis{
  PADDLEBOAT_AXIS_BUTTON_IGNORED = 0xFE,
  PADDLEBOAT_AXIS_IGNORED = 0xFFFE
}
enum
Special constants to specify an axis or axis button mapping is ignored by the controller.
Paddleboat_Ignored_Buttons{
  PADDLEBOAT_BUTTON_IGNORED = 0xFFFE
}
enum
Special constant to specify a button is ignored by the controller.
Paddleboat_Mapping_Axis{
  PADDLEBOAT_MAPPING_AXIS_LEFTSTICK_X = 0,
  PADDLEBOAT_MAPPING_AXIS_LEFTSTICK_Y,
  PADDLEBOAT_MAPPING_AXIS_RIGHTSTICK_X,
  PADDLEBOAT_MAPPING_AXIS_RIGHTSTICK_Y,
  PADDLEBOAT_MAPPING_AXIS_L1,
  PADDLEBOAT_MAPPING_AXIS_L2,
  PADDLEBOAT_MAPPING_AXIS_R1,
  PADDLEBOAT_MAPPING_AXIS_R2,
  PADDLEBOAT_MAPPING_AXIS_HATX,
  PADDLEBOAT_MAPPING_AXIS_HATY,
  PADDLEBOAT_MAPPING_AXIS_COUNT = 10
}
enum
Axis order enum of Paddleboat axis mapping table.
Paddleboat_MouseStatus{
  PADDLEBOAT_MOUSE_NONE = 0,
  PADDLEBOAT_MOUSE_CONTROLLER_EMULATED = 1,
  PADDLEBOAT_MOUSE_PHYSICAL
}
enum
The status of the mouse device.
Paddleboat_Mouse_Buttons{
  PADDLEBOAT_MOUSE_BUTTON_LEFT = (1U << 0),
  PADDLEBOAT_MOUSE_BUTTON_RIGHT = (1U << 1),
  PADDLEBOAT_MOUSE_BUTTON_MIDDLE = (1U << 2),
  PADDLEBOAT_MOUSE_BUTTON_BACK = (1U << 3),
  PADDLEBOAT_MOUSE_BUTTON_FORWARD = (1U << 4),
  PADDLEBOAT_MOUSE_BUTTON_6 = (1U << 5),
  PADDLEBOAT_MOUSE_BUTTON_7 = (1U << 6),
  PADDLEBOAT_MOUSE_BUTTON_8 = (1U << 7)
}
enum
Paddleboat mouse buttons as bitmask values AND against Paddleboat_Mouse_Data.buttonsDown to determine button status.
Paddleboat_Remap_Addition_Mode{
  PADDLEBOAT_REMAP_ADD_MODE_DEFAULT = 0,
  PADDLEBOAT_REMAP_ADD_MODE_REPLACE_ALL
}
enum
The addition mode to use when passing new controller mapping data to Paddleboat_addControllerRemapData.

Typedefs

Paddleboat_ControllerStatusCallback)(const int32_t controllerIndex, const Paddleboat_ControllerStatus controllerStatus, void *userData) typedef
void(*
Signature of a function that can be passed to Paddleboat_setControllerStatusCallback to receive information about controller connections and disconnections.
Paddleboat_Controller_Data typedef
A structure that contains the current data for a controller's inputs and sensors.
Paddleboat_Controller_Info typedef
A structure that contains information about a particular controller device.
Paddleboat_Controller_Mapping_Data typedef
A structure that describes the button and axis mappings for a specified controller device running on a specified range of Android API levels.
Paddleboat_Controller_Pointer typedef
A structure that contains virtual pointer position data.
Paddleboat_Controller_Thumbstick typedef
A structure that contains X and Y axis data for an analog thumbstick.
Paddleboat_Controller_Thumbstick_Precision typedef
A structure that contains axis precision data for a thumbstick in the X and Y axis.
Paddleboat_MouseStatusCallback)(const Paddleboat_MouseStatus mouseStatus, void *userData) typedef
void(*
Signature of a function that can be passed to Paddleboat_setMouseStatusCallback to receive information about mouse device status changes.
Paddleboat_Mouse_Data typedef
A structure that contains input data for the mouse device.
Paddleboat_Vibration_Data typedef
A structure that describes the parameters of a vibration effect.

Functions

Paddleboat_addControllerRemapData(const Paddleboat_Remap_Addition_Mode addMode, const int32_t remapTableEntryCount, const Paddleboat_Controller_Mapping_Data *mappingData)
void
Add new controller remap information to the internal remapping table.
Paddleboat_destroy(JNIEnv *env)
void
Destroy resources that Paddleboat has created.
Paddleboat_getActiveAxisMask()
uint64_t
Retrieve the active axis ids being used by connected devices.
Paddleboat_getBackButtonConsumed()
bool
Get whether Paddleboat consumes AKEYCODE_BACK key events from devices being managed by Paddleboat.
Paddleboat_getControllerData(const int32_t controllerIndex, Paddleboat_Controller_Data *controllerData)
Retrieve the current controller data from the controller with the specified index.
Paddleboat_getControllerInfo(const int32_t controllerIndex, Paddleboat_Controller_Info *controllerInfo)
Retrieve the current controller device info from the controller with the specified index.
Paddleboat_getControllerName(const int32_t controllerIndex, const size_t bufferSize, char *controllerName)
Retrieve the current controller name from the controller with the specified index.
Paddleboat_getControllerRemapTableData(const int32_t destRemapTableEntryCount, Paddleboat_Controller_Mapping_Data *mappingData)
int32_t
Retrieve the current table of controller remap entries.
Paddleboat_getControllerStatus(const int32_t controllerIndex)
Retrieve the current controller device info from the controller with the specified index.
Paddleboat_getLastKeycode()
int32_t
An function that returns the last keycode seen in a key event coming from a controller owned by Paddleboat.
Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)
Retrieve the current mouse data.
Paddleboat_getMouseStatus()
Retrieve the current controller device info from the controller with the specified index.
Paddleboat_init(JNIEnv *env, jobject jcontext)
Initialize Paddleboat, constructing internal resources via JNI.
Paddleboat_isInitialized()
bool
Check if Paddleboat was successfully initialized.
Paddleboat_onStart(JNIEnv *env)
void
Inform Paddleboat that a start event was sent to the application.
Paddleboat_onStop(JNIEnv *env)
void
Inform Paddleboat that a stop event was sent to the application.
Paddleboat_processGameActivityKeyInputEvent(const void *event, const size_t eventSize)
int32_t
Process a GameActivityKeyEvent input event to see if it is from a device being managed by Paddleboat.
Paddleboat_processGameActivityMotionInputEvent(const void *event, const size_t eventSize)
int32_t
Process a GameActivityMotionEvent input event to see if it is from a device being managed by Paddleboat.
Paddleboat_processInputEvent(const AInputEvent *event)
int32_t
Process an input event to see if it is from a device being managed by Paddleboat.
Paddleboat_setBackButtonConsumed(bool consumeBackButton)
void
Set whether Paddleboat consumes AKEYCODE_BACK key events from devices being managed by Paddleboat.
Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback statusCallback, void *userData)
void
Set a callback to be called whenever a controller managed by Paddleboat changes status.
Paddleboat_setControllerVibrationData(const int32_t controllerIndex, const Paddleboat_Vibration_Data *vibrationData, JNIEnv *env)
Set vibration data for the controller with the specified index.
Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback statusCallback, void *userData)
void
Set a callback to be called when the mouse status changes.
Paddleboat_update(JNIEnv *env)
void
Updates internal Paddleboat status and processes pending connection/disconnections.

Macros

PADDLEBOAT_MAX_CONTROLLERS 8
Maximum number of simultaneously connected controllers.

Structs

Paddleboat_Controller_Data

A structure that contains the current data for a controller's inputs and sensors.

Paddleboat_Controller_Info

A structure that contains information about a particular controller device.

Paddleboat_Controller_Mapping_Data

A structure that describes the button and axis mappings for a specified controller device running on a specified range of Android API levels.

Paddleboat_Controller_Pointer

A structure that contains virtual pointer position data.

Paddleboat_Controller_Thumbstick

A structure that contains X and Y axis data for an analog thumbstick.

Paddleboat_Controller_Thumbstick_Precision

A structure that contains axis precision data for a thumbstick in the X and Y axis.

Paddleboat_Mouse_Data

A structure that contains input data for the mouse device.

Paddleboat_Vibration_Data

A structure that describes the parameters of a vibration effect.

Enumerations

Paddleboat_Buttons

 Paddleboat_Buttons

Paddleboat controller buttons defined as bitmask values.

AND against Paddleboat_Controller_Data.buttonsDown to check for button status.

Properties
PADDLEBOAT_BUTTON_A

Bitmask for Paddleboat_Controller_Data.buttonsDown A button.

PADDLEBOAT_BUTTON_AUX1

Bitmask for Paddleboat_Controller_Data.buttonsDown AUX1 button.

PADDLEBOAT_BUTTON_AUX2

Bitmask for Paddleboat_Controller_Data.buttonsDown AUX2 button.

PADDLEBOAT_BUTTON_AUX3

Bitmask for Paddleboat_Controller_Data.buttonsDown AUX3 button.

PADDLEBOAT_BUTTON_AUX4

Bitmask for Paddleboat_Controller_Data.buttonsDown AUX4 button.

PADDLEBOAT_BUTTON_B

Bitmask for Paddleboat_Controller_Data.buttonsDown B button.

PADDLEBOAT_BUTTON_COUNT

Count of defined controller buttons.

PADDLEBOAT_BUTTON_DPAD_DOWN

Bitmask for Paddleboat_Controller_Data.buttonsDown direction pad down button.

PADDLEBOAT_BUTTON_DPAD_LEFT

Bitmask for Paddleboat_Controller_Data.buttonsDown direction pad left button.

PADDLEBOAT_BUTTON_DPAD_RIGHT

Bitmask for Paddleboat_Controller_Data.buttonsDown direction pad right button.

PADDLEBOAT_BUTTON_DPAD_UP

Bitmask for Paddleboat_Controller_Data.buttonsDown direction pad up button.

PADDLEBOAT_BUTTON_L1

Bitmask for Paddleboat_Controller_Data.buttonsDown L1 trigger button.

PADDLEBOAT_BUTTON_L2

Bitmask for Paddleboat_Controller_Data.buttonsDown L2 trigger button.

PADDLEBOAT_BUTTON_L3

Bitmask for Paddleboat_Controller_Data.buttonsDown L3 thumbstick button.

PADDLEBOAT_BUTTON_R1

Bitmask for Paddleboat_Controller_Data.buttonsDown R1 trigger button.

PADDLEBOAT_BUTTON_R2

Bitmask for Paddleboat_Controller_Data.buttonsDown R2 trigger button.

PADDLEBOAT_BUTTON_R3

Bitmask for Paddleboat_Controller_Data.buttonsDown R3 thumbstick button.

PADDLEBOAT_BUTTON_SELECT

Bitmask for Paddleboat_Controller_Data.buttonsDown Select button.

PADDLEBOAT_BUTTON_START

Bitmask for Paddleboat_Controller_Data.buttonsDown Start button.

PADDLEBOAT_BUTTON_SYSTEM

Bitmask for Paddleboat_Controller_Data.buttonsDown System button.

PADDLEBOAT_BUTTON_TOUCHPAD

Bitmask for Paddleboat_Controller_Data.buttonsDown Touchpad pressed.

PADDLEBOAT_BUTTON_X

Bitmask for Paddleboat_Controller_Data.buttonsDown X button.

PADDLEBOAT_BUTTON_Y

Bitmask for Paddleboat_Controller_Data.buttonsDown Y button.

Paddleboat_ControllerButtonLayout

 Paddleboat_ControllerButtonLayout

The button layout and iconography of the controller buttons.

Properties
PADDLEBOAT_CONTROLLER_LAYOUT_ARCADE_STICK

X Y R1 L1
A B R2 L2.

PADDLEBOAT_CONTROLLER_LAYOUT_MASK

Mask value, AND with Paddleboat_Controller_Info.controllerFlags to get the Paddleboat_ControllerButtonLayout value.

PADDLEBOAT_CONTROLLER_LAYOUT_REVERSE

 X 
Y A
 B 

PADDLEBOAT_CONTROLLER_LAYOUT_SHAPES

 △ 
□ ○
 x 
x = A, ○ = B, □ = X, △ = Y.

PADDLEBOAT_CONTROLLER_LAYOUT_STANDARD

 Y 
X B
 A 

Paddleboat_ControllerStatus

 Paddleboat_ControllerStatus

Current status of a controller (at a specified controller index)

Properties
PADDLEBOAT_CONTROLLER_ACTIVE

Controller is connected and active.

PADDLEBOAT_CONTROLLER_INACTIVE

No controller is connected.

PADDLEBOAT_CONTROLLER_JUST_CONNECTED

Controller has just connected, only seen in a controller status callback.

PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED

Controller has just disconnected, only seen in a controller status callback.

Paddleboat_Controller_Flags

 Paddleboat_Controller_Flags

Paddleboat controller device feature flags as bitmask values AND against Paddleboat_Controller_Info.controllerFlags to determine feature availability.

Properties
PADDLEBOAT_CONTROLLER_FLAG_GENERIC_PROFILE

Bitmask for Paddleboat_Controller_Info.controllerFlags If set, this controller device wasn't found in the internal controller database and a generic button and axis mapping profile is being used.

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

Bitmask for Paddleboat_Controller_Info.controllerFlags If set, this controller device has a touchpad that will register the PADDLEBOAT_BUTTON_TOUCHPAD button when pressed.

PADDLEBOAT_CONTROLLER_FLAG_VIBRATION

Bitmask for Paddleboat_Controller_Info.controllerFlags If set, this controller device supports vibration effects using the Paddleboat_setControllerVibrationData function.

PADDLEBOAT_CONTROLLER_FLAG_VIBRATION_DUAL_MOTOR

Bitmask for Paddleboat_Controller_Info.controllerFlags If set, this controller device supports both left and right vibration motor data for vibration effects.

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

Bitmask for Paddleboat_Controller_Info.controllerFlags If set, this controller device can simulate a virtual mouse and will report coordinates in Paddleboat_Controller_Data.virtualPointer

Paddleboat_ErrorCode

 Paddleboat_ErrorCode

Paddleboat error code results.

Properties
PADDLEBOAT_ERROR_ALREADY_INITIALIZED

Paddleboat_init was called a second time without a call to Paddleboat_destroy in between.

PADDLEBOAT_ERROR_FEATURE_NOT_SUPPORTED

The feature is not supported by the specified controller.

Example: Calling Paddleboat_setControllerVibrationData on a controller that does not have the PADDLEBOAT_CONTROLLER_FLAG_VIBRATION bit set in Paddleboat_Controller_Info.controllerFlags.

PADDLEBOAT_ERROR_INIT_GCM_FAILURE

Paddleboat could not be successfully initialized.

Instantiation of the GameControllerManager class failed.

PADDLEBOAT_ERROR_INVALID_CONTROLLER_INDEX

Invalid controller index specified.

Valid index range is from 0 to PADDLEBOAT_MAX_CONTROLLERS - 1

PADDLEBOAT_ERROR_INVALID_PARAMETER

An invalid parameter was specified.

This usually means NULL or nullptr was passed in a parameter that requires a valid pointer.

PADDLEBOAT_ERROR_NOT_INITIALIZED

Paddleboat was not successfully initialized.

Either Paddleboat_init was not called or returned an error.

PADDLEBOAT_ERROR_NO_CONTROLLER

No controller is connected at the specified controller index.

PADDLEBOAT_ERROR_NO_MOUSE

No virtual or physical mouse device is connected.

PADDLEBOAT_NO_ERROR

No error.

Function call was successful.

Paddleboat_Ignored_Axis

 Paddleboat_Ignored_Axis

Special constants to specify an axis or axis button mapping is ignored by the controller.

Properties
PADDLEBOAT_AXIS_BUTTON_IGNORED

Constant that signifies an axis in the Paddleboat_Controller_Mapping_Data.axisPositiveButtonMapping array and/or Paddleboat_Controller_Mapping_Data.axisNegativeButtonMapping array does not have a mapping to a button.

PADDLEBOAT_AXIS_IGNORED

Constant that signifies an axis in the Paddleboat_Controller_Mapping_Data.axisMapping array is unused by the controller.

Paddleboat_Ignored_Buttons

 Paddleboat_Ignored_Buttons

Special constant to specify a button is ignored by the controller.

Properties
PADDLEBOAT_BUTTON_IGNORED

Constant that signifies a button in the Paddleboat_Controller_Mapping_Data.buttonMapping array does not map to a button on the controller.

Paddleboat_Mapping_Axis

 Paddleboat_Mapping_Axis

Axis order enum of Paddleboat axis mapping table.

Properties
PADDLEBOAT_MAPPING_AXIS_COUNT

Number of axis used for controller mapping configuration.

PADDLEBOAT_MAPPING_AXIS_HATX

Paddleboat internal mapping index for HatX trigger axis.

This is usually the dpad left/right.

PADDLEBOAT_MAPPING_AXIS_HATY

Paddleboat internal mapping index for HatY trigger axis.

This is usually the dpad up/down.

PADDLEBOAT_MAPPING_AXIS_L1

Paddleboat internal mapping index for L1 trigger axis.

PADDLEBOAT_MAPPING_AXIS_L2

Paddleboat internal mapping index for L2 trigger axis.

PADDLEBOAT_MAPPING_AXIS_LEFTSTICK_X

Paddleboat internal mapping index for left thumbstick X axis.

PADDLEBOAT_MAPPING_AXIS_LEFTSTICK_Y

Paddleboat internal mapping index for left thumbstick Y axis.

PADDLEBOAT_MAPPING_AXIS_R1

Paddleboat internal mapping index for R1 trigger axis.

PADDLEBOAT_MAPPING_AXIS_R2

Paddleboat internal mapping index for R2 trigger axis.

PADDLEBOAT_MAPPING_AXIS_RIGHTSTICK_X

Paddleboat internal mapping index for right thumbstick X axis.

PADDLEBOAT_MAPPING_AXIS_RIGHTSTICK_Y

Paddleboat internal mapping index for right thumbstick Y axis.

Paddleboat_MouseStatus

 Paddleboat_MouseStatus

The status of the mouse device.

Properties
PADDLEBOAT_MOUSE_CONTROLLER_EMULATED

A virtual mouse is connected The virtual mouse is being simulated by a game controller.

PADDLEBOAT_MOUSE_NONE

No mouse device is connected.

PADDLEBOAT_MOUSE_PHYSICAL

A physical mouse or trackpad device is connected.

Paddleboat_Mouse_Buttons

 Paddleboat_Mouse_Buttons

Paddleboat mouse buttons as bitmask values AND against Paddleboat_Mouse_Data.buttonsDown to determine button status.

Properties
PADDLEBOAT_MOUSE_BUTTON_6

Bitmask for Paddleboat_Mouse_Data.buttonsDown mouse button 6.

PADDLEBOAT_MOUSE_BUTTON_7

Bitmask for Paddleboat_Mouse_Data.buttonsDown mouse button 7.

PADDLEBOAT_MOUSE_BUTTON_8

Bitmask for Paddleboat_Mouse_Data.buttonsDown mouse button 8.

PADDLEBOAT_MOUSE_BUTTON_BACK

Bitmask for Paddleboat_Mouse_Data.buttonsDown back mouse button.

PADDLEBOAT_MOUSE_BUTTON_FORWARD

Bitmask for Paddleboat_Mouse_Data.buttonsDown forward mouse button.

PADDLEBOAT_MOUSE_BUTTON_LEFT

Bitmask for Paddleboat_Mouse_Data.buttonsDown left mouse button.

PADDLEBOAT_MOUSE_BUTTON_MIDDLE

Bitmask for Paddleboat_Mouse_Data.buttonsDown middle mouse button.

PADDLEBOAT_MOUSE_BUTTON_RIGHT

Bitmask for Paddleboat_Mouse_Data.buttonsDown right mouse button.

Paddleboat_Remap_Addition_Mode

 Paddleboat_Remap_Addition_Mode

The addition mode to use when passing new controller mapping data to Paddleboat_addControllerRemapData.

Properties
PADDLEBOAT_REMAP_ADD_MODE_DEFAULT

If a vendorId/productId controller entry in the new remap table exists in the current database, and the min/max API ranges overlap, replace the existing entry, otherwise add a new entry.

Always adds a new entry if the vendorId/productId does not exist in the current database. These changes only persist for the current session.

PADDLEBOAT_REMAP_ADD_MODE_REPLACE_ALL

The current controller database will be erased and entirely replaced by the new remap table.

This change only persists for the current session.

Typedefs

Paddleboat_ControllerStatusCallback

void(* Paddleboat_ControllerStatusCallback)(const int32_t controllerIndex, const Paddleboat_ControllerStatus controllerStatus, void *userData)

Signature of a function that can be passed to Paddleboat_setControllerStatusCallback to receive information about controller connections and disconnections.

Function will be called on the same thread that calls Paddleboat_update.

Details
Parameters
controllerIndex
Index of the controller that has registered a status change, will range from 0 to PADDLEBOAT_MAX_CONTROLLERS - 1.
controllerStatus
New status of the controller.
userData
The value of the userData parameter passed to Paddleboat_setControllerStatusCallback

Paddleboat_Controller_Data

struct Paddleboat_Controller_Data Paddleboat_Controller_Data

A structure that contains the current data for a controller's inputs and sensors.

Paddleboat_Controller_Info

struct Paddleboat_Controller_Info Paddleboat_Controller_Info

A structure that contains information about a particular controller device.

Several fields are populated by the value of the corresponding fields from InputDevice.

Paddleboat_Controller_Mapping_Data

struct Paddleboat_Controller_Mapping_Data Paddleboat_Controller_Mapping_Data

A structure that describes the button and axis mappings for a specified controller device running on a specified range of Android API levels.


See Paddleboat_Mapping_Axis for axis order. Hat axis should be mapped to dpad buttons.

Paddleboat_Controller_Pointer

struct Paddleboat_Controller_Pointer Paddleboat_Controller_Pointer

A structure that contains virtual pointer position data.

X and Y coordinates are pixel based and range from 0,0 to window width,height.

Paddleboat_Controller_Thumbstick

struct Paddleboat_Controller_Thumbstick Paddleboat_Controller_Thumbstick

A structure that contains X and Y axis data for an analog thumbstick.

Axis ranges from -1.0 to 1.0.

Paddleboat_Controller_Thumbstick_Precision

struct Paddleboat_Controller_Thumbstick_Precision Paddleboat_Controller_Thumbstick_Precision

A structure that contains axis precision data for a thumbstick in the X and Y axis.

Value ranges from 0.0 to 1.0. Flat is the extent of a center flat (deadzone) area of a thumbstick axis Fuzz is the error tolerance (deviation) of a thumbstick axis

Paddleboat_MouseStatusCallback

void(* Paddleboat_MouseStatusCallback)(const Paddleboat_MouseStatus mouseStatus, void *userData)

Signature of a function that can be passed to Paddleboat_setMouseStatusCallback to receive information about mouse device status changes.

Function will be called on the same thread that calls Paddleboat_update.

Details
Parameters
mouseStatus
Current status of the mouse.
userData
The value of the userData parameter passed to Paddleboat_setMouseStatusCallback

Paddleboat_Mouse_Data

struct Paddleboat_Mouse_Data Paddleboat_Mouse_Data

A structure that contains input data for the mouse device.

Paddleboat_Vibration_Data

struct Paddleboat_Vibration_Data Paddleboat_Vibration_Data

A structure that describes the parameters of a vibration effect.

Functions

Paddleboat_addControllerRemapData

void Paddleboat_addControllerRemapData(
  const Paddleboat_Remap_Addition_Mode addMode,
  const int32_t remapTableEntryCount,
  const Paddleboat_Controller_Mapping_Data *mappingData
)

Add new controller remap information to the internal remapping table.

Details
Parameters
addMode
The addition mode for the new data. See the Paddleboat_Remap_Addition_Mode enum for details on each mode.
remapTableEntryCount
the number of remap elements in the mappingData array.
mappingData
An array of controller mapping structs to be added to the internal remapping table. The pointer passed in mappingData is not retained and does not need to persist after function return.

Paddleboat_destroy

void Paddleboat_destroy(
  JNIEnv *env
)

Destroy resources that Paddleboat has created.

See also: Paddleboat_init

Details
Parameters
env
The JNIEnv attached to the thread calling the function.

Paddleboat_getActiveAxisMask

uint64_t Paddleboat_getActiveAxisMask()

Retrieve the active axis ids being used by connected devices.

This can be used to determine what axis values to provide to GameActivityPointerInfo_enableAxis when GameActivity is being used.

Details
Returns
A bitmask of the active axis ids that have been used by connected devices during the current application session.

Paddleboat_getBackButtonConsumed

bool Paddleboat_getBackButtonConsumed()

Get whether Paddleboat consumes AKEYCODE_BACK key events from devices being managed by Paddleboat.

The default at initialization is true.

Details
Returns
If true, Paddleboat will consume AKEYCODE_BACK key events, if false it will pass them through.

Paddleboat_getControllerData

Paddleboat_ErrorCode Paddleboat_getControllerData(
  const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData
)

Retrieve the current controller data from the controller with the specified index.

Details
Parameters
controllerIndex
The index of the controller to read from, must be between 0 and PADDLEBOAT_MAX_CONTROLLERS - 1
controllerData
a pointer to the controller data struct to populate.
Returns
PADDLEBOAT_NO_ERROR if data was successfully read.

Paddleboat_getControllerInfo

Paddleboat_ErrorCode Paddleboat_getControllerInfo(
  const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo
)

Retrieve the current controller device info from the controller with the specified index.

Details
Parameters
controllerIndex
The index of the controller to read from, must be between 0 and PADDLEBOAT_MAX_CONTROLLERS - 1
controllerInfo
a pointer to the controller device info struct to populate.
Returns
true if the data was read, false if there was no connected controller at the specified index.

Paddleboat_getControllerName

Paddleboat_ErrorCode Paddleboat_getControllerName(
  const int32_t controllerIndex,
  const size_t bufferSize,
  char *controllerName
)

Retrieve the current controller name from the controller with the specified index.

This name is retrieved from InputDevice.getName().

Details
Parameters
controllerIndex
The index of the controller to read from, must be between 0 and PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize
The capacity in bytes of the string buffer passed in controllerName
controllerName
A pointer to a buffer that will be populated with the name string. The name string is a C string in UTF-8 format. If the length of the string is greater than bufferSize the string will be truncated to fit.
Returns
PADDLEBOAT_NO_ERROR if data was successfully read.

Paddleboat_getControllerRemapTableData

int32_t Paddleboat_getControllerRemapTableData(
  const int32_t destRemapTableEntryCount,
  Paddleboat_Controller_Mapping_Data *mappingData
)

Retrieve the current table of controller remap entries.

Details
Parameters
destRemapTableEntryCount
the number of Paddleboat_Controller_Mapping_Data entries in the array passed in the mappingData parameter. Paddleboat will not copy more than this number of entries out of the internal array to avoid overflowing the buffer.
mappingData
pointer to an array of Paddleboat_Controller_Mapping_Data structures. this should contain at least destRemapTableEntryCount elements. Passing nullptr is valid, and can be used to get the number of elements in the internal remap table.
Returns
The number of elements in the internal remap table.

Paddleboat_getControllerStatus

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex
)

Retrieve the current controller device info from the controller with the specified index.

Details
Parameters
controllerIndex
The index of the controller to read from, must be between 0 and PADDLEBOAT_MAX_CONTROLLERS - 1.
Returns
Paddleboat_ControllerStatus enum value of the current controller status of the specified controller index.

Paddleboat_getLastKeycode

int32_t Paddleboat_getLastKeycode()

An function that returns the last keycode seen in a key event coming from a controller owned by Paddleboat.

Useful for debugging unknown buttons in new devices in the sample app

Details
Returns
keycode from last controller key event.

Paddleboat_getMouseData

Paddleboat_ErrorCode Paddleboat_getMouseData(
  Paddleboat_Mouse_Data *mouseData
)

Retrieve the current mouse data.

Details
Parameters
mouseData
pointer to the mouse data struct to populate.
Returns
true if the data was read, false if there was no connected mouse device.

Paddleboat_getMouseStatus

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

Retrieve the current controller device info from the controller with the specified index.

Details
Returns
Paddleboat_MouseStatus enum value of the current mouse status.

Paddleboat_init

Paddleboat_ErrorCode Paddleboat_init(
  JNIEnv *env,
  jobject jcontext
)

Initialize Paddleboat, constructing internal resources via JNI.

This may be called after calling Paddleboat_destroy to reinitialize the library. See also:Paddleboat_destroy

Details
Parameters
env
The JNIEnv attached to the thread calling the function.
jcontext
A Context derived object used by the game. This can be an Activity derived class.
Returns
PADDLEBOAT_NO_ERROR if successful, otherwise an error code relating to initialization failure.

Paddleboat_isInitialized

bool Paddleboat_isInitialized()

Check if Paddleboat was successfully initialized.

Details
Returns
false if the initialization failed or was not called.

Paddleboat_onStart

void Paddleboat_onStart(
  JNIEnv *env
)

Inform Paddleboat that a start event was sent to the application.

Details
Parameters
env
The JNIEnv attached to the thread calling the function.

Paddleboat_onStop

void Paddleboat_onStop(
  JNIEnv *env
)

Inform Paddleboat that a stop event was sent to the application.

Details
Parameters
env
The JNIEnv attached to the thread calling the function.

Paddleboat_processGameActivityKeyInputEvent

int32_t Paddleboat_processGameActivityKeyInputEvent(
  const void *event,
  const size_t eventSize
)

Process a GameActivityKeyEvent input event to see if it is from a device being managed by Paddleboat.

At least once per game frame, the game should iterate through reported GameActivityKeyEvents and pass them to Paddleboat_processGameActivityKeyInputEvent for evaluation.

Details
Parameters
event
the GameActivityKeyEvent input event received by the application.
eventSize
the size of the GameActivityKeyEvent struct being passed in bytes.
Returns
0 if the event was ignored, 1 if the event was processed/consumed by Paddleboat.

Paddleboat_processGameActivityMotionInputEvent

int32_t Paddleboat_processGameActivityMotionInputEvent(
  const void *event,
  const size_t eventSize
)

Process a GameActivityMotionEvent input event to see if it is from a device being managed by Paddleboat.

At least once per game frame, the game should iterate through reported GameActivityMotionEvents and pass them to Paddleboat_processGameActivityMotionInputEvent for evaluation.

Details
Parameters
event
the GameActivityMotionEvent input event received by the application.
eventSize
the size of the GameActivityMotionEvent struct being passed in bytes.
Returns
0 if the event was ignored, 1 if the event was processed/consumed by Paddleboat.

Paddleboat_processInputEvent

int32_t Paddleboat_processInputEvent(
  const AInputEvent *event
)

Process an input event to see if it is from a device being managed by Paddleboat.

Details
Parameters
event
the input event received by the application.
Returns
0 if the event was ignored, 1 if the event was processed/consumed by Paddleboat.

Paddleboat_setBackButtonConsumed

void Paddleboat_setBackButtonConsumed(
  bool consumeBackButton
)

Set whether Paddleboat consumes AKEYCODE_BACK key events from devices being managed by Paddleboat.

The default at initialization is true. This can be set to false to allow exiting the application from a back button press when the application is in an appropriate state (i.e. the title screen).

Details
Parameters
consumeBackButton
If true, Paddleboat will consume AKEYCODE_BACK key events, if false it will pass them through.

Paddleboat_setControllerStatusCallback

void Paddleboat_setControllerStatusCallback(
  Paddleboat_ControllerStatusCallback statusCallback,
  void *userData
)

Set a callback to be called whenever a controller managed by Paddleboat changes status.

This is used to inform of controller connections and disconnections.

Details
Parameters
statusCallback
function pointer to the controllers status change callback, passing NULL or nullptr will remove any currently registered callback.
userData
optional pointer (may be NULL or nullptr) to user data that will be passed as a parameter to the status callback. A reference to this pointer will be retained internally until changed by a future call to Paddleboat_setControllerStatusCallback

Paddleboat_setControllerVibrationData

Paddleboat_ErrorCode Paddleboat_setControllerVibrationData(
  const int32_t controllerIndex,
  const Paddleboat_Vibration_Data *vibrationData,
  JNIEnv *env
)

Set vibration data for the controller with the specified index.

Details
Parameters
controllerIndex
The index of the controller to read from, must be between 0 and PADDLEBOAT_MAX_CONTROLLERS - 1.
vibrationData
The intensity and duration data for the vibration effect. Valid intensity range is from 0.0 to 1.0. Intensity of 0.0 will turn off vibration if it is active. Duration is specified in milliseconds. The pointer passed in vibrationData is not retained and does not need to persist after function return.
env
The JNIEnv attached to the thread calling the function.
Returns
true if the vibration data was set, false if there was no connected controller or the connected controller does not support vibration.

Paddleboat_setMouseStatusCallback

void Paddleboat_setMouseStatusCallback(
  Paddleboat_MouseStatusCallback statusCallback,
  void *userData
)

Set a callback to be called when the mouse status changes.

This is used to inform of physical or virual mouse device connections and disconnections.

Details
Parameters
statusCallback
function pointer to the controllers status change callback, passing NULL or nullptr will remove any currently registered callback.
userData
optional pointer (may be NULL or nullptr) to user data that will be passed as a parameter to the status callback. A reference to this pointer will be retained internally until changed by a future call to Paddleboat_setMouseStatusCallback

Paddleboat_update

void Paddleboat_update(
  JNIEnv *env
)

Updates internal Paddleboat status and processes pending connection/disconnections.

Paddleboat_update is responsible for triggering any registered controller or mouse status callbacks, those callbacks will fire on the same thread that called Paddleboat_update. This function should be called once per game frame. It is recommended to call Paddleboat_update before sending any new input events or reading controller inputs for a particular game frame.

Details
Parameters
env
The JNIEnv attached to the thread calling the function.

Macros

PADDLEBOAT_MAX_CONTROLLERS

 PADDLEBOAT_MAX_CONTROLLERS 8

Maximum number of simultaneously connected controllers.