BoardIO.h

[詳解]

/// @file
/// @brief DipSwitch、PushSwitch、LEDの情報を提供するMonostateクラス BoardIO のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_BOARDIO_H
#define AMDAEMON_BOARDIO_H

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

#include <cstdint>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_boardio
/// @{

    /// @brief DipSwitch、PushSwitch、LEDの情報を提供するMonostateクラス。
    /// @see Input, Output
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    ///
    /// DipSwitchやPushSwitchの生入力値を取得したり、LEDを直接操作したい場合に用いる。
    /// ID付けされた入出力処理を行う場合はこのクラスではなく
    /// Input クラスや Output クラスを用いること。
    ///
    /// Output クラスとはLED出力値を共有しており、
    /// どちらか一方で設定した出力値はもう一方にも反映される。
    ///
    /// @par ライブラリ利用アプリで実装すべきこと(Nuシリーズタイトルのみ)
    /// - @ref #isPushSwitchOn "isPushSwitchOn(0)" が true を返した場合、
    ///   Sequence クラスのメンバ関数 Sequence#beginTest を呼び出し、
    ///   ゲームテストモードへ遷移すること。
    ///     - BoardIO クラス単体では「ちょうど押した時」の判定ができない。
    ///       また、I/Oボードが接続されている場合、
    ///       そのTESTスイッチがON状態になった場合にも同様の処理を行う必要がある。
    ///       これらを解決・一元化するために、 Input クラスの利用を推奨する。
    ///
    /// @par プラットフォーム情報
    /// - ALLSシリーズにはPushSwitch、LEDが搭載されておらず、下記のように扱われる。
    ///     - すべてのPushSwitchは常にOFF状態として扱われる。
    ///     - すべてのLEDは常に消灯状態として扱われ、状態設定は必ず失敗する。
    /// - ALLSシリーズにおけるDipSwitchは、
    ///   システムテストモードで設定できる汎用フラグ値のビット列を表す。
    ///
    /// @ingroup g_common
    class BoardIO
    {
        // 下記は暗黙の定義を用いる。
        //BoardIO() = default;
        //‾BoardIO() = default;
        //BoardIO(const BoardIO&) = default;
        //BoardIO& operator=(const BoardIO&) = default;

    public:
        // DipSwitch

        /// @brief DipSwitchのON/OFF状態ビット列を取得する。
        /// @return DipSwitchのON/OFF状態ビット列。
        ///
        /// ON状態の場合、対応するビットは 1 になる。
        /// OFF状態の場合、対応するビットは 0 となる。
        /// 各ビットはDipSwitchのインデックスに対応している。
        ///
        /// iostream との親和性のために戻り値の型を std::uint16_t としているが、
        /// 実際に値が入るのは下位 amdaemon::DipSwitchCount ビットまでとなる。
        ///
        /// ビット演算を行いたくない場合、メンバ関数 #isDipSwitchOn で各DipSwitchの
        /// 状態を個別に取得するか、 std::bitset クラスで戻り値をラップするとよい。
        ///
        /// @code
        /// amdaemon::System system;
        /// 
        /// // メンバ関数 getDipSwitchBits の戻り値を bitset に変換
        /// std::bitset<amdaemon::DipSwitchCount> bits(system.getDipSwitchBits());
        /// @endcode
        ///
        /// @par プラットフォーム情報
        /// - Nuシリーズの場合、この値はDaemonプロセスの起動時に取得され、
        ///   以降DipSwitchを操作しても変化しない。
        ///     - 変更したDipSwitch状態を反映するためにはDaemonプロセスを再起動する必要がある。
        /// - ALLSシリーズの場合、
        ///   この値はシステムテストモードで設定できる汎用フラグ値のビット列を表す。
        std::uint16_t getDipSwitchBits() const;

        /// @brief DipSwitchのアプリ定義値を取得する。
        /// @return DipSwitchのアプリ定義値。
        ///
        /// @par プラットフォーム情報
        /// - Nuシリーズの場合、インデックス 0, 1, 2 のDipSwitch状態により表される値を返す。
        /// - ALLSシリーズの場合、メンバ関数 #getDipSwitchBits と同じ値を返す。
        std::uint16_t getDipSwitchAppValue() const;

        /// @brief DipSwitchのON/OFF状態を取得する。
        /// @param[in] index DipSwitchインデックス。
        /// @retval true  ON状態である場合。
        /// @retval false OFF状態である場合。
        ///
        /// @exception Exception
        /// 引数 index に amdaemon::DipSwitchCount 以上の値を指定した場合。
        bool isDipSwitchOn(std::size_t index) const;

        /// @brief DipSwitchのON/OFF状態を取得する。
        /// @param[in] pos DipSwitch位置。
        /// @retval true  ON状態である場合。
        /// @retval false OFF状態である場合。
        ///
        /// @exception Exception
        /// 引数 pos に不正な値を指定した場合。
        bool isDipSwitchOn(DipSwitchPos pos) const
        {
            return isDipSwitchOn(static_cast<std::size_t>(pos));
        }

    public:
        // PushSwitch

        /// @brief PushSwitchのON/OFF状態ビット列を取得する。
        /// @return PushSwitchのON/OFF状態ビット列。
        ///
        /// ON状態の場合、対応するビットは 1 になる。
        /// それ以外の場合、対応するビットは 0 となる。
        /// 各ビットはPushSwitchのインデックスに対応している。
        ///
        /// iostream との親和性のために戻り値の型を std::uint16_t としているが、
        /// 実際に値が入るのは下位 amdaemon::PushSwitchCount ビットまでとなる。
        ///
        /// ビット演算を行いたくない場合、メンバ関数 #isPushSwitchOn で各PushSwitchの
        /// 状態を個別に取得するか、 std::bitset クラスで戻り値をラップするとよい。
        std::uint16_t getPushSwitchBits() const;

        /// @brief PushSwitchのON/OFF状態を取得する。
        /// @param[in] index PushSwitchインデックス。
        /// @retval true  ON状態である場合。
        /// @retval false OFF状態である場合。
        ///
        /// @exception Exception
        /// 引数 index に amdaemon::PushSwitchCount 以上の値を指定した場合。
        bool isPushSwitchOn(std::size_t index) const;

    public:
        // LED

        /// @brief LEDの状態を設定する。
        /// @param[in] index LEDインデックス。
        /// @param[in] on 点灯状態にするならば true 、消灯状態にするならば false 。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        ///
        /// @exception Exception
        /// 引数 index に amdaemon::BoardLedCount 以上の値を指定した場合。
        ///
        /// この関数で指定しても即座に更新されるわけではなく、
        /// Core クラスのメンバ関数 Core#execute 呼び出しによって更新される。
        void setLedState(std::size_t index, bool on, bool forceUpdate = false);

        /// @brief 現在設定されているLED状態ビット列を取得する。
        /// @return 現在設定されているLED状態ビット列。
        ///
        /// 現在ライブラリ内で保持しているLED状態を返す。
        /// 起動直後などは、実際のLEDがこの状態になっているとは限らない。
        ///
        /// 点灯状態の場合、対応するビットは 1 になる。
        /// 消灯状態の場合、対応するビットは 0 となる。
        /// 各ビットはLEDのインデックスに対応している。
        ///
        /// iostream との親和性のために戻り値の型を std::uint16_t としているが、
        /// 実際に値が入るのは下位 amdaemon::BoardLedCount ビットまでとなる。
        ///
        /// ビット演算を行いたくない場合、メンバ関数 #isCurrentLedStateOn で各LED状態を
        /// 個別に取得するか、 std::bitset クラスで戻り値をラップするとよい。
        std::uint16_t getCurrentLedStateBits() const;

        /// @brief 現在設定されているLED状態が点灯状態であるか否かを取得する。
        /// @param[in] index LEDインデックス。
        /// @retval true  点灯状態である場合。
        /// @retval false 消灯状態である場合。
        ///
        /// @exception Exception
        /// 引数 index に amdaemon::BoardLedCount 以上の値を指定した場合。
        ///
        /// 現在ライブラリ内で保持しているLED状態を返す。
        /// 起動直後などは、実際のLEDがこの状態になっているとは限らない。
        bool isCurrentLedStateOn(std::size_t index) const;
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_BOARDIO_H