source-device.h

Go to the documentation of this file.

/*
 * source-device.h
 *
 * Copyright (C) 2009-2011  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Abstraction for a device that can act as the source of gamepad events.  This
 * is often a wrapper around a particular USB adapter, for instance
 */

#ifndef GAMEPAD_SOURCE_DEVICE_H__
#define GAMEPAD_SOURCE_DEVICE_H__

// includes --------------------------------------------------------------------
#include "common/common.h"
#include "threadsafe/smart_ptr.h"


namespace gamepad {


/// \ingroup gamepad_api
/// \defgroup source_device Source Device Interface
///
/// 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.
/*@{*/


/// 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.
enum eButton {
        // current state
        eButtonDown             = 0x01, ///< button is pushed down right now
        eButtonUp               = 0x00, ///< button is not pushed down now

        // recent state
        eButtonWasPushed        = 0x10, ///< button was pushed at one point
        eButtonWasReleased      = 0x20, ///< button was released at one point

        // handy masks
        eButtonWasOrIsDown      = 0x11, ///< button was or is pushed down

        // keep this last!
        eButtonInvalid          = 0x80
};



/// 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.
enum eDeviceState {

        // attached state.  These are exclusive values.
        eDevice_Attached = 0x0001, ///< device is properly attached
        eDevice_Detached = 0x0002, ///< device is definitely not attached
        eDevice_Unknown  = 0x0004, ///< may or may not be attached--common!

        // keep this last
        eDevice_Invalid = 0
};



/// what you get back when you read the value of a particular potentiometer
struct pot_value_t {
        enum eConstants {
                eStartMin       = (+1000) * (1000),
                eStartMax       = (-1000) * (1000)
        };

        // constructor, manipulators
        pot_value_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        minSeen = eStartMin;
                        maxSeen = eStartMax;
                        value = 0;
                }
        void dump(IN const char * title) const throw() {
                        DPRINTF("%s  val=%d  [%d - %d]",
                            title, value, minSeen, maxSeen);
                }
        bool isValid(void) const throw() {
                        return (minSeen < maxSeen &&
                                value >= minSeen &&
                                value <= maxSeen);
                }
        void update(IN int newValue) throw() {
                        value = newValue;
                        if (value < minSeen)
                                minSeen = value;
                        if (value > maxSeen)
                                maxSeen = value;
                }

        // data fields
        int     minSeen;        ///< minimum value seen
        int     maxSeen;        ///< maximum value seen
        int     value;          ///< current (most recent) value
};



/// 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.
byte_t updateButton(IN byte_t oldBitFlags, IN bool isButtonDown) throw();



/// An object that supplies gamepad input.  Often this is a USB device, for
/// instance, that may support multiple different types of gamepads plugged in
/// at once.  Regardless of how many gamepads are plugged in, a SourceDevice
/// is supposed to represent a physical or logical device (USB device or the
/// bluetooth subsystem as respective examples) that supports polling
/// independent of other SourceDevice objects.
///
/// Force feedback support is purposely limited for now.  If you want rich
/// force feedback support, you should probably work closer to the native
/// drivers.
class SourceDevice {
public:
        // virtual destructor --------------------------------------------------
        virtual ~SourceDevice(void) throw();

        // gamepad::SourceDevice class interface methods -----------------------

        /// 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).
        /// \b 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.
        /// \b 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 * getPublicName(void) throw() = 0;

        /// 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 const char * getUniqueId(void) throw() = 0;

        /// 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 eDeviceState getState(void) throw() = 0;

        /// 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 getNumPots(void) throw() = 0;

        /// 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 int getNumButtons(void) throw() = 0;

/*
        // Jan 2011: removing all force feedback support for now
        /// the source must say how many force feedback rumble objects are
        ///     supported.  Typically there are one per gamepad, for instance.
        //virtual int getNumRumblers(void) throw() = 0;
 */

        /// 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 void poll(void) throw() = 0;

        /// retrieves the value of a particular potentiometer. 
        virtual const pot_value_t& getPotValue(IN int potIndex) = 0;

        /// 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 eButton getButtonValue(IN int buttonIndex) = 0;

/*
        // Jan 2011: removing all force feedback support for now
        /// plays the given rumbler effect.  Returns false on failure
        virtual bool playRumble(IN int rumbleIndex,
                                IN uint16_t highFreqMagnitude,
                                IN uint16_t lowFreqMagnitude,
                                IN int durationMilliseconds) = 0;
*/
};



/// objects supporting this interface can create gamepad::SourceDevice
///     instances.
/// Note to implementers (and users): objects supporting this interface are
///     intended to be long-lived.  So if you write an object that supports this 
///     interface, it should re-poll (or do whatever discovery is necessary) on
///     every API call, and not rely on one-time discovery during object
///     initialization.  In particular, it is expected that
///     SourceDeviceFactory::getCount() will be expensive to call.
class SourceDeviceFactory {
public:
        // virtual destructor --------------------------------------------------
        virtual ~SourceDeviceFactory(void) throw();

        // gamepad::SourceDeviceFactory class interface methods ----------------
        virtual const char * getName(void) const throw() = 0;
        virtual int getCount(void) = 0;
        virtual smart_ptr<SourceDevice> getSourceDevice(IN int index) = 0;
};



/// state snapshot of a source device.  Used by configuration tools only
struct device_state_t {
        // enums
        enum eConstants {
                eMaxButtons     = 256,
                eMaxPots        = 256
        };

        // constructor, manipulators
        device_state_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        nPots = nButtons = 0;
                }
        void dump(IN const char * title) const throw() {
                        DPRINTF("%s (source device state snapshot)", title);
                        DPRINTF("  Number of potentiometers: %d", nPots);
                        DPRINTF("  Number of buttons: %d", nButtons);
                }

        // data fields
        int             nPots;
        int             nButtons;
        int             button[eMaxButtons];
        pot_value_t     pot[eMaxPots];
};



/// take a state snapshot
void snapshotState(IN SourceDevice * device,
                        OUT device_state_t& state);


/// is a single button down?
int buttonDown(IN const device_state_t& state);


/// was a button released?
int buttonReleased(IN const device_state_t& state);


/// compare new and old states: did a single button change state?
int buttonChanged(IN const device_state_t& oldState,
                        IN const device_state_t& newState);


/// compare new and old states: are all potentiometers calibrated?
bool potsCalibrated(IN const device_state_t& oldState,
                        IN const device_state_t& newState);


/// get pot at largest value--specify threshold: 0 (min) to 1 (max).
///     pots with values under the threshold will be ignored.
int maxPotValue(IN const device_state_t& state,
                        IN float threshold);


/// compare new and old states: which potentiometer has changed most?
int maxPotChanged(IN const device_state_t& oldState,
                        IN const device_state_t& newState);


};      // gamepad namespace

#endif  // GAMEPAD_SOURCE_DEVICE_H__