This library exists to abstract the gamepad library from physical input sources. More...
|
Classes | |
| struct | gamepad::pot_value_t |
| what you get back when you read the value of a particular potentiometer More... | |
| class | gamepad::SourceDevice |
| An object that supplies gamepad input. More... | |
| class | gamepad::SourceDeviceFactory |
| objects supporting this interface can create gamepad::SourceDevice instances. More... | |
| struct | gamepad::device_state_t |
| state snapshot of a source device. Used by configuration tools only More... | |
Modules | |
| DirectInput Gamepad Devices | |
APIs to provide gamepad::SourceDevice objects based on the Microsoft DirectX DirectInput APIs. | |
| Linux Input Gamepad Devices (Deprecated) | |
APIs to provide gamepad::SourceDevice objects based on the linux input event model (see the header file /usr/include/linux/input.h). | |
| Linux Joystick Gamepad Devices | |
APIs to provide gamepad::SourceDevice objects based on the linux joystick event model (see the header file /usr/include/linux/joystick.h). | |
Enumerations | |
| enum | gamepad::eButton { gamepad::eButtonDown = 0x01, gamepad::eButtonUp = 0x00, gamepad::eButtonWasPushed = 0x10, gamepad::eButtonWasReleased = 0x20, gamepad::eButtonWasOrIsDown = 0x11, gamepad::eButtonInvalid = 0x80 } |
button state enum. More... | |
| enum | gamepad::eDeviceState { gamepad::eDevice_Attached = 0x0001, gamepad::eDevice_Detached = 0x0002, gamepad::eDevice_Unknown = 0x0004, gamepad::eDevice_Invalid = 0 } |
device state enum. More... | |
Functions | |
| gamepad::pot_value_t::pot_value_t (void) throw () | |
| void | gamepad::pot_value_t::clear (void) throw () |
| void | gamepad::pot_value_t::dump (IN const char *title) const throw () |
| bool | gamepad::pot_value_t::isValid (void) const throw () |
| void | gamepad::pot_value_t::update (IN int newValue) throw () |
| byte_t | gamepad::updateButton (IN byte_t oldBitFlags, IN bool isButtonDown) throw () |
| helper method to update a button value. | |
| virtual const char * | gamepad::SourceDevice::getPublicName (void)=0 throw () |
| a "pretty" name, often the manufacturer and model, for instance. | |
| virtual const char * | gamepad::SourceDevice::getUniqueId (void)=0 throw () |
| each source device MUST supply a unique ID. | |
| virtual eDeviceState | gamepad::SourceDevice::getState (void)=0 throw () |
| returns the current state of the source device. | |
| virtual int | gamepad::SourceDevice::getNumPots (void)=0 throw () |
| the source must say how many pots (potentiometers) are exposed. | |
| virtual int | gamepad::SourceDevice::getNumButtons (void)=0 throw () |
| the source must say how many buttons are exposed. | |
| virtual void | gamepad::SourceDevice::poll (void)=0 throw () |
| the source will be asked to poll all of its inputs. | |
| virtual const pot_value_t & | gamepad::SourceDevice::getPotValue (IN int potIndex)=0 |
| retrieves the value of a particular potentiometer. | |
| virtual eButton | gamepad::SourceDevice::getButtonValue (IN int buttonIndex)=0 |
| retrieves the state of a particular button. | |
| virtual const char * | gamepad::SourceDeviceFactory::getName (void) const =0 throw () |
| virtual int | gamepad::SourceDeviceFactory::getCount (void)=0 |
| virtual smart_ptr< SourceDevice > | gamepad::SourceDeviceFactory::getSourceDevice (IN int index)=0 |
| gamepad::device_state_t::device_state_t (void) throw () | |
| void | gamepad::device_state_t::clear (void) throw () |
| void | gamepad::device_state_t::dump (IN const char *title) const throw () |
| void | gamepad::snapshotState (IN SourceDevice *device, OUT device_state_t &state) |
| take a state snapshot | |
| int | gamepad::buttonDown (IN const device_state_t &state) |
| is a single button down? | |
| int | gamepad::buttonReleased (IN const device_state_t &state) |
| was a button released? | |
| int | gamepad::buttonChanged (IN const device_state_t &oldState, IN const device_state_t &newState) |
| compare new and old states: did a single button change state? | |
| bool | gamepad::potsCalibrated (IN const device_state_t &oldState, IN const device_state_t &newState) |
| compare new and old states: are all potentiometers calibrated? | |
| int | gamepad::maxPotValue (IN const device_state_t &state, IN float threshold) |
| get pot at largest value--specify threshold: 0 (min) to 1 (max). | |
| int | gamepad::maxPotChanged (IN const device_state_t &oldState, IN const device_state_t &newState) |
| compare new and old states: which potentiometer has changed most? | |
Variables | |
| int | gamepad::pot_value_t::minSeen |
| minimum value seen | |
| int | gamepad::pot_value_t::maxSeen |
| maximum value seen | |
| int | gamepad::pot_value_t::value |
| current (most recent) value | |
| int | gamepad::device_state_t::nPots |
| int | gamepad::device_state_t::nButtons |
| int | gamepad::device_state_t::button [eMaxButtons] |
| pot_value_t | gamepad::device_state_t::pot [eMaxPots] |
Detailed Description
This library exists to abstract the gamepad library from physical input sources.
You can use the gamepad library to map any input to a gamepad, so long as you supply an object that supports this interface.
See linux_input for an example of a SourceDevice implemented on top of the linux input event model.
Enumeration Type Documentation
| enum gamepad::eButton |
button state enum.
Note that button state is somewhat tricky! Many (or most) source devices will give a full event history, so that every single button press will be recorded. But this interface uses polling rather than events, and therefore multiple button press events could be compressed into a single "button is down" result. If your game requires full eventing (capture every single button press regardless of polling interval) then you probably need to use raw input APIs directly. For most uses the eButtonWasPushed/eButtonWasReleased flags should be sufficient.
- Enumerator:
Definition at line 67 of file source-device.h.
device state enum.
At the moment these are exclusive values, but other device flags may be supported in the future, so I recommend performing bit-check operations rather than checking for equality. "Attached" means that the device is capable of sending events, even if it isn't physically attached. For instance, a wireless or bluetooth device is considered attached if it is communicating with the local host. "Detached" means that the device has been physically disconnected and/or turned off so no more events can be retrieved.
- Enumerator:
eDevice_Attached device is properly attached
eDevice_Detached device is definitely not attached
eDevice_Unknown may or may not be attached--common!
eDevice_Invalid
Definition at line 94 of file source-device.h.
Function Documentation
| gamepad::pot_value_t::pot_value_t | ( | void | ) | throw () [inline, inherited] |
Definition at line 115 of file source-device.h.
| void gamepad::pot_value_t::clear | ( | void | ) | throw () [inline, inherited] |
Definition at line 116 of file source-device.h.
| void gamepad::pot_value_t::dump | ( | IN const char * | title | ) | const throw () [inline, inherited] |
Definition at line 121 of file source-device.h.
| bool gamepad::pot_value_t::isValid | ( | void | ) | const throw () [inline, inherited] |
Definition at line 125 of file source-device.h.
| void gamepad::pot_value_t::update | ( | IN int | newValue | ) | throw () [inline, inherited] |
Definition at line 130 of file source-device.h.
| byte_t gamepad::updateButton | ( | IN byte_t | oldBitFlags, | |
| IN bool | isButtonDown | |||
| ) | throw () |
helper method to update a button value.
Given an input set of eButton bit flags, and the current button state (up or down), returns a new set of button bit flags.
| virtual const char* gamepad::SourceDevice::getPublicName | ( | void | ) | throw () [pure virtual, inherited] |
a "pretty" name, often the manufacturer and model, for instance.
note that this is recommended for debugging but not necessarily for display to the end gamer (string may not be meaningful, and almost certainly isn't localized). NOTE: this should come directly from the hardware itself, and not be modified by any code. This gives developers a chance to identify hardware by name. WARNING: despite what I just said, be careful about identifying hardware by public name. In testing, I've found many USB adaptors have the same hardware-specified information, even though they behave quite differently. So only use the public name for devices you know will have consistent behavior. In practice, this will tend to be gamepads that directly attach via USB and not adaptors (for instance, XBox 360 and Playstation3 controllers).
| virtual const char* gamepad::SourceDevice::getUniqueId | ( | void | ) | throw () [pure virtual, inherited] |
each source device MUST supply a unique ID.
The ID must be unique to that physical device, not just the manufacturer and model! So for instance if a gamer plugged in two identical USB adapters, the unique ID would still be different for each. Sometimes (rarely) manufacturers make the serial number of their adapters/joysticks available. Barring that, anyone who implements this interface has to ensure the IDs are unique. These IDs should be unique for the lifetime of the device (this process) but are not generally valid across process lifetimes, and so should not be persisted.
| virtual eDeviceState gamepad::SourceDevice::getState | ( | void | ) | throw () [pure virtual, inherited] |
returns the current state of the source device.
Note that many sources aren't capable of determining whether or not they are attached! This is annoying but reflects either poor standards or the physical realities of the device in question. If someone disconnects a gamepad (or turns it off in the case of wireless gamepads) you'll stop receiving events and the poll() call won't actually do anything. Call this method occasionally so you can detect when a player has disconnected a device.
| virtual int gamepad::SourceDevice::getNumPots | ( | void | ) | throw () [pure virtual, inherited] |
the source must say how many pots (potentiometers) are exposed.
A "pot" is any input that allows the user to continuously vary it through a range of values. An example is the X or Y axis of a joystick, or a single axis in the case of steering wheels. See http://en.wikipedia.org/wiki/Potentiometer This is the total number of pots supported by the source device, NOT the number of pots per gamepad (the two numbers will often be the same for single-gamepad devices).
| virtual int gamepad::SourceDevice::getNumButtons | ( | void | ) | throw () [pure virtual, inherited] |
the source must say how many buttons are exposed.
This is the total number of buttons for the source device, NOT the number of buttons per gamepad (again, some source devices may support multiple gamepads).
| virtual void gamepad::SourceDevice::poll | ( | void | ) | throw () [pure virtual, inherited] |
the source will be asked to poll all of its inputs.
This is so that later calls to getPotValue() or getButtonValue() will return the current value.
| virtual const pot_value_t& gamepad::SourceDevice::getPotValue | ( | IN int | potIndex | ) | [pure virtual, inherited] |
retrieves the value of a particular potentiometer.
| virtual eButton gamepad::SourceDevice::getButtonValue | ( | IN int | buttonIndex | ) | [pure virtual, inherited] |
retrieves the state of a particular button.
Typically this is eButtonDown or eButtonUp, maybe OR'd with eButtonWasPushed if the button was ever pushed between this and the previous poll interval. See the eButton enum.
| virtual const char* gamepad::SourceDeviceFactory::getName | ( | void | ) | const throw () [pure virtual, inherited] |
| virtual int gamepad::SourceDeviceFactory::getCount | ( | void | ) | [pure virtual, inherited] |
| virtual smart_ptr<SourceDevice> gamepad::SourceDeviceFactory::getSourceDevice | ( | IN int | index | ) | [pure virtual, inherited] |
| gamepad::device_state_t::device_state_t | ( | void | ) | throw () [inline, inherited] |
Definition at line 288 of file source-device.h.
| void gamepad::device_state_t::clear | ( | void | ) | throw () [inline, inherited] |
Definition at line 289 of file source-device.h.
| void gamepad::device_state_t::dump | ( | IN const char * | title | ) | const throw () [inline, inherited] |
Definition at line 292 of file source-device.h.
| void gamepad::snapshotState | ( | IN SourceDevice * | device, | |
| OUT device_state_t & | state | |||
| ) |
take a state snapshot
| int gamepad::buttonDown | ( | IN const device_state_t & | s | ) |
is a single button down?
| int gamepad::buttonReleased | ( | IN const device_state_t & | s | ) |
was a button released?
| int gamepad::buttonChanged | ( | IN const device_state_t & | s0, | |
| IN const device_state_t & | s1 | |||
| ) |
compare new and old states: did a single button change state?
| bool gamepad::potsCalibrated | ( | IN const device_state_t & | s0, | |
| IN const device_state_t & | s1 | |||
| ) |
compare new and old states: are all potentiometers calibrated?
| int gamepad::maxPotValue | ( | IN const device_state_t & | state, | |
| IN float | threshold | |||
| ) |
get pot at largest value--specify threshold: 0 (min) to 1 (max).
pots with values under the threshold will be ignored.
| int gamepad::maxPotChanged | ( | IN const device_state_t & | s0, | |
| IN const device_state_t & | s1 | |||
| ) |
compare new and old states: which potentiometer has changed most?
Variable Documentation
int gamepad::pot_value_t::minSeen [inherited] |
minimum value seen
Definition at line 139 of file source-device.h.
int gamepad::pot_value_t::maxSeen [inherited] |
maximum value seen
Definition at line 140 of file source-device.h.
int gamepad::pot_value_t::value [inherited] |
current (most recent) value
Definition at line 141 of file source-device.h.
int gamepad::device_state_t::nPots [inherited] |
Definition at line 299 of file source-device.h.
int gamepad::device_state_t::nButtons [inherited] |
Definition at line 300 of file source-device.h.
int gamepad::device_state_t::button[eMaxButtons] [inherited] |
Definition at line 301 of file source-device.h.
pot_value_t gamepad::device_state_t::pot[eMaxPots] [inherited] |
Definition at line 302 of file source-device.h.
