MGL::Audio::Voice#

概要#

MGL::Audio::Voiceは音源となるオーディオボイスを実装するための基底クラスです。

音声ファイルやソフトウェア音源などを実装する場合はこのクラスを継承したクラスを作成します。オーディオボイスはMGL::Audio::LoadVoiceにて登録後、MGL::Audio::Sourceを用いて再生可能です。

オーディオ再生についてはオーディオ再生を、オーディオボイスの実装方法についてはオーディオボイスの作成（準備中）を参照してください。

宣言#

namespace MGL::Input
{
    class Voice;
}

メンバ情報#

種類	名前	内容
列挙型	Status	ボイスの状態
列挙型	Type	ボイスの種類
関数	コンストラクタ
純粋仮想関数	Load	読み込み処理
仮想関数	GetSample	サンプルデータの取得
仮想関数	Start	再生開始時の処理
仮想関数	Stop	再生停止時の処理
純粋仮想関数	GetTotalFrame	最大サンプルフレーム数を取得
純粋仮想関数	IsLoop	ループフラグの取得
純粋仮想関数	GetLoopFrame	ループフレームを取得
純粋仮想関数	GetTrackCount	トラック数を取得
関数	GetKey	ボイスキーの取得
関数	RemoveRequests	削除要求
関数	SetStatus	ボイスの状態を設定
関数	GetStatus	ボイスの状態を取得
関数	GetType	ボイスの種類を取得
関数	SetVolume	ボイス音量を設定
関数	GetVolume	ボイス音量を取得

Status#

ボイスの状態

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        enum class Status
        {
            None,       //!< 状態なし（初期状態）
            Loading,    //!< 読み込み中
            Error,      //!< エラー発生
            Ready,      //!< 準備完了
            Remove      //!< 削除要求済み
        };
    };
}

説明#

オーディオボイスの状態を表す値の定義です。値の内容は次の通りです。

None: 状態を持っていません。生成直後の初期値にのみ使用されています。
Loading: 読み込み中の状態を表す値です。この状態のボイスを再生しようとした場合、状態がReadyに変化するまで再生が保留されます。
Error: オーディオボイス内部でエラーが発生している状態を表す値です。この状態のボイスは再生できません。継承先では読み込みに失敗した場合などにこの値を設定してください。
Ready: 再生可能な状態を表す値です。継承先ではサンプルデータを取得可能な状態になったタイミングでこの状態を設定してください。
Remove: 削除要求を受けてから実際に削除されるまでの間に設定される値です。

Type#

ボイスの種類

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        enum class Type
        {
            Static,     //!< スタティック: 読み込み後は内部状態が変化しない。同時再生可能
            Dynamic     //!< ダイナミック: 再生中に内部状態が変化する。同時再生不可能。ストリーム再生など
        };
    };
}

説明#

オーディオボイスの種類を表す値の定義です。値の内容は次の通りです。

Static: ボイス初期化後に内部状態が変化しないボイスであることを表す値です。この種類のボイスは1つのボイスに対して複数のソースを割り当てられるようになり、同時再生が可能となります。ボイスが持つ全てのサンプルデータに対し、常にランダムアクセスが可能な場合に設定してください。
Dynamic: ボイス初期化後も内部状態が変化するボイスであることを表す値です。この種類のボイスは1つのボイスに対して1つのソースしか割り当てられず、同時再生ができません。ストリーミング再生やソフトウェア音源などを実装する場合はこちらを利用してください。

コンストラクタ#

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        constexpr Voice(VoiceKey key, Type type) noexcept;
    };
}

引数#

MGL::Audio::VoiceKey key: このボイスに割り当てるボイスキー
MGL::Audio::Voice::Type type: このボイスの種類

説明#

オーディオボイスの基底クラスのコンストラクタです。

keyはこのボイスを表すキーです。通常はアプリケーション側が管理する値であるため、継承先のコンストラクタの引数で受けるようにし、その値をそのまま渡してください。

typeはこのボイスの種類を表す値を指定します。MGL::Audio::Voice::Typeの説明を参照し、実装するボイスに適合する値を選択してください。

利用例#

// Staticな YourAudioVoice を実装する場合の例

class YourAudioVoice : public MGL::Audio::Voice
{
public:
    YourAudioVoice(MGL::Audio::VoiceKey voiceKey) noexcept
        : MGL::Audio::Voice(voiceKey, MGL::Audio::Voice::Type::Static)
    {
    }

