gamepad-map.h

Go to the documentation of this file.

/*
 * gamepad-map.h
 *
 * Copyright (C) 2008-2010  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.
 *
 *
 * Gamepad mapping.  This contains most of the important definitions used in the
 * API.
 */

#ifndef GAMEPAD_GAMEPAD_MAP_H__
#define GAMEPAD_GAMEPAD_MAP_H__


// includes --------------------------------------------------------------------
#include "gamepad-type.h"

#include "source-device/source-device.h"


namespace gamepad {


/// \ingroup gamepadlib
/*@{*/


/// the current position of a dpad.  A dpad is a "Directional Pad", see
///     http://en.wikipedia.org/wiki/D-pad
enum eDpad {
        eDpad_Centered          = 0, ///< dpad is not pressed or tilted at all
        eDpad_Left              = 1, ///< pushed left
        eDpad_Right             = 2, ///< pushed right
        eDpad_Up                = 4, ///< pushed up
        eDpad_Down              = 8, ///< pushed straight down

        // composite values
        eDpad_UpLeft            = eDpad_Up   | eDpad_Left,
        eDpad_UpRight           = eDpad_Up   | eDpad_Right,
        eDpad_DownLeft          = eDpad_Down | eDpad_Left,
        eDpad_DownRight         = eDpad_Down | eDpad_Right,

        // keep this last!
        eDpad_Invalid           = 16
};



/// button mapping information
struct button_map_t {
        button_map_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        index = -1;
                }
        void dump(IN const char * title) const throw() {
                        DPRINTF("%s (button map): index=%d", title, index);
                }
        bool isValid(void) const throw() {
                        return (index >= 0);
                }

        // data fields
        int             index;  ///< button or pot index
};



/// all button values OR'd together
typedef uint32_t buttons_t;     // TODO: deprecate?


/// a joystick is a 2-axis stick
struct joystick_t {
        // constructor, manipulators
        joystick_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        x.clear();
                        y.clear();
                }

        // data fields
        pot_value_t     x;      ///< current x-axis potentiometer value
        pot_value_t     y;      ///< current y-axis potentiometer value
};


/// describes joystick mapping
struct joystick_map_t {
        joystick_map_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        xIndex = yIndex = -1;
                }
        void dump(IN const char * title) const throw() {
                        DPRINTF("%s (joystick map):  xIndex=%d  yIndex=%d",
                            title, xIndex, yIndex);
                }
        bool isValid(void) const throw() {
                        return (xIndex >= 0 && yIndex >= 0);
                }

        // data fields
        int             xIndex;         ///< index of x axis potentiometer
        int             yIndex;         ///< index of y axis potentiometer
};


/// describes a potentiometer mapping
struct pot_map_t {
        pot_map_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        index = -1;
                }
        void dump(IN const char * title) const throw() {
                        DPRINTF("%s (potentiometer map):  index=%d",
                            title, index);
                }
        bool isValid(void) const throw() {
                        return (index >= 0);
                }

        // data fields
        int             index;          ///< index of potentiometer
};



/// a dpad_map_t describes how to map from low-level SourceDevice events (buttons
///     or potentiometers) into dpad events.  
struct dpad_map_t {
        // constants
        enum eType {
                eType_Button    = 1,    ///< dpad uses buttons for events
                eType_2Pot      = 2,    ///< dpad uses 2 potentiometers
                eType_4Pot      = 3,    ///< dpad uses 4 potentiometers
                eType_Invalid   = 0
        };
        enum eIndex {
                eLeft   = 0,
                eUp     = 1,
                eRight  = 2,    // left and right will be same for 2 pot
                eDown   = 3,    // up and down will be same for 2 pot

                // keep this last
                eBad    = 255
        };

        // constructor, destructor
        dpad_map_t(void) throw() { this->clear(); }

