gamepad-config.h

Go to the documentation of this file.

/*
 * gamepad-config.h
 *
 * Copyright (C) 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.
 *
 *
 * Object to help with manual configuration of gamepads
 */

#ifndef GAMEPAD_OPENGL_GAMEPAD_CONFIG_H__
#define GAMEPAD_OPENGL_GAMEPAD_CONFIG_H__

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


namespace gamepad {


/// \ingroup gamepad_api
/// \defgroup gamepad_config Gamepad Configuration
///
/*@{*/


/// instruction set for user
enum eInstruction {
        // instructions
        eInstruction_Calibrate          = 0x401,///< press and move all controls

        eInstruction_ButtonPress        = 0x111,///< press the specified button

        // Dpad instructions: typically you'll need to do this (center or move
        //      dpad) and then press the gamepad's primay action button
        eInstruction_DpadCenter         = 0x310,///< center dpad
        eInstruction_DpadLeft           = 0x311,///< move dpad to left and 
        eInstruction_DpadRight          = 0x312,///< move specified dpad up
        eInstruction_DpadUp             = 0x313,///< move specified dpad up
        eInstruction_DpadDown           = 0x314,///< move specified dpad up

        // Joystick instructions: typically you'll need to do this (center or
        //      move joystick) and then press the gamepad's primary action
        //      button.
        eInstruction_JoyCenter          = 0x320,///< center joystick
        eInstruction_JoyLeft            = 0x321,///< push joystick left
        eInstruction_JoyUp              = 0x322,///< push joystick up

        // Potentiometer instructions: you'll do this and press the gamepad's
        //      primary action button.
        eInstruction_PotCenter          = 0x330,///< pot is centered/zero'd
        eInstruction_PotExtreme         = 0x331,///< now move pot to extreme

        // these are NOT instructions!  These are bit flags
        eInstruction_RequestControl     = 0x100,///< specific to one control
        eInstruction_PressMainAction    = 0x200,///< main action button press
        eInstruction_ExternalEvent      = 0x400,///< requires non-gamepad event

        // keep this last!
        eInstruction_Invalid            = 0
};



/// specifies the current status of gamepad configuration
struct config_status_t {
        // constructor, manipulators
        config_status_t(void) throw() { this->clear(); }
        void clear(void) throw() {
                        currStep = -1;
                        maxSteps = 0;
                        instruct = eInstruction_Invalid;
                        primary = NULL;
                        logical = NULL;
                }

        // data fields
        int             currStep;       ///< current step of config (first is 0)
        int             maxSteps;       ///< total number of configuration steps
        eInstruction    instruct;       ///< what user should do
        const char *    primary;        ///< logical name of primary button
        const char *    logical;        ///< logical input being configured
};



class Configurator {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Configurator(void) throw();

        // gamepad::Configurator class interface methods -----------------------

        /// call this to reset configuration state and go back to calibration
        virtual void reset(void) = 0;

        /// call this frequently (multiple times per second).  Returns false
        ///     when the configurator is done.
        virtual bool update(OUT config_status_t& status) = 0;

        /// if the current instruction is eInstruction_Calibrate, you can only
        ///     move to the next step by calling this method.  This should be
        ///     called once all controls have been moved/pressed, and all
        ///     controls are currently released (no buttons pressed, joysticks
        ///     pushed off center, etc.).  So the Configurator knows it is now
        ///     safe to take a snapshot of gamepad state.
        virtual void calibrationComplete(void) = 0;

        /// once done, call this to get the mapping
        virtual smart_ptr<Map> getMapping(void) = 0;

        // static factory methods ----------------------------------------------

        /// walk through and configure a mapping to the specified gamepad
        ///     type, from the specified device.  Caller also supplies a
        ///     friendly name for the mapping.
        static smart_ptr<Configurator> create(IN smart_ptr<Manager>& mgr,
                                IN smart_ptr<SourceDevice>& device,
                                IN smart_ptr<Type>& type,
                                IN const char * name);
};



/// handy string token given enum (can be used as key for localized string)
const char * getInstructionToken(IN eInstruction instruct);


};      // gamepad namespace


#endif  // GAMEPAD_OPENGL_GAMEPAD_CONFIG_H__