    // 他省略
};

Load#

読み込み処理

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        virtual bool Load() noexcept = 0;
    };
}

戻り値#

bool: 成功時にtrue、失敗時にfalse

説明#

オーディオリソースの読み込み処理を記述するための純粋仮想関数です。MGL::Audio::LoadVoiceが実行された際にこの関数が呼び出されます。

非同期でリソースを読み込む場合はSetStatusにLoadingを指定した後に読み込みスレッドを起動してください。同期的に読み込む場合は、Loadingを介さず読み込み処理の後にMGL::Audio::Voice::Status::Readyを設定しても問題ありません。

読み込み処理に失敗した場合、SetStatusにErrorを設定してください。

引数の戻り値は、同期読み込みの場合はその処理結果をそのまま返してください。非同期読み込みの場合は、読み込みスレッドの起動に成功した時点でtrueを返してしまっても問題ありません。

利用例#

宣言

class YourAudioVoice : public MGL::Audio::Voice
{
public:
    virtual bool Load() noexcept override;

    // 他省略

private:
    std::future<void> _loadFuture;
};

非同期読み込みの例

bool YourAudioVoice::Load() noexcept
{
    // 先に状態を Loading に設定
    SetStatus(MGL::Audio::Voice::Status::Loading);

    // 読み込みスレッドを起動
    _loadFuture = std::async(std::launch::async, [this]
    {
        if (LoadResource())     // この関数で読み込んで成否の結果を返していると仮定
        {
            SetStatus(MGL::Audio::Voice::Status::Ready);
        }
        else
        {
            SetStatus(MGL::Audio::Voice::Status::Error);
        }
    });

    return true;
}

同期読み込みの例

bool YourAudioVoice::Load() noexcept
{
    if (!LoadResource())     // この関数で読み込んで成否の結果を返していると仮定
    {
        SetStatus(MGL::Audio::Voice::Status::Error);
        return false;
    }

    SetStatus(MGL::Audio::Voice::Status::Ready);
    return true;
}

GetSample#

サンプルデータの取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        // (1) Staticボイスからの取得
        virtual bool GetSample(
                    float &outDataL,
                    float &outDataR,
                    uint32_t trackIndex,
                    size_t sampleFrame) const noexcept;

        // (2) Dynamicボイスからの取得
        virtual bool GetSample(float &outDataL, float &outDataR) noexcept;
    };
}

引数#

(1) Staticボイスからの取得

float &outDataL: 左チャンネル出力のサンプルデータの格納先
float &outDataR: 右チャンネル出力のサンプルデータの格納先
uint32_t trackIndex: トラック番号
size_t sampleFrame: 取得するサンプルデータのフレーム

(2) Dynamicボイスからの取得

float &outDataL: 左チャンネル出力のサンプルデータの格納先
float &outDataR: 右チャンネル出力のサンプルデータの格納先

戻り値#

bool: 継続の場合はtrue、終了の場合はfalse

説明#

サンプリングデータを取得する際に呼び出される関数です。

コンストラクタで指定されたボイスの種類がStaticかDynamicかで呼び出される関数が変化します。この関数はどちらも純粋仮想関数ではありませんが、設定した種類に応じてどちらか一方を実装しなければなりません。

(1) はTypeにStaticを指定した場合に呼び出される関数です。指定されたトラック番号とサンプルフレームに対応したサンプリングデータを、outDataLとoutDataRの両方に格納してください。この関数はconstであるため、内部で自身を書き換えることはできません。

(2) はTypeにDynamicを指定した場合に呼び出される関数です。トラック番号と現在のサンプルフレームは指定されず、自身で管理している値を使用する必要があります。トラック番号は再生開始時にStartの引数に渡されるため、こちらを保持して使用してください。この関数はサンプリングデータを格納後、サンプルフレームなどの内部状態を適切に更新する必要があります。

格納先のoutDataLとoutDataRは0.0fから1.0fでクランプされた浮動小数点数で格納する必要があります。

再生すべきサンプリングデータが末尾に達し、再生を終了する場合は戻り値にfalseを返してください。

ループ再生に関わる処理は、Staticボイスの場合はソース側が管理するため、ボイス側で必要な処理は末尾に達した際にfalseを返すことのみです。Dynamicボイスの場合はソース側では管理しないため、ループ再生の処理も含めてボイス側で実装する必要があります。

