UsbIOPwmOutput.h

[詳解]

/// @file
/// @brief USB I/O のPWM出力処理を行うクラス UsbIOPwmOutput のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_USBIOPWMOUTPUT_H
#define AMDAEMON_USBIOPWMOUTPUT_H

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

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

namespace amdaemon
{
/// @addtogroup g_usbio
/// @{

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

    /// @brief USB I/O のPWM出力処理を行うクラス。
    /// @see UsbIO, UsbIONode
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// UsbIONode クラスのメンバ関数 UsbIONode#getPwmOutput から取得すること。
    ///
    /// USB I/O のPWM(Pulse Width Modulation)出力を行う。
    ///
    /// AM Daemon が標準でサポートするPWM出力は、PWM出力専用ポートに対するものである。
    /// PWM出力と汎用出力の切替ができるポートに対する出力はユニークコマンド扱いとなるため、
    /// このクラスではなく UsbIOUniqueOutput クラスを用いて処理すること。
    class UsbIOPwmOutput
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit UsbIOPwmOutput(InnerIndexHolder);

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

        /// @brief PWM出力スロット数を取得する。
        /// @return PWM出力スロット数。
        std::size_t getSlotCount() const;

        /// @brief 出力するデューティ値配列を設定する。
        /// @param[in] duties 出力するデューティ値配列。
        /// @param[in] slotCount デューティ値配列の要素数。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        /// @return 要求状態値。更新不要ならば無効値。
        ///
        /// @exception Exception
        /// - 引数 duties に nullptr を指定した場合。
        /// - 引数 slotCount にPWM出力スロット数より大きな値を指定した場合。
        ///   PWM出力スロット数はメンバ関数 #getSlotCount で取得できる。
        ///
        /// この関数を呼び出しても即座に出力されるわけではない。
        /// 反映状況は戻り値の要求状態値で確認できる。
        ///
        /// 引数 forceUpdate が false かつ値が変化しない場合、更新不要と判断される。
        /// その場合、戻り値の要求状態値は無効値となる。
        ///
        /// この関数を同一フレーム内で複数回呼びだした場合、
        /// 最後の呼び出し時に指定した値のみが反映される。
        RequestState setDuties(
            const std::uint8_t* duties,
            std::size_t slotCount,
            bool forceUpdate = false);

        /// @brief 出力するデューティ値配列を設定する。
        /// @param[in] duties 出力するデューティ値配列。
        /// @param[in] slotCount
        ///     デューティ値配列の要素数。既定値は SIZE_MAX (std::size_t 型の最大値)。
        ///     この値と duties.size() のうち小さい方の値が実際のサイズとして利用される。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        /// @return 要求状態値。更新不要ならば無効値。
        ///
        /// @exception Exception
        /// 引数 slotCount にPWM出力スロット数より大きい値を指定し、
        /// かつ引数 duties の要素数もPWM出力スロット数より大きい場合。
        /// PWM出力スロット数はメンバ関数 #getSlotCount で取得できる。
        ///
        /// デューティ値を可変長配列型で指定するオーバロード。
        /// 挙動は
        /// setDuties(const std::uint8_t*, std::size_t, bool)
        /// オーバロードに準ずる。
        RequestState setDuties(
            const std::vector<std::uint8_t>& duties,
            std::size_t slotCount = SIZE_MAX,
            bool forceUpdate = false)
        {
            return
                this->setDuties(
                    duties.data(),
                    std::min(slotCount, duties.size()),
                    forceUpdate);
        }

        /// @brief 出力するデューティ値配列を設定する。
        /// @tparam Count デューティ値配列の要素数。
        /// @param[in] duties 出力するデューティ値配列。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        /// @return 要求状態値。更新不要ならば無効値。
        ///
        /// @exception Exception
        /// 引数 duties の要素数がPWM出力スロット数より大きい場合。
        /// PWM出力スロット数はメンバ関数 #getSlotCount で取得できる。
        ///
        /// デューティ値を固定長配列型で指定するオーバロード。
        /// 挙動は
        /// setDuties(const std::uint8_t*, std::size_t, bool)
        /// オーバロードに準ずる。
        template<std::size_t Count>
        RequestState setDuties(const std::uint8_t (&duties)[Count], bool forceUpdate = false)
        {
            return this->setDuties(duties, Count, forceUpdate);
        }

        /// @brief 全デューティ値を 0 に設定する。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        /// @return 要求状態値。更新不要ならば無効値。
        ///
        /// メンバ関数 #setDuties に全要素が 0 のデューティ値配列を渡すことと同義。
        RequestState resetDuties(bool forceUpdate = false);

        /// @brief 出力するデューティ値を設定する。
        /// @param[in] slotIndex スロットインデックス。
        /// @param[in] duty デューティ値。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        /// @return 要求状態値。更新不要ならば無効値。
        ///
        /// @exception Exception
        /// 引数 slotIndex にPWM出力スロット数以上の値を指定した場合。
        /// PWM出力スロット数はメンバ関数 #getSlotCount で取得できる。
        ///
        /// この関数を呼び出しても即座に出力されるわけではない。
        /// 反映状況は戻り値の要求状態値で確認できる。
        ///
        /// 引数 forceUpdate が false かつ値が変化しない場合、更新不要と判断される。
        /// その場合、戻り値の要求状態値は無効値となる。
        ///
        /// この関数を同一フレーム内で同一スロットインデックスに対して複数回呼びだした場合、
        /// 最後の呼び出し時に指定した値のみが反映される。
        /// 異なるスロットインデックスに対して呼びだした場合はマージされる。
        RequestState setDuty(
            std::size_t slotIndex,
            std::uint8_t duty,
            bool forceUpdate = false);

        /// @brief 現在設定されているデューティ値配列を取得する。
        /// @return 現在設定されているデューティ値配列。
        ///
        /// 現在ライブラリ内で保持しているデューティ値配列を返す。
        /// 起動直後などは、実デバイスにこの値が設定されているとは限らない。
        const std::uint8_t* getCurrentDuties() const;

        /// @brief 現在設定されているデューティ値を取得する。
        /// @param[in] slotIndex スロットインデックス。
        /// @return 現在設定されているデューティ値。
        ///
        /// @exception Exception
        /// 引数 slotIndex にPWM出力スロット数以上の値を指定した場合。
        /// PWM出力スロット数はメンバ関数 #getSlotCount で取得できる。
        ///
        /// 現在ライブラリ内で保持しているデューティ値を返す。
        /// 起動直後などは、実デバイスにこの値が設定されているとは限らない。
        std::uint8_t getCurrentDuty(std::size_t slotIndex) const;

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

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_USBIOPWMOUTPUT_H