InputUnit.h

[詳解]

/// @file
/// @brief カテゴリ単位のID付けされた入力情報を提供するクラス InputUnit のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_INPUTUNIT_H
#define AMDAEMON_INPUTUNIT_H

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

#include <cstdint>
#include <cstddef>

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

    // 内部クラスの前方宣言
    class InnerIndexHolder;

    // ラッパクラスの前方宣言
    class SwitchInput;
    class AnalogInput;

    /// @brief カテゴリ単位のID付けされた入力情報を提供するクラス。
    /// @see Input, Player
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// Input クラスのメンバ関数 Input#getSystem および Input#getPlayer から取得すること。
    ///
    /// 入力識別ID値は文字列から作成できる。
    /// アプリ実装においては、定数を定義してそれを用いることを推奨する。
    ///
    /// @code
    /// namespace inputs
    /// {
    ///     const amdaemon::InputId Up = amdaemon::InputId::make(L"up");
    /// }
    /// @endcode
    ///
    /// 有効な入力識別IDそのものはDaemonプロセスの設定ファイルで定義する。
    ///
    /// スイッチ入力は SwitchInput クラス、アナログ入力は AnalogInput クラスで
    /// それぞれラップして入力値を取得することを推奨する。
    /// メンバ関数 #getSwitch および #getAnalog で各ラッパを取得できる。
    ///
    /// @ingroup g_player
    class InputUnit
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit InputUnit(InnerIndexHolder);

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

        /// @brief 指定した識別IDの入力が存在するか否かを取得する。
        /// @param[in] id 入力識別ID。
        /// @retval true  存在する場合。
        /// @retval false 存在しない場合。
        bool exists(const InputId& id) const;

        /// @brief 入力値を取得する。
        /// @param[in] id 入力識別ID。
        /// @return 入力値。入力元デバイスにより値の意味は異なる。
        ///
        /// @exception Exception
        /// 引数 id に存在しない入力識別IDを指定した場合。
        ///
        /// - PushSwitchおよびI/Oボードスイッチ入力の場合、
        ///   ON状態ならば 1 、OFF状態ならば 0 を返す。
        /// - I/Oボードアナログ入力の場合、有効ビット数分になるよう直値を右シフトした値を返す。
        ///   値の最小値は 1 となる。
        /// - I/Oボードロータリ入力の場合、前フレームとの差分値を返す。
        ///   値の範囲は -32768 以上 +32768 以下となる。
        std::int64_t getValue(const InputId& id) const;

        /// @brief 前フレームとの入力値の差分値を取得する。
        /// @param[in] id 入力識別ID。
        /// @return 前フレームとの入力値の差分値。
        ///
        /// @exception Exception
        /// 引数 id に存在しない入力識別IDを指定した場合。
        ///
        /// 入力値がどのような意味を持っていようと関係なく一律で
        /// 前フレームの入力値と現在フレームの入力値との差分値を返す。
        std::int64_t getDelta(const InputId& id) const;

        /// @brief 入力値の取りうる最小値を取得する。
        /// @param[in] id 入力識別ID。
        /// @return 入力値の取りうる最小値。
        ///
        /// @exception Exception
        /// 引数 id に存在しない入力識別IDを指定した場合。
        std::int64_t getMinValue(const InputId& id) const;

        /// @brief 入力値の取りうる最大値を取得する。
        /// @param[in] id 入力識別ID。
        /// @return 入力値の取りうる最大値。
        ///
        /// @exception Exception
        /// 引数 id に存在しない入力識別IDを指定した場合。
        std::int64_t getMaxValue(const InputId& id) const;

        /// @brief 入力の直値を取得する。
        /// @param[in] id 入力識別ID。
        /// @return 入力の直値。入力元デバイスにより値の意味は異なる。
        ///
        /// @exception Exception
        /// 引数 id に存在しない入力識別IDを指定した場合。
        ///
        /// ゲームテストモード等で直値の表示が必要となる場合に用いる。
        /// 通常はこちらではなくメンバ関数 #getValue を用いること。
        ///
        /// - I/Oボードアナログ入力の場合、 0 以上 UINT16_MAX 以下の直値を返す。
        /// - I/Oボードロータリ入力の場合、 0 以上 UINT16_MAX 以下の直値を返す。
        /// - 上記以外の入力の場合、メンバ関数 #getValue と同じ値を返す。
        std::int64_t getDirectValue(const InputId& id) const;

        /// @brief スイッチ入力ラッパを取得する。
        /// @param[in] id 入力識別ID。
        /// @return スイッチ入力ラッパ。
        ///
        /// 引数 id に存在しない入力識別IDを指定した場合でもラッパを取得できる。
        /// ただしラッパのメンバ関数 SwitchInput#exists は false を返す。
        inline SwitchInput getSwitch(const InputId& id) const;

        /// @brief アナログ入力ラッパを取得する。
        /// @param[in] id 入力識別ID。
        /// @param[in] minValue 最小値を線形変換した時の値。
        /// @param[in] maxValue 最大値を線形変換した時の値。
        /// @return アナログ入力ラッパ。
        ///
        /// @exception Exception
        /// 引数 minValue または maxValue に非数値(NAN等)を指定した場合。
        ///
        /// 引数 id に存在しない入力識別IDを指定した場合でもラッパを取得できる。
        /// ただしラッパのメンバ関数 AnalogInput#exists は false を返す。
        inline AnalogInput getAnalog(
            const InputId& id,
            double minValue,
            double maxValue) const;

        /// @brief アナログ入力ラッパを取得する。
        /// @param[in] id 入力識別ID。
        /// @param[in] maxValue 最大値を線形変換した時の値。既定値は 1.0 。
        /// @return アナログ入力ラッパ。
        ///
        /// @exception Exception
        /// 引数 maxValue に非数値(NAN等)を指定した場合。
        ///
        /// 最小値を線形変換した時の値は 0.0 となる。
        ///
        /// 引数 id に存在しない入力識別IDを指定した場合でもラッパを取得できる。
        /// ただしラッパのメンバ関数 AnalogInput#exists は false を返す。
        inline AnalogInput getAnalog(const InputId& id, double maxValue = 1) const;

    private:
        std::size_t _playerIndex;   ///< プレイヤーインデックス。

    private:
        // コピー禁止
        InputUnit(const InputUnit&);            // 宣言のみ
        InputUnit& operator=(const InputUnit&); // 宣言のみ
    };

/// @}
} // namespace amdaemon

// 互いに参照しているためこの位置に記述する必要がある
#include "amdaemon/SwitchInput.h"
#include "amdaemon/AnalogInput.h"

namespace amdaemon
{
    // スイッチ入力ラッパを取得する。
    inline SwitchInput InputUnit::getSwitch(const InputId& id) const
    {
        return SwitchInput(*this, id);
    }

    // アナログ入力ラッパを取得する。
    inline AnalogInput InputUnit::getAnalog(
        const InputId& id,
        double minValue,
        double maxValue) const
    {
        return AnalogInput(*this, id, minValue, maxValue);
    }

    // アナログ入力ラッパを取得する。
    inline AnalogInput InputUnit::getAnalog(const InputId& id, double maxValue) const
    {
        return AnalogInput(*this, id, maxValue);
    }
} // namespace amdaemon

#endif // AMDAEMON_INPUTUNIT_H