Start#

再生開始時の処理

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        virtual bool Start(uint32_t trackIndex, LoopType loopType) noexcept;
    };
}

引数#

uint32_t trackIndex: トラック番号
MGL::Audio::LoopType loopType: ループタイプ

戻り値#

成功時にtrue、失敗時にfalse

説明#

オーディオソースがボイスの再生を開始する際に呼び出す関数です。

引数のtrackIndexとloopTypeは、MGL::Audio::Source::Playの引数に指定した値がそのまま渡されます。Dynamicボイスを作成する場合、これらの値はソース側では管理しないため、この関数の内容を保持する必要があります。

再生可能である場合は戻り値にtrueを返してください。

継承先でこの関数を実装しなかった場合、何もせずにtrueを返します。

Stop#

再生停止時の処理

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        virtual void Stop() noexcept;
    };
}

説明#

オーディオソースがボイスの再生を終了する際に呼び出される関数です。主にDynamicボイスで再生終了のタイミングを知る際に利用します。

継承先でこの関数を実装しなかった場合は何も処理しません。

GetTotalFrame#

最大サンプルフレーム数を取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        [[nodiscard]] virtual uint32_t GetTotalFrame(uint32_t trackIndex) const noexcept = 0;
    };
}

引数#

uint32_t trackIndex: トラック番号

戻り値#

uint32_t: トラック番号に対応した最大サンプルフレーム数

説明#

指定されたトラック番号の最大サンプルフレーム数を取得するための関数です。

継承先においては、そのトラック番号が指すサンプリングデータの末尾のフレーム数を返してください。トラック番号に対応したサンプリングデータが存在しない場合は0を返してください。

IsLoop#

ループフラグの取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        [[nodiscard]] virtual bool IsLoop(uint32_t trackIndex) const noexcept = 0;
    };
}

引数#

uint32_t trackIndex: トラック番号

戻り値#

bool: ループする場合はtrue、しない場合はfalse

説明#

指定したトラック番号にループの指示があるかを取得するための関数です。再生開始時にMGL::Audio::LoopTypeのResourceDefaultが指定された場合、この戻り値に基づいてループ再生を行うかが決定されます。

トラック番号に対応したサンプリングデータが存在しない場合はfalseを返してください。

GetLoopFrame#

ループフレームを取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        [[nodiscard]] virtual uint32_t GetLoopFrame(uint32_t trackIndex) const noexcept = 0;
    };
}

引数#

uint32_t trackIndex: トラック番号

戻り値#

uint32_t: そのトラックに設定されたループフレーム

説明#

トラックにループ再生の指定がある場合に、そのループポイントを取得するための関数です。

再生開始時にループ再生が指示されていた場合、サンプリングデータの末尾に達した後に、再生を終了せずにこの関数が返すフレームへと移動します。

GetTrackCount#

トラック数を取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        virtual uint32_t GetTrackCount() const noexcept = 0;
    };
}

戻り値#

uint32_t: トラック数

説明#

ボイスが持つトラック数を取得するための関数です。

ボイスが複数のトラックを持たない場合、この関数の戻り値は1にしてください。

GetKey#

ボイスキーの取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        [[nodiscard]] constexpr VoiceKey GetKey() const noexcept;
    };
}

戻り値#

MGL::Audio::VoiceKey: このボイスのキー

説明#

このボイスを表すボイスキーを取得します。

利用例#

constexpr const auto kVoiceKey = MGL::Audio::MakeVoiceKey("sample");

auto voice = MGL::Audio::LoadVoice<YourAudioVoice>(kVoiceKey, "$resource/audio_file");

if (voice.GetKey() == kVoiceKey)
{
    // 通常はここに到達
}

RemoveRequests#

削除要求

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        void RemoveRequests() noexcept;
    };
}

説明#

ボイスに対する削除要求を行う関数です。

この関数はMGL内部が適切なタイミングで呼び出すため、通常は明示的に呼び出す必要はなく、利用も推奨されません。アプリケーション側からボイスを削除する場合はMGL::Audio::UnloadVoiceを利用してください。

SetStatus#

ボイスの状態を設定

宣言#

namespace MGL::Input
{
    class Voice
    {
    protected:
        void SetStatus(Status status) noexcept;
    };
}

