Credit.h

[詳解]

/// @file
/// @brief ビデオゲームのクレジット処理を提供するMonostateクラス Credit のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_CREDIT_H
#define AMDAEMON_CREDIT_H

#include "amdaemon/env.h"
#include "amdaemon/CreditUnit.h"
#include "amdaemon/CreditSpecialDevice.h"
#include "amdaemon/CreditBookkeeping.h"
#include "amdaemon/CreditConfig.h"
#include "amdaemon/CreditSound.h"

#include <utility>
#include <functional>
#include <vector>
#include <cstdint>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_credit
/// @{

    /// @brief ビデオゲームのクレジット処理を提供するMonostateクラス。
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    /// 一部の関数は処理完了まで呼び出し元スレッドをブロックする。
    ///
    /// @par ライブラリ利用アプリで実装すべきこと(ビデオタイトルのみ)
    /// - メンバ関数 @ref setCoinInHook(std::function<bool (CreditSound)>) "setCoinInHook"
    ///   または #setCoinInHookWithPlayer でフック関数を設定し、
    ///   フック関数呼び出し時にコイン/クレジット投入音再生処理を行うこと。
    /// - ゲームテストモードにバックアップクリア画面を用意し、
    ///   オペレータがクリアを指示した場合にメンバ関数 #clearBackup を呼び出すこと。
    ///     - 必要に応じて Sequence クラスのメンバ関数 Sequence#clearBackup も呼び出すこと。
    ///
    /// @par INSERT COIN(S) 表示について
    /// CreditUnit クラスの説明を参照すること。
    ///
    /// @ingroup g_common
    class Credit
    {
    public:
        // 下記は暗黙の定義を用いる。
        //Credit() = default;
        //‾Credit() = default;
        //Credit(const Credit&) = default;
        //Credit& operator=(const Credit&) = default;

        /// @brief クレジット機能を利用可能であるか否かを取得する。
        /// @retval true  利用可能である場合。
        /// @retval false 機能が無効である場合。
        bool isAvailable() const;

        /// @brief コイン追加を無視する処理が有効であるか否かを取得する。
        /// @retval true  処理が有効である場合。
        /// @retval false 処理が無効であるか、クレジット機能が無効である場合。
        /// @see #setCoinInIgnored
        ///
        /// メンバ関数 #setCoinInIgnored で設定した値を返す。
        /// ただし、 Sequence クラスによるゲームテストモードの開始時および終了時には
        /// 初期値 false にリセットされる。
        ///
        /// 処理の詳細はメンバ関数 #setCoinInIgnored の説明を参照すること。
        bool isCoinInIgnored() const;

        /// @brief コイン追加を無視する処理を有効にするか否かを設定する。
        /// @param[in] ignored 有効にするならば true 。無効にするならば false 。
        /// @retval true  成功した場合。
        /// @retval false 失敗したか、クレジット機能が無効である場合。
        /// @see #isCoinInIgnored
        ///
        /// この関数によってコイン追加を無視する処理を有効にした場合、
        /// コイン投入、サービスクレジット、電子マネーのコイン購入操作について、
        /// ゲームテストモード中と同等の動作を行うようになる。
        ///
        /// 即ち、コイン投入およびサービスボタン押下によるコイン追加は無視され、
        /// 電子マネーによるコイン購入操作は失敗扱いとなる。
        ///
        /// なお、ゲームテストモード中および進行停止エラー発生中は、
        /// この関数での設定状態とは関係なくコイン追加が無視される。
        ///
        /// この関数による処理有効設定は、 Sequence クラスによるゲームテストモードの
        /// 開始時および終了時にリセットされて処理無効状態に戻る。
        /// この関数自体はゲームテストモード中に呼び出すことも可能だが、
        /// ゲームテストモードの終了時に設定がリセットされるため、実質無意味となる。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool setCoinInIgnored(bool ignored);

        /// @brief 現在のクレジット値とブックキーピングのクリア処理を要求する。
        /// @retval true  成功した場合。
        /// @retval false 失敗したか、クレジット機能が無効である場合。
        ///
        /// クレジット関連のブックキーピングのみがクリアされる。
        /// プレイ回数やプレイ時間等のブックキーピングは
        /// Sequence クラスのメンバ関数 Sequence#clearBackup でクリアできる。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool clearBackup();

        /// @brief 現在のクレジット関連ブックキーピングを取得する。
        /// @return クレジット関連ブックキーピング。
        ///
        /// プレイ回数やプレイ時間等のブックキーピングは
        /// Sequence クラスのメンバ関数 Sequence#getBookkeeping で取得できる。
        const CreditBookkeeping& getBookkeeping() const;

        /// @brief 現在のクレジット設定を取得する。
        /// @return 現在のクレジット設定。
        const CreditConfig& getConfig() const;

        /// @brief コイン投入時に呼び出されるフック関数を設定する。
        /// @param[in] hook フック関数。
        /// @see #setCoinInHookWithPlayer
        ///
        /// この関数でフック関数(コールバック)を設定すると、
        /// 以降のコイン投入時にフック関数が呼び出される。
        ///
        /// より正確には、コイン投入音を鳴らすべきタイミングで呼び出される。
        /// ゲームテストモード中など、コイン投入音を鳴らすべきでないタイミングでは、
        /// たとえコイン投入を行ったとしても呼び出されない。
        ///
        /// コイン投入時には投入音を鳴らすことが作成基準で定められているため、
        /// 必ずこの関数、またはメンバ関数 #setCoinInHookWithPlayer でフック関数を登録し、
        /// 投入音再生処理を実施すること。
        ///
        /// フック関数の第1引数には、投入音種別を表す @ref CreditSound 列挙値が渡される。
        /// 渡される値が CreditSound::None になることはない。
        ///
        /// フック関数は、処理が完了したならば true 、未完了ならば false を返すこと。
        /// false を返した場合は次のフレームで再度フック関数呼び出しが発生する。
        /// false を返す状況としては、前回の投入音が再生完了していない場合等が考えられる。
        ///
        /// フック関数には、第1引数に @ref CreditSound 列挙値を受け取り、
        /// bool 値を返す関数もしくは関数オブジェクトを指定できる。
        /// 任意のクラスのメンバ関数を指定したい場合はラムダ式を用いるとよい。
        ///
        /// コイン投入によってコイン数が増加したプレイヤーを判別したい場合、
        /// この関数の代わりにメンバ関数 #setCoinInHookWithPlayer を用いることができる。
        /// この関数とメンバ関数
        /// #setCoinInHookWithPlayer は内部で共通のフック関数設定先を用いるため、
        /// 両方にフック関数を設定しようとした場合は最後に設定したもののみ有効となる。
        ///
        /// いずれのフック関数も未設定の場合、設定されるまでフック処理が保留される。
        /// そのため、Daemonプロセス起動からフック関数設定までの間にコイン投入を N 回行うと、
        /// フック関数設定直後に N 回連続でフック関数が呼び出される。
        /// ただし、 1 フレームに呼び出される回数は 1 回までとなる。
        ///
        /// @code
        /// // MyClass クラスのメンバ関数 doHook を指定する例
        /// void setHook(MyClass& c)
        /// {
        ///     amdaemon::Credit credit;
        ///     credit.setCoinInHook([&c](amdaemon::CreditSound s) { return c.doHook(s); });
        /// }
        /// 
        /// // MyClass クラスのメンバ関数内から指定する例
        /// void MyClass::setHook()
        /// {
        ///     amdaemon::Credit credit;
        ///     credit.setCoinInHook([this](amdaemon::CreditSound s) { return this->doHook(s); });
        /// }
        /// @endcode
        void setCoinInHook(std::function<bool (CreditSound)> hook);

#if AMDAEMON_MSVC_COMPATIBLE(1900) // VC++2015以降

        /// @brief コイン投入時に呼び出されるフック関数を設定する。(VC++2015以降限定)
        /// @param[in] hook フック関数。
        /// @see #setCoinInHookWithPlayer
        ///
        /// メンバ関数 setCoinInHook(std::function<bool (CreditSound)> hook) のオーバロード。
        ///
        /// 引数のフック関数をそのままメンバ関数 #setCoinInHookWithPlayer に渡すだけである。
        /// よって詳細はメンバ関数 #setCoinInHookWithPlayer の説明を参照すること。
        ///
        /// VC++2013以前の環境では、
        /// std::function クラステンプレートの関数型によるオーバロードが正しく機能しない。
        /// そのためこのメンバ関数はVC++2015以降の環境でのみ定義される。
        void setCoinInHook(
            std::function<bool (CreditSound, const std::vector<std::size_t>&)> hook)
        {
            this->setCoinInHookWithPlayer(std::move(hook));
        }

#endif // VC++2015以降

        /// @brief コイン投入時に呼び出されるフック関数を設定する。
        /// @param[in] hook フック関数。
        /// @see setCoinInHook(std::function<bool (CreditSound)>)
        ///
        /// 基本的にはメンバ関数 setCoinInHook(std::function<bool (CreditSound)>)
        /// に準ずるため、そちらの説明も参照すること。
        ///
        /// この関数は、設定するフック関数に第2引数が追加されている点が異なる。
        ///
        /// フック関数の第2引数には、コイン投入によってコイン数が増加したプレイヤーの
        /// プレイヤーインデックスが配列で渡される。
        /// 配列である理由は、クレジット設定の COIN CHUTE TYPE 設定値が COMMON の場合、
        /// 1回のコイン投入に対して複数のプレイヤーが該当する場合があるためである。
        ///
        /// 第2引数の参照先配列自体は常に有効だが、
        /// フック関数が true を返した直後に配列要素はクリアされ、要素数 0 になる。
        /// フック関数呼び出し時点での配列内容をそれ以降でも利用したい場合、
        /// 参照の保持ではなく値のコピーを行うこと。
        ///
        /// この関数とメンバ関数
        /// @ref setCoinInHook(std::function<bool (CreditSound)>) "setCoinInHook"
        /// は内部で共通のフック関数設定先を用いるため、
        /// 両方にフック関数を設定しようとした場合は最後に設定したもののみ有効となる。
        void setCoinInHookWithPlayer(
            std::function<bool (CreditSound, const std::vector<std::size_t>&)> hook);

        /// @brief コイン投入時に呼び出されるフック関数を解除し、未設定状態に戻す。
        /// @see
        ///     @ref setCoinInHook(std::function<bool (CreditSound)>) "setCoinInHook",
        ///     #setCoinInHookWithPlayer
        ///
        /// フック関数未設定である場合、設定されるまでフック関数呼び出しが保留される。
        void resetCoinInHook();

        /// @brief 有効プレイヤー数を取得する。
        /// @return 有効プレイヤー数。クレジット機能が無効ならば 0 。
        /// @see Core#getPlayerCount
        ///
        /// 機能が有効ならば、 Core#getPlayerCount と同じ値を返す。
        std::size_t getPlayerCount() const;

        /// @brief プレイヤーのクレジット情報インスタンスを取得する。
        /// @param[in] playerIndex プレイヤーインデックス。
        /// @return プレイヤーのクレジット情報インスタンス。
        /// @see Player
        ///
        /// @exception Exception
        /// - クレジット機能が無効である場合。
        /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
        ///   有効プレイヤー数はメンバ関数 #getPlayerCount で取得できる。
        CreditUnit& getPlayer(std::size_t playerIndex);

        /// @copydoc getPlayer
        const CreditUnit& getPlayer(std::size_t playerIndex) const;

        /// @brief 特殊デバイス操作インスタンスを取得する。
        /// @return 特殊デバイス操作インスタンス。
        CreditSpecialDevice& getSpecialDevice();
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_CREDIT_H