MGL::Audio::Source#

概要#

MGL::Audio::Sourceは読み込み済みのオーディオボイスを再生するためのクラスです。

このクラスはMGL内部で管理されているオーディオソースの実体にアタッチして動作するハンドルクラスです。アプリケーション側からは通常、このクラスを経由してオーディオの再生や制御を行います。

MGLのオーディオ再生の基礎的な説明はオーディオ再生を参照してください。

宣言#

namespace MGL::Input
{
    class Source;
}

メンバ情報#

種類	名前	内容	バージョン
関数	コンストラクタ		1.0.0+
関数	Attach	ボイスとソースの関連付け	1.0.0+
関数	Detach	ボイスとソースの関連付けを解除	1.0.0+
関数	IsAttached	ソースがボイスと関連付けられているかを取得	1.0.0+
関数	Play	ボイスの再生	1.0.0+
関数	IsPlaying	再生中かどうかを取得	1.0.0+
関数	Pause	一時停止	1.0.0+
関数	Resume	一時停止からの再開	1.0.0+
関数	IsPaused	一時停止の状態を取得	1.0.0+
関数	Stop	停止	1.0.0+
関数	SetVolume	音量の設定	1.0.0+
関数	GetVolume	ボリュームの取得	1.0.0+
関数	Fadeout	フェードアウト	1.0.0+
関数	IsFading	フェード中かどうかを取得	1.0.0+

コンストラクタ#

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        // (1) 空のオーディオソースを生成
        constexpr Source() noexcept;

        // (2) ボイスと関連付けたオーディオソースを生成
        Source(VoiceKey voiceKey, bool isAutoRemove = true) noexcept;
    };
}

引数#

(1) 空のオーディオソースを生成

引数なし

(2) ボイスと関連付けたオーディオソースを生成

MGL::Audio::VoiceKey voiceKey: 関連付けるボイスのキー
bool isAutoRemove: 再生終了後に自動で再生リストから削除するかのフラグ

説明#

オーディオソースのコンストラクタです。

(1)は空のオーディオソースを生成します。空のオーディオソースは再生前にAttachを呼び出して手動でボイスと関連付けるか、Playで再生時にボイスキーを指定する必要があります。

(2)は生成と同時にボイスとの関連付けを行います。voiceKeyには関連付けるボイスのキーを指定します。isAutoRemoveにtrueを指定した場合、ソースの再生が終了した時点で再生リストから削除し、このクラスは空の状態に戻ります。同じソースで繰り返し再生を行う場合などにおいてはfalseを指定してください。省略時はtrueが指定されます。

(2)で生成した場合、正しくボイスと関連付けられているかをチェックする場合はIsAttachedを呼び出してください。

オーディオソースを用いたボイス再生の詳細についてはオーディオの再生を参照してください。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// (1) 空のオーディオソースを生成
MGL::Audio::Source source;

// ボイスの関連付け
if (source.Attach(kTitleBGM, false))
{
    MGL_TRACE("関連付け成功");
}

// (2) ボイスと関連付けたオーディオソースを生成
MGL::Audio::Source source(kTitleBGM, false);

if (source.IsAttached())
{
    MGL_TRACE("関連付け成功");
}

バージョン情報#

MGL 1.0.0

初回リリース

Attach#

ボイスとソースの関連付け

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        bool Attach(VoiceKey voiceKey, bool isAutoRemove) noexcept;
    };
}

引数#

MGL::Audio::VoiceKey voiceKey: 関連付けるボイスのキー
bool isAutoRemove: 再生終了後に自動で再生リストから削除するかのフラグ

戻り値#

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

説明#

このクラスとオーディオボイスを関連付けます。

voiceKeyには関連付けるボイスのキーを指定します。isAutoRemoveにtrueを指定した場合、ソースの再生が終了した時点で再生リストから削除し、このクラスは空の状態に戻ります。同じソースで繰り返し再生を行う場合などにおいてはfalseを指定してください。省略時はtrueが指定されます。