引数#

MGL::Audio::Voice::Status status: 設定するボイスの状態

説明#

ボイスの状態を変更します。

この関数はprotectedで宣言されているため、継承先クラス以外からは使用できません。

利用例#

Loadの利用例を参照してください。

GetStatus#

ボイスの状態を取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        [[nodiscard]] Status GetStatus() const noexcept;
    };
}

戻り値#

MGL::Audio::Voice::Status status: 現在のボイスの状態

説明#

ボイスの状態を取得します。

利用例#

constexpr const auto kVoiceKey = MGL::Audio::MakeVoiceKey("sample");

auto voice = MGL::Audio::LoadVoice<YourAudioVoice>(kVoiceKey, "$resource/audio_file");

if (voice.GetStatus() == MGL::Audio::Voice::Status::Error)
{
    MGL_TRACE("ボイスの初期化に失敗している");

}

GetType#

ボイスの種類を取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        [[nodiscard]] constexpr Type GetType() const noexcept;
    };
}

戻り値#

MGL::Audio::Voice::Type: このボイスの種類

説明#

このボイスの種類を取得します。

利用例#

constexpr const auto kVoiceKey = MGL::Audio::MakeVoiceKey("sample");

auto voice = MGL::Audio::LoadVoice<YourAudioVoice>(kVoiceKey, "$resource/audio_file");

switch (voice.Type())
{
    case MGL::Audio::Voice::Type::Static:
        MGL_TRACE("Staticボイス");
        break;

    case MGL::Audio::Voice::Type::Dynamic:
        MGL_TRACE("Dynamicボイス");
        break;
}

SetVolume#

ボイス音量を設定

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        void SetVolume(float volume) noexcept;
    };
}

引数#

float volume: 設定する音量

説明#

ボイス音量を設定します。

ボイス音量はこのボイスに一律で適用されるスケール値です。初期状態では1.0fが設定されています。

ボイスキーを経由した設定を行う場合はMGL::Audio::SetVoiceVolumeを利用してください。

利用例#

constexpr const auto kVoiceKey = MGL::Audio::MakeVoiceKey("sample");

auto voice = MGL::Audio::LoadVoice<YourAudioVoice>(kVoiceKey, "$resource/audio_file");

// このボイスの音量を 0.5倍（50%）に設定
voice.SetVolume(0.5f);

// MGL::Audio::SetVoiceVolume(kVoiceKey, 0.5f); と等価

GetVolume#

ボイス音量を取得

宣言#

namespace MGL::Input
{
    class Voice
    {
    public:
        [[nodiscard]] float GetVolume() const noexcept;
    };
}

戻り値#

float: ボイスに設定されている音量

説明#

ボイスに設定されている音量を取得します。

ボイス音量はこのボイスに一律で適用されるスケール値です。初期状態では1.0fが設定されています。

ボイスキーを経由して取得する場合はMGL::Audio::GetVoiceVolumeを利用してください。

利用例#

constexpr const auto kVoiceKey = MGL::Audio::MakeVoiceKey("sample");

auto voice = MGL::Audio::LoadVoice<YourAudioVoice>(kVoiceKey, "$resource/audio_file");

MGL_TRACE("ボイス音量: %f", voice.GetVolume());

MGLドキュメント

MGL::Audio::Voice

Contents

MGL::Audio::Voice#

概要#

宣言#

メンバ情報#

Status#

宣言#

説明#

Type#

宣言#

説明#

関連#

コンストラクタ#

宣言#

引数#

説明#

利用例#

関連#

Load#

宣言#

戻り値#

説明#

利用例#

関連#

GetSample#

宣言#

引数#

戻り値#

説明#

関連#

Start#

宣言#

引数#

戻り値#

説明#

関連#

Stop#

宣言#

説明#

関連#

GetTotalFrame#

宣言#

引数#

戻り値#

説明#

IsLoop#

宣言#

引数#

戻り値#

説明#

関連#

GetLoopFrame#

宣言#

引数#

戻り値#

説明#

関連#

GetTrackCount#

宣言#

戻り値#

説明#

GetKey#

宣言#

戻り値#

説明#

利用例#

関連#

RemoveRequests#

宣言#

説明#

関連#

SetStatus#

宣言#

引数#

説明#

利用例#

関連#

GetStatus#