OutputUnit.h

[詳解]

/// @file
/// @brief カテゴリ単位のID付けされた出力処理を行うクラス OutputUnit のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_OUTPUTUNIT_H
#define AMDAEMON_OUTPUTUNIT_H

#include "amdaemon/env.h"
#include "amdaemon/SwitchOutput.h"
#include "amdaemon/AnalogOutput.h"
#include "amdaemon/OutputId.h"

#include <cstdint>
#include <cstddef>

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

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

    // ラッパクラスの前方宣言
    class SwitchOutput;
    class AnalogOutput;

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

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

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

        /// @brief 出力値を設定する。
        /// @param[in] id 出力識別ID。
        /// @param[in] value 出力値。出力先デバイスにより値の意味は異なる。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        ///
        /// @exception Exception
        /// - 引数 id に存在しない出力識別IDを指定した場合。
        /// - 引数 value に有効範囲外の値を指定した場合。
        void setValue(const OutputId& id, std::int64_t value, bool forceUpdate = false);

        /// @brief 現在出力値として設定されている値を取得する。
        /// @param[in] id 出力識別ID。
        /// @return 現在出力値として設定されている値。
        ///
        /// @exception Exception
        /// 引数 id に存在しない出力識別IDを指定した場合。
        ///
        /// 現在ライブラリ内で保持している値を返す。
        /// 起動直後などは、実デバイスにこの値が設定されているとは限らない。
        std::int64_t getCurrentValue(const OutputId& id) const;

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

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

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

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

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

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

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_OUTPUTUNIT_H