処理に成功した場合、戻り値にtrueが返ります。ボイスキーが有効でない場合など、正しく関連付けが行われなかった場合はfalseが返ります。

既に関連付けが行われているソースに対してこの関数を呼び出した場合、それまでの関連付けが解除されて新たな関連付けが行われます。

オーディオソースを用いたボイス再生の詳細についてはオーディオの再生を参照してください。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source;

// ボイスの関連付け
if (source.Attach(kTitleBGM, false))
{
    MGL_TRACE("関連付け成功");
}

バージョン情報#

MGL 1.0.0

初回リリース

Detach#

ボイスとソースの関連付けを解除

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        void Detach() noexcept;
    };
}

説明#

このクラスとオーディオボイスとの関連付けを解除し、自身を空の状態に戻します。

この関数が行うのは関連付けの解除のみであり、再生中のボイスはそのまま継続されます。再生停止を目的としている場合、Stopを呼び出してください。

この関数はデストラクタで自動的に呼び出されるため、クラスの寿命が切れた場合も同様の処理が行われます。

警告

この関数を呼び出した後、再生中のボイスを制御する手段はありません。ループ再生を行う場合など、再生後に制御する必要がある場合はこの関数を呼び出さないでください。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// タイトル画面のBGMのソースを準備
MGL::Audio::Source source(kTitleBGM);

// アタッチできていたら再生して即デタッチ
if (source.IsAttached())
{
    source.Play()
    source.Detach();
}

// 補足: 上記の処理はこの2行と等価
{
    MGL::Audio::Source source(kTitleBGM);
    source.Play();
}

バージョン情報#

MGL 1.0.0

初回リリース

IsAttached#

ソースがボイスと関連付けられているかを取得

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        [[nodiscard]] bool IsAttached() const noexcept;
    };
}

戻り値#

bool: 関連付けられている場合はtrue、そうでない場合はfalse

説明#

このクラスがオーディオボイスと関連付けられている状態であるかを取得します。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source(kTitleBGM, false);

if (source.IsAttached())
{
    MGL_TRACE("関連付け成功");
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

Play#

ボイスの再生

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        // (1) ボイスを指定して再生
        bool Play(
                VoiceKey voiceKey,
                bool isAutoRemove = true,
                uint32_t trackIndex = 0,
                LoopType loopType = LoopType::ResourceDefault,
                float volume = 1.0f) noexcept;


        // (2) 関連付けられているボイスを再生
        bool Play(
                uint32_t trackIndex = 0,
                LoopType loopType = LoopType::ResourceDefault,
                float volume = 1.0f) noexcept;

    };
}

引数#

(1) ボイスを指定して再生

MGL::Audio::VoiceKey voiceKey: 再生するボイスのキー
bool isAutoRemove: 再生終了後に自動で再生リストから削除するかのフラグ
uint32_t trackIndex: トラック番号
MGL::Audio::LoopType loopType: ループタイプ
float volume: 再生音量

(2) 関連付けられているボイスを再生

uint32_t trackIndex: トラック番号
MGL::Audio::LoopType loopType: ループタイプ
float volume: 再生音量

戻り値#

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

説明#

ボイスの再生を開始します。

(1) はボイスとの関連付けと再生を同時に行います。関連付けの処理はvoiceKeyとisAutoStopを指定したAttachの呼び出しと等価です。

(2) は既にボイスと関連付けられているソースに対して使用します。ボイスと関連付けられていない状態では処理に失敗しfalseを返します。

引数のtrackIndexは再生するボイスのトラック番号を指定します。この値はボイスが複数のトラックを持つ場合にのみ利用可能であり、単一トラックで構成されたボイスにおいては無視されます。省略時は0が指定されます。

