MGL::Audio#

概要#

MGL::Audioで定義されているトップレベルのAPIです。

関数#

種類

名前

内容

定数式

MakeVoiceKey

ボイスキーの生成

関数

LoadVoice

ボイスの読み込み

関数

UnloadVoice

ボイスの破棄

関数

SetMasterVolume

マスター音量の設定

関数

GetMasterVolume

マスター音量の取得

関数

SetVoiceVolume

ボイスのボリュームを設定

関数

GetVoiceVolume

ボイスのボリュームを取得

MakeVoiceKey#

ボイスキーの生成

宣言#

namespace MGL::Audio
{
    constexpr VoiceKey MakeVoiceKey(
                            const char *key,
                            uint32_t seed = kDefaultVoiceKeySeed) noexcept;
}

引数#

const char *key

ボイスキーの生成に使用する文字列

uint32_t seed

ボイスキーのハッシュ生成に使用するシード値。省略時はMGL::Audio::kDefaultVoiceKeySeed

戻り値#

MGL::Audio::VoiceKey

生成されたボイスキー

説明#

文字列からボイスキーを生成するための定数式です。

ボイスキーはオーディオボイスにアクセスするために使用する一意のキーです。オーディオボイス読み込み時に指定し、以降はそのボイスキーを経由してオーディオボイスにアクセスします。

キーの生成にはMGL::Hash::FNV1aが使用されます。引数のseedに異なる値を指定すると生成される値も変化するため、衝突などの問題が生じた場合はこの値を指定することで解決される場合があります。引数を省略した場合はMGL::Audio::kDefaultVoiceKeySeedが指定されます。

関連#

LoadVoice#

ボイスの読み込み

宣言#

namespace MGL::Audio
{
    template <class VoiceClass, class... Args>
    std::weak_ptr<VoiceClass> LoadVoice(Args... args) noexcept;
}

引数#

VoiceClass

追加するオーディオボイスのクラス名

Args... args

オーディオボイスのコンストラクタに渡す引数リスト

戻り値#

std::weak_ptr<VoiceClass>

正常に処理が完了した場合はそのオーディオボイスクラスの弱参照ポインタ、失敗時には空の弱参照ポインタ

説明#

オーディオボイスの生成と読み込み要求を行うためのテンプレート関数です。

テンプレート引数には生成するオーディオボイスクラスを指定します。

関数の引数はそのままコンストラクタへと渡されます。必要な引数は生成するオーディオボイスクラスに依存しますが、通常はここでボイスキーや読み込むファイルのパスなどを指定します。

処理に成功した場合は生成したオーディオボイスクラスの弱参照ポインタを返します。失敗時の戻り値は空の弱参照ポインタとなります。

この関数は生成したクラスに対して読み込み要求を行いますが、その読み込みが同期的に行われるかは生成するオーディオボイスに依存します。この関数が成功していても、読み込みに成功しているとは限らない点にご注意ください。

オーディオボイスの読み込みの詳細についてはオーディオボイスの登録を参照してください。

利用例#

// タイトル画面のBGMを読み込むと仮定して、そのボイスを表すキーを生成
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// MGL::Audio::WaveVoice で タイトル画面のBGMを読み込む
// （ WaveVoice はMGLの標準構成に含まれるWave形式の音声ファイルを読み込むオーディオボイスクラス）
auto voice = MGL::Audio::LoadVoice<MGL::Audio::WaveVoice>(kTitleBGM, "$resource/bgm_title.wav");

// 失敗している場合は空の弱参照ポインタとなる
if (voice.expired())
{
    MGL_TRACE("読み込み失敗");
}

関連#

UnloadVoice#

ボイスの破棄

宣言#

namespace MGL::Audio
{
    inline bool UnloadVoice(VoiceKey key) noexcept;
}

引数#

MGL::Audio::VoiceKey key

破棄するボイスのキー

戻り値#

bool

成功時にtrue、失敗時にfalse

説明#

読み込み済みのオーディオボイスを破棄します。

破棄したボイスは、それ以降はボイスキーによるアクセスが行えなくなります。オーディオボイスは共有ポインタで管理されているため、実際にメモリから解放されるのは全てのボイスの利用を終えた後になります。

利用例#

// タイトル画面のBGMを読み込むと仮定して、そのボイスを表すキーを生成
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// タイトル画面用BGMのボイスを破棄
if (MGL::Audio::Unload(kTitleBGM))
{
    MGL_TRACE("破棄成功");
}
else
{
    MGL_TRACE("破棄失敗");  // 読み込まれていないボイスキーを指定した場合などに到達
}

関連#

SetMasterVolume#

マスター音量の設定

宣言#

namespace MGL::Audio
{
    inline void SetMasterVolume(float volume) noexcept;
}

引数#

float volume

設定するマスター音量

説明#

マスター音量を設定します。

設定値は各々の音量に乗算されるスケール値であり、デフォルトでは1.0fです。

利用例#

// マスター音量を0.5倍(50%)に設定
MGL::Audio::SetMasterVolume(0.5f);

関連#

GetMasterVolume#

マスター音量の取得

宣言#

namespace MGL::Audio
{
    [[nodiscard]] inline float GetMasterVolume() noexcept;
}

戻り値#

float

現在のマスター音量

説明#

現在のマスター音量を取得します。

マスター音量は各々の音量に乗算されるスケール値であり、デフォルトでは1.0fです。

利用例#

auto masterVolume = MGL::Audio::GetMasterVolume();
MGL_TRACE("現在のマスター音量: %f", masterVolume);

関連#

SetVoiceVolume#

ボイスの音量を設定

宣言#

namespace MGL::Audio
{
    inline void SetVoiceVolume(VoiceKey voiceKey, float volume) noexcept;
}

引数#

MGL::Audio::VoiceKey voiceKey

音量を設定するボイスのキー

float volume

設定する音量

説明#

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

ここで設定した音量は、そのボイスを再生する際に乗算されるスケール値です。デフォルトの音量は1.0fです。

利用例#

// タイトル画面のBGMを読み込むと仮定して、そのボイスを表すキーを生成
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// タイトル画面のBGMの音量を0.5倍(50%)に設定
MGL::Audio::SetVoiceVolume(kTitleBGM, 0.5f);

関連#

GetVoiceVolume#

ボイスの音量を取得

宣言#

namespace MGL::Audio
{
    [[nodiscard]] inline float GetVoiceVolume(VoiceKey voiceKey) noexcept;
}

引数#

MGL::Audio::VoiceKey voiceKey

音量を取得するボイスのキー

戻り値#

float

ボイスの音量

説明#

指定したボイスの音量を取得します。

ボイスの音量は、そのボイスを再生する際に乗算されるスケール値です。デフォルトの音量は1.0fです。

指定したボイスキーに対応するボイスが存在しない場合は0.0fが返ります。

利用例#

// タイトル画面のBGMを読み込むと仮定して、そのボイスを表すキーを生成
constexpr const auto kTitleBGM = MGL::Audio::MakeVoiceKey("TitleBGM");

// タイトル画面のBGMの音量を0.5倍(50%)に設定
auto voiceVolume = MGL::Audio::GetVoiceVolume(kTitleBGM);
MGL_TRACE("ボイス音量: %f", voiceVolume);

関連#