manager.h

Go to the documentation of this file.

/*
 * manager.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 manager
 */

#ifndef GAMEPAD_MANAGER_H__
#define GAMEPAD_MANAGER_H__

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

#include "nstream/nstream.h"    // named streams


namespace gamepad {


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



/// you'll want one of these to get at source devices (gamepad::SourceDevice)
///   and create gamepad objects (gamepad::Gamepad).
///
/// Here is how you use a gamepad::Manager object:
///  - iterate over all exposed SourceDevice objects
///  - once you have one (or the player selects one), pick a mapping for
///     the device.  A mapping (gamepad::Map) describes how to extract
///     logical gamepad events from the raw source device events.
///  - with a particular source device and mapping, you can create a
///     gamepad object (gamepad::Gamepad).
///
/// \b WARNING: this class is not threadsafe.  You'll need to synchronize
///     access at a higher layer if necessary.
class Manager {
public:
        // public enums --------------------------------------------------------
        enum eResult {
                eResult_Success         = 0,    ///< success!
                eResult_SourceInUse     = 1,    ///< source device already bound
                eResult_BadSource       = 2,    ///< source device is gone/bad
                eResult_BadMap          = 3,    ///< specified map won't work

                // keep this last!
                eResult_Invalid         = -1
        };

        // virtual destructor --------------------------------------------------
        virtual ~Manager(void) throw();

        // gamepad::Manager class interface methods ----------------------------

        /// retrieve the data directory used by this gamepad::Manager
        virtual nstream::Folder * getDataDirectory(void) = 0;

        /// this can be an expensive call!  This will re-poll all devices as
        ///     needed.  Returns true if anything changed (devices
        ///     added/removed)
        virtual bool rediscover(void) = 0;

        /// the number of currently discovered source devices
        virtual int getSourceDeviceCount(void) = 0;

        /// given an index (0 <= index < SourceDeviceCount), returns the
        ///     specified source device.  Will return NULL on bad index, or if
        ///      a source device no longer exists.
        virtual smart_ptr<SourceDevice> getSourceDevice(IN int index) = 0;

        /// returns source device with the specified unique ID.  Can return
        ///     null for a variety of reasons (bad ID, source device was just
        ///     unplugged, etc.)
        virtual smart_ptr<SourceDevice> getSourceDeviceById(IN const char * id) = 0;

        /// get the count of known gamepade types.  To start with, this consists
        ///     of built-in types only, but the client can add more.
        virtual int getTypeCount(void) = 0;

        /// get the specified type.  Returns NULL if the input index is invalid.
        virtual smart_ptr<Type> getType(IN int index) = 0;

        /// get the specified type (specified by its unique ID)
        virtual smart_ptr<Type> getType(IN const char * id) = 0;

        /// add a type to the set of known gamepad types.
        virtual void addType(IN smart_ptr<Type>& type) = 0;

        /// get the count of known mappings.  To start with, this consists of
        ///     built-in mappings only, but the client can add more.
        virtual int getMappingCount(void) = 0;

        /// get the specified mapping.  Returns NULL if the input index is
        ///     invalid.
        virtual smart_ptr<Map> getMapping(IN int index) = 0;

        /// get the specified mapping (specified by its unique ID)
        virtual smart_ptr<Map> getMapping(IN const char * id) = 0;

        /// add a mapping to the set of known mappings
        virtual void addMapping(IN smart_ptr<Map>& map) = 0;

        /// once you have a source device and a mapping, you can create a
        ///     logical gamepad object.
        virtual eResult createGamepad(IN smart_ptr<SourceDevice>& device,
                                IN smart_ptr<Map>& map,
                                OUT smart_ptr<Gamepad>& gamepad) = 0;

        /// get the count of known good gamepad devices
        virtual int getGamepadCount(void) = 0;

        /// get the specified gamepad device
        virtual smart_ptr<Gamepad> getGamepad(IN int index) = 0;

        /// get the specified gamepad by its ID
        virtual smart_ptr<Gamepad> getGamepad(IN const char * id) = 0;

        /// delete (un-configure) the specified gamepad.  Returns false if
        ///     the gamepad is not recognized.
        virtual bool deleteGamepad(IN const char * gamepadId) = 0;

        /// this refreshes all state for devices.  You can call this once on
        ///     the manager, and then all gamepad objects are automatically
        ///     updated for you.
        /// This routine just iterates through all known source devices and
        ///     calls poll() on them.  If you need more control over updates,
        ///     you can avoid calling this and call poll() on individual
        ///     source devices as needed.
        virtual void update(void) = 0;

        // static class methods (factory methods) ------------------------------

        /// this is the static method used to create gamepad::Manager objects.
        ///     The data directory should contain all gamepad type files, as
        ///     well as localized text files.  See the data directory in this
        ///     svn repository for an example (and reference sample).
        ///     For now only a single data directory per Manager is supported.
        static smart_ptr<Manager> create(IN smart_ptr<nstream::Folder>& dataDirectory);
};



/// helper method to return a list of recommended mappings for a given
///     source device.  Note that there could be zero to many recommended
///     mappings!
///
/// \b NOTE: this helper is very simple and inefficient.  It is intended
///     to be called very infrequently (such as when a user plugs in a new
///     device).
void getRecommendedMappings(IN Manager * manager,
                                IN SourceDevice * device,
                                OUT VecString& mapIds);


/// helper method to autoconfigure any gamepads possible based on
///     recommended mappings.
///
/// \b NOTE: if you use this, make sure you give the user a chance to
///     correct or remove any autoconfigured gamepads!  Some manufacturers
///     may change how their devices, breaking older versions of gamepad
///     libraries etc.
///
/// This is also inefficient.  Only call when new source devices are
///     discovered.
void autoconfigureGamepads(IN Manager * manager);


};      // gamepad namespace

#endif  // GAMEPAD_MANAGER_H__