loopTypeはループ再生を行うかどうかの指定です。省略またはLoopType::ResourceDefaultを指定した場合、そのリソースが持つループ設定を使用します。リソースごとのループ設定はオーディオボイスが管理しており、得られる結果はオーディオボイス側の実装に依存します。

volumeは再生開始時の音量の指定です。この値は再生時に乗算されるスケール値であり、省略時には1.0fが指定されます。

オーディオ再生の詳細についてはオーディオの再生も参照してください。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// (1) ボイスを指定して再生

MGL::Audio::Source source;

if (!source.Play(kTitleBGM))
{
    MGL_TRACE("再生失敗");
}

// (2) 関連付けられているボイスを再生

MGL::Audio::Source source(kTitleBGM);

if (!source.Play())
{
    MGL_TRACE("再生失敗");
}

バージョン情報#

MGL 1.0.0

初回リリース

IsPlaying#

再生中かどうかを取得

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        [[nodiscard]] bool IsPlaying() const noexcept;
    };
}

戻り値#

bool: 再生中である場合にtrue、再生していない場合はfalse

説明#

ソースが現在再生中であるかを取得します。

この関数はPauseによる一時停止中でもtrueを返します。実際に出力されているかを知るにはIsPausedと併せて利用してください。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source(kTitleBGM)

source.Play();

if (source.IsPlaying())
{
    MGL_TRACE("再生中");
}
else
{
    MGL_TRACE("再生していない");
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

Pause#

一時停止

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        void Pause(bool isEnabled = true) noexcept;
    };
}

引数#

bool isEnabled: trueで一時停止、falseで解除。省略時はtrue

説明#

再生中のソースを一時停止します。再開する場合は引数にfalseを指定するか、Resumeを呼び出します。

一時停止中はIsPausedがtrueを返すようになります。IsPlayingは一時停止中もtrueを返すことに注意してください。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source(kTitleBGM);

// 再生
source.Play();

// 一時停止
source.Pause();

// この状態では source.IsPaused() と source.IsPlaying() は共に true を返す

// 再開
source.Resume();    // source.Pause(false); と等価

バージョン情報#

MGL 1.0.0

初回リリース

Resume#

一時停止からの再開

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        void Resume() noexcept;
    };
}

説明#

一時停止を解除します。

この関数はPauseの引数にfalseを指定した場合と等価です。

利用例#

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

バージョン情報#

MGL 1.0.0

初回リリース

IsPaused#

一時停止の状態を取得

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        [[nodiscard]] bool IsPaused() const noexcept;
    };
}

戻り値#

bool: 一時停止中にtrue、そうでなければfalse

説明#

現在一時停止中かを取得します。

IsPlayingは一時停止中もtrueを返すため、正しく一時停止状態を知るにはこちらの関数を使用してください。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source(kTitleBGM);

// 再生
source.Play();

// 一時停止
source.Pause();

// 一時停止状態をチェック
if (source.IsPaused())
{
    MGL_TRACE("一時停止中");
}
else
{
    MGL_TRACE("一時停止していない");
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

Stop#

停止

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        bool Stop() const noexcept;
    };
}

戻り値#

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

説明#

再生中のソースを再生リストから削除し、即座に出力を停止させます。

コンストラクタやアタッチ処理のisAutoRemoveにtrueを指定している場合、この関数を呼び出した後に自身は空の状態に戻ります。falseを指定していた場合は関連付けらたままの状態で残り、再び再生が可能です。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source(kTitleBGM, false);

// 再生
source.Play();

// 停止
source.Stop();

// コンストラクタの isAutoRemove に false を指定しているので、もう一度再生可能。
// もし true を指定していた場合は失敗する。
source.Play();

バージョン情報#

MGL 1.0.0

初回リリース

SetVolume#

音量の設定

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        // (1) 即座に反映
        void SetVolume(float volume) noexcept;

        // (2) 時間経過と共に反映（フェード処理）
        void SetVolume(float volume, float fadeTimeSec, bool isAutoStop = false) noexcept;
    };
}

