To use this library, you need to be aware of a few key concepts. More...
|
Modules | |
| Gamepad Localization | |
The Gamepad library is built to natively support any locale (although I suspect it only works well for left-to-right languages). | |
| Linux-Specific Notes | |
This library uses the linux joystick APIs to read gamepad events. | |
| Simple SDK | |
The Wavepacket family of repositories use a very granular set of libraries, so it is easy to mix and max functionality when constructing programs. | |
| Win32 Notes | |
This library uses DirectInput for gamepad events in Win32. | |
Detailed Description
To use this library, you need to be aware of a few key concepts.
- Source Devices These abstract hardware devices (such as controllers, or USB adapters that expose multiple controllers). Source Devices (gamepad::SourceDevice) generate the raw input events that are then mapped to actual gamepad objects.
- Gamepad Types A gamepad type (gamepad::Type) gives information about a type of gamepad, for instance, Playstation 3 or XBox 360 or Nintendo 64, etc. Your code can look at gamepad::Type objects to see how many joysticks are supported on the gamepad, how many buttons, etc.
- Mapping A mapping object maps from raw Source Device events to a particular Gamepad. Mappings are required because even the exact same physical gamepad device may expose different Source Device events depending on USB adapters, manufacturers, etc. In fact, most of the purpose of this library is to make Mappings (gamepad::Map) easy to create and manage.
- Gamepad A gamepad (gamepad::Gamepad) is an actual instance of a gamepad. Once you have a Source Device and a Mapping, you can combine the two to create a logical gamepad::Gamepad device, and read inputs from that.
- Manager The gamepad::Manager object is what holds all the known gamepad::SourceDevice objects, all the gamepad::Map objects, and all the created gamepad::Gamepad objects.
Configuration of Gamepads
Most of the work of this library is automating the mapping from raw hardware inputs into meaningful gamepad events. For instance, the hardware may say "axis 7 was just moved to position 55" and this library will do the mapping to say "gamepad 2, which is an XBox 360
gamepad, just had its left direction pad pushed up".
In general, the mappings aren't known ahead of time. I suspect that directly-attached gamepads (such as Playstation 3 and XBox 360 controllers) may have stable mappings. But in general, gamepads will provide random hardware inputs, so it won't always be possible to hard-code the mappings. Instead, we'll need the user (whoever is actually holding the controller) to configure the gamepad manually so we can figure the mapping out.
To do that, this library exposes a Configurator object (gamepad::Configurator) to walk the user through configuration. The Configurator has no UI, just an API. This way, the Configurator can be used in any rendering system (OpenGL, DirectX, whatever). The gamepad-opengl project in SourceForge has an OpenGL example program that uses the Configurator to configure gamepads.
The Configurator is designed to be run in games etc. that are running in a rendering loop (or other event loop). To use the Configurator, create it and then call update() during each event loop (you should also call update() on the gamepad::Manager each iteration so that source devices have state updated). The Configurator will tell you where it is in the configuration process, and what it wants the user to do next, by returning a config_status_t structure.
See the configureGamepad tool as an example of how the Configurator can be used to configure gamepads in an event loop. The gamepad-opengl sourceforge project has a graphical example.
Once the Configurator has finished, it will produce a mapping (gamepad::Map) that you can use to create a Gamepad object.
You can also save/load completed gamepad::Map objects so users don't have to re-configure their gamepads every time they play your game.
How to Use This Library
Usually, your code will do this:
- Create a gamepad::Manager object at program startup.
- Call gamepad::Manager::rediscover() infrequently (once per second?) to detect if gamepads have been attached or detached.
- Call gamepad::Manager::update() every frame to gather the most recent gamepad events
- Use the gamepad::Configurator to help the user configure gamepads when necessary.
- Use gamepad::Map objects (from the Configurator, or loaded from disk) to create gamepad::Gamepad objects from given gamepad::SourceDevice objects.
- Link using the single SDK library (see Simple SDK)
Support for other Gamepad Types
This library is completely data-driven. I've provided built-in support for several common gamepads, such as:
- Playstation 2
- Playstation 3
- XBox 360
- Nintendo 64
You can always add your own type of gamepad! All of the data is in the data directory off the main gamepad directory. There are two files you'll probably want to provide:
- .gamepad This file contains the raw data about the gamepad, such as how many joysticks, direction pads, and buttons a gamepad has, and the logical name of each.
- .vgfx This file contains vector graphics rendering instructions so that the gamepad can be rendered on any platform.
If you add your own gamepad type, you should also provide a locale file in the appropriate directory in the strings subdirectory so that people can localize the user-facing strings associated with the gamepad.
