diff options
Diffstat (limited to 'xbmc/input/joysticks/interfaces/IButtonMap.h')
| -rw-r--r-- | xbmc/input/joysticks/interfaces/IButtonMap.h | 343 |
1 files changed, 343 insertions, 0 deletions
diff --git a/xbmc/input/joysticks/interfaces/IButtonMap.h b/xbmc/input/joysticks/interfaces/IButtonMap.h new file mode 100644 index 0000000..0b4b7d5 --- /dev/null +++ b/xbmc/input/joysticks/interfaces/IButtonMap.h @@ -0,0 +1,343 @@ +/* + * Copyright (C) 2014-2018 Team Kodi + * This file is part of Kodi - https://kodi.tv + * + * SPDX-License-Identifier: GPL-2.0-or-later + * See LICENSES/README.md for more information. + */ + +#pragma once + +#include "input/joysticks/DriverPrimitive.h" +#include "input/joysticks/JoystickTypes.h" + +#include <string> +#include <vector> + +namespace KODI +{ +namespace JOYSTICK +{ +/*! + * \ingroup joystick + * \brief Button map interface to translate between the driver's raw + * button/hat/axis elements and physical joystick features. + * + * \sa IButtonMapper + */ +class IButtonMap +{ +public: + virtual ~IButtonMap() = default; + + /*! + * \brief The add-on ID of the game controller associated with this button map + * + * The controller ID provided by the implementation serves as the context + * for the feature names below. + * + * \return The ID of this button map's game controller add-on + */ + virtual std::string ControllerID(void) const = 0; + + /*! + * \brief The Location of the peripheral associated with this button map + * + * \return The peripheral's location + */ + virtual std::string Location(void) const = 0; + + /*! + * \brief Load the button map into memory + * + * \return True if button map is ready to start translating buttons, false otherwise + */ + virtual bool Load(void) = 0; + + /*! + * \brief Reset the button map to its defaults, or clear button map if no defaults + */ + virtual void Reset(void) = 0; + + /*! + * \brief Check if the button map is empty + * + * \return True if the button map is empty, false if it has features + */ + virtual bool IsEmpty(void) const = 0; + + /*! + * \brief Get the ID of the controller profile that best represents the + * appearance of the peripheral + * + * \return The controller ID, or empty if the appearance is unknown + */ + virtual std::string GetAppearance() const = 0; + + /*! + * \brief Set the ID of the controller that best represents the appearance + * of the peripheral + * + * \param controllerId The controller ID, or empty to unset the appearance + * + * \return True if the appearance was set, false on error + */ + virtual bool SetAppearance(const std::string& controllerId) const = 0; + + /*! + * \brief Get the feature associated with a driver primitive + * + * Multiple primitives can be mapped to the same feature. For example, + * analog sticks use one primitive for each direction. + * + * \param primitive The driver primitive + * \param feature The name of the resolved joystick feature, or + * invalid if false is returned + * + * \return True if the driver primitive is associated with a feature, false otherwise + */ + virtual bool GetFeature(const CDriverPrimitive& primitive, FeatureName& feature) = 0; + + /*! + * \brief Get the type of the feature for the given name + * + * \param feature The feature to look up + * + * \return The feature's type + */ + virtual FEATURE_TYPE GetFeatureType(const FeatureName& feature) = 0; + + /*! + * \brief Get the driver primitive for a scalar feature + * + * When a feature can be represented by a single driver primitive, it is + * called a scalar feature. + * + * - This includes buttons and triggers, because they can be mapped to a + * single button/hat/semiaxis + * + * - This does not include analog sticks, because they require two axes + * and four driver primitives (one for each semiaxis) + * + * \param feature Must be a scalar feature (a feature that only + * requires a single driver primitive) + * \param primitive The resolved driver primitive + * + * \return True if the feature resolved to a driver primitive, false if the + * feature didn't resolve or isn't a scalar feature + */ + virtual bool GetScalar(const FeatureName& feature, CDriverPrimitive& primitive) = 0; + + /*! + * \brief Add or update a scalar feature + * + * \param feature Must be a scalar feature + * \param primitive The feature's driver primitive + * + * \return True if the feature was updated, false if the feature is + * unchanged or failure occurs + */ + virtual void AddScalar(const FeatureName& feature, const CDriverPrimitive& primitive) = 0; + + /*! + * \brief Get an analog stick direction from the button map + * + * \param feature Must be an analog stick or this will return false + * \param direction The direction whose primitive is to be retrieved + * \param[out] primitive The primitive mapped to the specified direction + * + * \return True if the feature and direction resolved to a driver primitive + */ + virtual bool GetAnalogStick(const FeatureName& feature, + ANALOG_STICK_DIRECTION direction, + CDriverPrimitive& primitive) = 0; + + /*! + * \brief Add or update an analog stick direction + * + * \param feature Must be an analog stick or this will return false + * \param direction The direction being mapped + * \param primitive The driver primitive for the specified analog stick and direction + * + * \return True if the analog stick was updated, false otherwise + */ + virtual void AddAnalogStick(const FeatureName& feature, + ANALOG_STICK_DIRECTION direction, + const CDriverPrimitive& primitive) = 0; + + /*! + * \brief Get a relative pointer direction from the button map + * + * \param feature Must be a relative pointer stick or this will return false + * \param direction The direction whose primitive is to be retrieved + * \param[out] primitive The primitive mapped to the specified direction + * + * \return True if the feature and direction resolved to a driver primitive + */ + virtual bool GetRelativePointer(const FeatureName& feature, + RELATIVE_POINTER_DIRECTION direction, + CDriverPrimitive& primitive) = 0; + + /*! + * \brief Add or update a relative pointer direction + * + * \param feature Must be a relative pointer or this will return false + * \param direction The direction being mapped + * \param primitive The driver primitive for the specified analog stick and direction + * + * \return True if the analog stick was updated, false otherwise + */ + virtual void AddRelativePointer(const FeatureName& feature, + RELATIVE_POINTER_DIRECTION direction, + const CDriverPrimitive& primitive) = 0; + + /*! + * \brief Get an accelerometer from the button map + * + * \param feature Must be an accelerometer or this will return false + * \param positiveX The semiaxis mapped to the positive X direction (possibly unknown) + * \param positiveY The semiaxis mapped to the positive Y direction (possibly unknown) + * \param positiveZ The semiaxis mapped to the positive Z direction (possibly unknown) + * + * \return True if the feature resolved to an accelerometer with at least 1 known axis + */ + virtual bool GetAccelerometer(const FeatureName& feature, + CDriverPrimitive& positiveX, + CDriverPrimitive& positiveY, + CDriverPrimitive& positiveZ) = 0; + + /*! + * \brief Get or update an accelerometer + * + * \param feature Must be an accelerometer or this will return false + * \param positiveX The semiaxis corresponding to the positive X direction + * \param positiveY The semiaxis corresponding to the positive Y direction + * \param positiveZ The semiaxis corresponding to the positive Z direction + * + * The driver primitives must be mapped to a semiaxis or this function will fail. + * + * \return True if the accelerometer was updated, false if unchanged or failure occurred + */ + virtual void AddAccelerometer(const FeatureName& feature, + const CDriverPrimitive& positiveX, + const CDriverPrimitive& positiveY, + const CDriverPrimitive& positiveZ) = 0; + + /*! + * \brief Get a wheel direction from the button map + * + * \param feature Must be a wheel or this will return false + * \param direction The direction whose primitive is to be retrieved + * \param[out] primitive The primitive mapped to the specified direction + * + * \return True if the feature and direction resolved to a driver primitive + */ + virtual bool GetWheel(const FeatureName& feature, + WHEEL_DIRECTION direction, + CDriverPrimitive& primitive) = 0; + + /*! + * \brief Add or update a wheel direction + * + * \param feature Must be a wheel or this will return false + * \param direction The direction being mapped + * \param primitive The driver primitive for the specified analog stick and direction + * + * \return True if the analog stick was updated, false otherwise + */ + virtual void AddWheel(const FeatureName& feature, + WHEEL_DIRECTION direction, + const CDriverPrimitive& primitive) = 0; + + /*! + * \brief Get a throttle direction from the button map + * + * \param feature Must be a throttle or this will return false + * \param direction The direction whose primitive is to be retrieved + * \param[out] primitive The primitive mapped to the specified direction + * + * \return True if the feature and direction resolved to a driver primitive + */ + virtual bool GetThrottle(const FeatureName& feature, + THROTTLE_DIRECTION direction, + CDriverPrimitive& primitive) = 0; + + /*! + * \brief Add or update a throttle direction + * + * \param feature Must be a throttle or this will return false + * \param direction The direction being mapped + * \param primitive The driver primitive for the specified analog stick and direction + * + * \return True if the analog stick was updated, false otherwise + */ + virtual void AddThrottle(const FeatureName& feature, + THROTTLE_DIRECTION direction, + const CDriverPrimitive& primitive) = 0; + + /*! + * \brief Get the driver primitive for a keyboard key + * + * \param feature Must be a key + * \param primitive The resolved driver primitive + * + * \return True if the feature resolved to a driver primitive, false if the + * feature didn't resolve or isn't a scalar feature + */ + virtual bool GetKey(const FeatureName& feature, CDriverPrimitive& primitive) = 0; + + /*! + * \brief Add or update a key + * + * \param feature Must be a key + * \param primitive The feature's driver primitive + * + * \return True if the feature was updated, false if the feature is + * unchanged or failure occurs + */ + virtual void AddKey(const FeatureName& feature, const CDriverPrimitive& primitive) = 0; + + /*! + * \brief Set a list of driver primitives to be ignored + * + * This is necessary to prevent features from interfering with the button + * mapping process. This includes accelerometers, as well as PS4 triggers + * which send both a button press and an analog value. + * + * \param primitives The driver primitives to be ignored + */ + virtual void SetIgnoredPrimitives(const std::vector<CDriverPrimitive>& primitives) = 0; + + /*! + * \brief Check if a primitive is in the list of primitives to be ignored + * + * \param primitive The primitive to check + * + * \return True if the primitive should be ignored in the mapping process + */ + virtual bool IsIgnored(const CDriverPrimitive& primitive) = 0; + + /*! + * \brief Get the properties of an axis + * + * \param axisIndex The index of the axis to check + * \param center[out] The center, if known + * \param range[out] The range, if known + * + * \return True if the properties are known, false otherwise + */ + virtual bool GetAxisProperties(unsigned int axisIndex, int& center, unsigned int& range) = 0; + + /*! + * \brief Save the button map + */ + virtual void SaveButtonMap() = 0; + + /*! + * \brief Revert changes to the button map since the last time it was loaded + * or committed to disk + */ + virtual void RevertButtonMap() = 0; +}; +} // namespace JOYSTICK +} // namespace KODI |