引数#

(1) 即座に反映

float volume: 適用する音量

(2) 時間経過と共に反映（フェード処理）

float volume: 適用する音量
float fadeTimeSec: 音量変化にかける時間。単位は秒
bool isAutoStop: trueを指定すると、音量変化が完了した後に自動で停止する。省略時はfalse

説明#

ソース音量を設定します。音量は再生時に乗算されるスケール値であり、デフォルトでは1.0fです。

(1) は指定した音量を即座に反映させます。

(2) は現在の音量からfadeTimeSecで指定した時間をかけてvolumeまで変化させます。isAutoStopにtrueを指定した場合、音量変化が完了した時点で再生を終了します。

この関数は再生前に設定した値は反映されません。再生時の初期音量を指定したい場合はPlayの引数volumeに指定してください。

フェードアウト処理を行わせたい場合はFadeoutも利用可能です。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// 再生時にフェードインを行う例

MGL::Audio::Source source(kTitleBGM);

// 音量0で再生
source.Play(0, MGL::Audio::LoopType::ResourceDefault, 0.0f);

// 3秒かけて音量 1.0 まで変化させる
source.SetVolume(1.0f, 3.0f);

バージョン情報#

MGL 1.0.0

初回リリース

GetVolume#

ボリュームの取得

宣言#

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

戻り値#

float: 現在の音量

説明#

現在のソース音量を取得します。音量は再生時に乗算されるスケール値であり、デフォルトでは1.0fです。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// 再生時にフェードインを行う例

MGL::Audio::Source source(kTitleBGM);

// 音量0で再生
source.Play(0, MGL::Audio::LoopType::ResourceDefault, 0.5f);

// 現在のソース音量を取得
auto sourceVolume = source.GetVolume();
MGL_TRACE("現在のソース音量: %f", sourceVolume);    // 0.5fが出力される

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

Fadeout#

フェードアウト

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        void Fadeout(float fadeTimeSec, bool isAutoStop = true) noexcept;
    };
}

引数#

float fadeTimeSec: 音量変化にかける時間。単位は秒
bool isAutoStop: trueを指定すると、音量変化が完了した後に自動で停止する。省略時はtrue

説明#

フェードアウトを行うための関数です。

現在のソース音量を、fadeTimeSecで指定した時間をかけて0.0fまで変化させます。isAutoStopにtrueが指定されている場合、音量変化が完了した時点で再生を終了します。

この関数はSetVolumeのvolumeに0.0fを指定し、残りの引数をそのまま渡した処理と等価です。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source(kTitleBGM);

// 再生
source.Play();

// 3秒かけてフェードアウト
source.Fadeout(3.0f);

バージョン情報#

MGL 1.0.0

初回リリース

IsFading#

フェード中かどうかを取得

宣言#

namespace MGL::Audio
{
    class Source
    {
    public:
        [[nodiscard]] bool IsFading() const noexcept;
    };
}

戻り値#

bool: フェード中ならtrue、そうでなければfalse

説明#

本関数を呼び出した時点において、音量変化が行われているかを取得します。

利用例#

// タイトル画面のBGMを表すボイスキー
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

MGL::Audio::Source source(kTitleBGM);

// 再生
source.Play();

// 3秒かけてフェードアウト
source.Fadeout(3.0f);

if (source.IsFading())
{
    // フェード開始後3秒以内ならここに到達
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

MGLドキュメント

MGL::Audio::Source

Contents

MGL::Audio::Source#

概要#

宣言#

メンバ情報#

コンストラクタ#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

Attach#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Detach#

宣言#

説明#

利用例#

バージョン情報#

関連#

IsAttached#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Play#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

IsPlaying#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Pause#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

Resume#

宣言#

説明#

利用例#

バージョン情報#

関連#

IsPaused#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Stop#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

SetVolume#

宣言#

引数#