AnalogInput.h

[詳解]

/// @file
/// @brief InputUnit クラスからアナログ入力を取得するラッパクラス AnalogInput のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_ANALOGINPUT_H
#define AMDAEMON_ANALOGINPUT_H

#include "amdaemon/env.h"
#include "amdaemon/InputId.h"

namespace amdaemon
{
/// @addtogroup g_io
/// @{

    // InputUnit クラスの前方宣言
    class InputUnit;

    /// @brief InputUnit クラスからアナログ入力を取得するラッパクラス。
    /// @see Input, InputUnit
    ///
    /// I/Oボードアナログ入力等、入力値の線形変換を行いたい入力に対して用いる。
    ///
    /// @code
    /// #include "amdaemon/Input.h"
    /// 
    /// namespace inputs
    /// {
    ///     // 定数宣言(実値は任意のソースファイルで定義する)
    ///     extern const amdaemon::InputId AnalogX;
    ///     extern const amdaemon::InputId AnalogY;
    ///     extern const amdaemon::InputId AnalogZ;
    /// }
    /// 
    /// void foo()
    /// {
    ///     amdaemon::Input input;
    /// 
    ///     // InputUnit インスタンスから取得
    ///     // 0.0 以上 1.0 以下に線形変換する
    ///     const auto x = input.getPlayer(0).getAnalog(inputs::AnalogX);
    /// 
    ///     // AnalogX のアナログ値を取得
    ///     double valueX = x.getValue();
    /// 
    ///     // InputUnit インスタンスから取得
    ///     // -100.0 以上 100.0 以下に線形変換する
    ///     const auto y = input.getPlayer(0).getAnalog(inputs::AnalogY, -100, 100);
    /// 
    ///     // AnalogY のアナログ差分値を取得
    ///     double deltaY = y.getDelta();
    /// 
    ///     // InputUnit インスタンスから直接構築
    ///     // 0.0 以上 10.0 以下に線形変換する
    ///     const amdaemon::AnalogInput z(input.getPlayer(0), inputs::AnalogZ, 10);
    /// 
    ///     // AnalogZ のアナログ値を取得
    ///     double valueZ = z.getValue();
    /// }
    /// @endcode
    class AnalogInput
    {
    public:
        /// @brief コンストラクタ。
        /// @param[in] unit InputUnit インスタンス参照。
        /// @param[in] id 入力識別ID。
        /// @param[in] minValue 最小値を線形変換した時の値。
        /// @param[in] maxValue 最大値を線形変換した時の値。
        ///
        /// @exception Exception
        /// 引数 minValue または maxValue に非数値(NAN等)を指定した場合。
        ///
        /// 引数 id に存在しない入力識別IDを指定した場合でも例外は発生しない。
        /// ただしメンバ関数 #exists は false を返す。
        ///
        /// (minValue >= maxValue) となるような値も指定可能である。
        /// その場合、元の値の単調増加に比例して単調減少するような線形変換が行われる。
        AnalogInput(
            const InputUnit& unit,
            const InputId& id,
            double minValue,
            double maxValue);

        /// @brief コンストラクタ。
        /// @param[in] unit InputUnit インスタンス参照。
        /// @param[in] id 入力識別ID。
        /// @param[in] maxValue 最大値を線形変換した時の値。既定値は 1.0 。
        ///
        /// @exception Exception
        /// 引数 maxValue に非数値(NAN等)を指定した場合。
        ///
        /// @ref #AnalogInput "AnalogInput(unit, id, 0, maxValue)" と同義。
        AnalogInput(const InputUnit& unit, const InputId& id, double maxValue = 1);

        // 下記は暗黙の定義を用いる。
        //AnalogInput(const AnalogInput&) = default;
        //‾AnalogInput() = default;
        //AnalogInput& operator=(const AnalogInput&) = default;

        /// @brief 入力が存在するか否かを取得する。
        /// @retval true  存在する場合。
        /// @retval false 存在しない場合。
        bool exists() const;

        /// @brief 線形変換された入力値を取得する。
        /// @return 線形変換された入力値。入力が存在しない場合は最小値。
        double getValue() const;

        /// @brief 線形変換された入力差分値を取得する。
        /// @return 線形変換された入力差分値。入力が存在しない場合は 0.0 。
        double getDelta() const;

        /// @brief 最小値を線形変換した時の値を取得する。
        /// @return 最小値を線形変換した時の値。
        ///
        /// メンバ関数 #getMaxValue の戻り値より大きい値になりうる。
        double getMinValue() const
        {
            return _minValue;
        }

        /// @brief 最大値を線形変換した時の値を取得する。
        /// @return 最大値を線形変換した時の値。
        ///
        /// メンバ関数 #getMinValue の戻り値より小さい値になりうる。
        double getMaxValue() const
        {
            return _maxValue;
        }

    private:
        const InputUnit* _unit; ///< InputUnit インスタンス参照。
        InputId _id;            ///< 入力識別ID。
        double _minValue;       ///< 最小値を線形変換した時の値。
        double _maxValue;       ///< 最大値を線形変換した時の値。
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_ANALOGINPUT_H