JvsSwitchInput.h

[詳解]

/// @file
/// @brief JVSスイッチ入力情報を提供するクラス JvsSwitchInput のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_JVSSWITCHINPUT_H
#define AMDAEMON_JVSSWITCHINPUT_H

#include "amdaemon/env.h"
#include "amdaemon/util/container.h"

#include <vector>
#include <cstdint>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_jvs
/// @{

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

    /// @brief JVSスイッチ入力情報を提供するクラス。
    /// @see Jvs, JvsNode
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// JvsNode クラスのメンバ関数 JvsNode#getSwitchInput から取得すること。
    class JvsSwitchInput
    {
    public:
        /// システムスイッチ入力の最大数。
        static const std::size_t MaxSystemBitCount = 8;

        /// プレイヤー単位スイッチ入力の最大数。
        static const std::size_t MaxPlayerBitCount = 64;

    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit JvsSwitchInput(InnerIndexHolder);

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

        /// @brief システムスイッチの入力状態ビット列を取得する。
        /// @return システムスイッチの入力状態ビット列。
        ///
        /// スイッチ入力がON状態の場合、対応するビットは 1 になる。
        /// それ以外の場合、対応するビットは 0 となる。
        /// 各ビットがどのボタンに対応しているかはデバイス依存である。
        ///
        /// iostream との親和性のために戻り値の型を std::uint16_t としているが、
        /// 実際に値が入るのは最大でも下位 #MaxSystemBitCount ビットまでとなる。
        ///
        /// ビット演算を行いたくない場合、メンバ関数 #isSystemOn で各ビットの
        /// 状態を個別に取得するか、 std::bitset クラスで戻り値をラップするとよい。
        ///
        /// @code
        /// amdaemon::Jvs jvs;
        /// 
        /// // メンバ関数 getSystemBits の戻り値を bitset に変換
        /// // std::bitset<sizeof(std::uint16_t) * 8> 型の値が返る
        /// auto bits =
        ///     amdaemon::util::toBitset(
        ///         jvs.getNode(0).getSwitchInput().getSystemBits());
        /// @endcode
        std::uint16_t getSystemBits() const;

        /// @brief システムスイッチの入力状態を取得する。
        /// @param[in] bitIndex ビットインデックス。
        /// @retval true  スイッチ入力がON状態である場合。
        /// @retval false スイッチ入力がOFF状態である場合。
        ///
        /// @exception Exception
        /// 引数 bitIndex に #MaxSystemBitCount 以上の値を指定した場合。
        bool isSystemOn(std::size_t bitIndex) const;

        /// @brief プレイヤー数を取得する。
        /// @return プレイヤー数。
        ///
        /// このプレイヤー数はJVS規格のスイッチ入力におけるプレイヤー数であり、
        /// Core#getPlayerCount で取得できるプレイヤー数とは異なる。
        std::size_t getPlayerCount() const;

        /// @brief プレイヤー単位スイッチの入力状態ビット列を取得する。
        /// @param[in] playerIndex プレイヤーインデックス。
        /// @return プレイヤー単位スイッチの入力状態ビット列。
        ///
        /// @exception Exception
        /// 引数 playerIndex にプレイヤー数以上の値を指定した場合。
        /// プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
        ///
        /// スイッチ入力がON状態の場合、対応するビットは 1 になる。
        /// それ以外の場合、対応するビットは 0 となる。
        /// 各ビットがどのボタンに対応しているかはデバイス依存である。
        ///
        /// ビット演算を行いたくない場合、メンバ関数 #isPlayerOn で各ビットの
        /// 状態を個別に取得するか、 std::bitset クラスで戻り値をラップするとよい。
        ///
        /// @code
        /// amdaemon::Jvs jvs;
        /// 
        /// // メンバ関数 getPlayerBits の戻り値を bitset に変換
        /// // std::bitset<sizeof(std::uint64_t) * 8> 型の値が返る
        /// auto bits =
        ///     amdaemon::util::toBitset(
        ///         jvs.getNode(0).getSwitchInput().getPlayerBits(0));
        /// @endcode
        std::uint64_t getPlayerBits(std::size_t playerIndex) const;

        /// @brief プレイヤー単位スイッチの入力状態を取得する。
        /// @param[in] playerIndex プレイヤーインデックス。
        /// @param[in] bitIndex ビットインデックス。
        /// @retval true  スイッチ入力がON状態である場合。
        /// @retval false スイッチ入力がOFF状態である場合。
        ///
        /// @exception Exception
        /// - 引数 playerIndex にプレイヤー数以上の値を指定した。
        ///   プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
        /// - 引数 bitIndex に #MaxPlayerBitCount 以上の値を指定した。
        bool isPlayerOn(std::size_t playerIndex, std::size_t bitIndex) const;

        /// @brief プレイヤー単位スイッチの入力状態ビット列配列を取得する。
        /// @return プレイヤー単位スイッチの入力状態ビット列配列。
        ///
        /// 範囲for文や各種アルゴリズム関数に渡すことを想定している。
        ///
        /// - プレイヤー数を知りたいだけならばメンバ関数 #getPlayerCount を用いること。
        /// - 特定プレイヤーのスイッチ入力状態ビット列を取得したいだけならばメンバ関数
        ///   #getPlayerBits を用いること。
        std::vector<std::uint64_t> getPlayersBits() const
        {
            return
                ::amdaemon::util::toContainer<decltype(getPlayersBits())>(
                    getPlayerCount(),
                    [this](std::size_t i) { return getPlayerBits(i); });
        }

    private:
        std::size_t _nodeIndex; ///< ノードインデックス。

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_JVSSWITCHINPUT_H