        // manipulators
        void clear(void) throw() {
                        type = eType_Invalid;
                        for (int i = 0;  i < 4; ++i) {
                                index[i] = eBad;
                        }
                        flipX = flipY = false;
                }
        void dump(IN const char * title) const throw() {
                        const char * typeName = "INVALID";
                        if (eType_Button == type) {
                                typeName = "Button";
                        } else if (eType_2Pot == type) {
                                typeName = "Two Potentiometer";
                        } else if (eType_4Pot == type) {
                                typeName = "Four Potentiometer";
                        }
                        DPRINTF("%s (directional pad mapping): %s",
                            title, typeName);
                        DPRINTF("  indices: up=%d  down=%d  left=%d  right=%d",
                            index[eUp], index[eDown],
                            index[eLeft], index[eRight]);
                        DPRINTF("  flip axis:  X=%s  Y=%s",
                            (flipX) ? "yes" : "no", (flipY) ? "yes" : "no");
                }
        bool isValid(void) const throw() {
                        if (eType_Button != type &&
                            eType_2Pot != type &&
                            eType_4Pot != type)
                                return false;   // not a valid type!
                        for (int i = 0; i < 4; ++i) {
                                if (eBad == index[i])
                                        return false;   // not a valid index
                        }
                        return true;
                }

        // data fields
        eType           type;
        byte_t          index[4]; ///< button/pot indices for 4 directions
        bool            flipX;  ///< flip x-axis value?
        bool            flipY;  ///< flip y-axis value?
};



/// A gamepad::Map is the magical binding between physical inputs (button
///     presses, joystick moves, wheel turns) and logical events (left top
///     trigger pressed, right joystick pushed up, etc.).  In practice, there is
///     no agreement between manufacturers how physical and logical events are
///     related.  So, for instance, different manufacturers will produce
///     USB adapters that represent the exact same gamepad completely
///     differently.
/// In short, based on the state of the world today, there is no way for a
///     programmer to know what type of gamepad a player is holding, or how to
///     interpret the events coming from that device.  The gamepad::Map
///     performs that mapping, and most of the purpose of this entire API is to
///     provide easy-to-create and manage gamepad mappings so that programmers
///     can work with gamepad objects and not worry about the underlying
///     details.
/// This particular object gamepad::Map is fairly low-level and is designed
///     to be easily persisted.  Users of the gamepad library will probably want
///     to use the Gamepad object instead, which is intended to represent the
///     physical instance of a connected gamepad.
class Map {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Map(void) throw();

        // gamepad::Map class interface methods --------------------------------

        /// returns the ID of this mapping.  IDs should be UUIDs
        virtual const char * getId(void) const throw() = 0;

        /// returns the ID of the gamepad type this mapping is for (also UUID)
        virtual const char * getTypeId(void) const throw() = 0;

        /// returns the name of this mapping.  This is for debugging and is not
        ///     meant for end users.
        virtual const char * getName(void) const throw() = 0;

        /// returns the list of device names for which this mapping is
        ///     recommended.  A device name is the same as what is returned
        ///     from gamepad::SourceDevice::getPublicName().  That is, it should
        ///     be the device name as returned directly by the hardware itself.
        /// This list can be empty, and there could be multiple mappings that
        ///     claim to support the same device.  This is especially true for
        ///     source devices that support multiple gamepads.
        virtual const VecString& getDeviceNames(void) const throw() = 0;

        /// given a button index for the gamepad (see gamepad::Type), how is it
        ///     mapped to buttons or potentiometers?  Returns NULL on error
        ///     (usually because the logicalName isn't recognized).
        virtual const button_map_t * getButtonMapping(
                                IN const char * logicalName) const throw() = 0;

        /// given a joystick index for the gamepad, how is it mapped to
        ///     potentiometers?  Returns NULL on error.
        virtual const joystick_map_t * getJoystickMapping(
                                IN const char * logicalName) const throw() = 0;

        /// given an potentiometer index for the gamepad (see gamepad::Type),
        ///     what is the corresponding potentiometer index on the source
        ///     device?  Returns NULL on error.
        virtual const pot_map_t * getPotMapping(
                                IN const char * logicalName) const throw() = 0;

        /// given a dpad index for the gamepad (see gamepad::Type), what is the
        ///     corresponding dpad index on the source device?  Returns NULL
        ///     on error.
        virtual const dpad_map_t * getDpadMapping(
                                IN const char * logicalName) const throw() = 0;
};



/// read mapping from a datahash (often a text file)
smart_ptr<Map> readMap(IN const Datahash * hash);


/// write mapping to a datahash (you can then use Datahash utility methods to
///     write to a stream etc)
smart_ptr<Datahash> writeMap(IN const Map * map);


};      // gamepad namespace


#endif  // GAMEPAD_GAMEPAD_MAP_H__