general.h

Go to the documentation of this file.

/*
 * general.h
 *
 * Bogus file for doxygen.  Don't use this file!
 */

/// \ingroup gamepad
/// \defgroup gamepad_general General Gamepad Overview
///
/// To use this library, you need to be aware of a few key concepts.
///  - <b>Source Devices</b>  These abstract hardware devices (such as
///     controllers, or USB adapters that expose multiple controllers).
///     Source Devices (\ref gamepad::SourceDevice) generate the raw input
///     events that are then mapped to actual gamepad objects.
///  - <b>Gamepad Types</b> A gamepad type (\ref 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.
///  - <b>Mapping</b> 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.
///  - <b>Gamepad</b> 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.
///  - <b>Manager</b> 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.
///
/// \n
/// <b>Configuration of Gamepads</b><br/>
/// 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.
///
/// \n
/// <b>How to Use This Library</b><br/>
/// 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 \ref gamepad_general_sdk)
///
/// \n
/// <b>Support for other Gamepad Types</b><br/>
/// 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
/// \b data directory off the main gamepad directory.  There are two files
/// you'll probably want to provide:
///  - <b>.gamepad</b>  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.
///  - <b>.vgfx</b> 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 \b strings subdirectory so that
/// people can localize the user-facing strings associated with the gamepad.