int Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes)
| frequency | 出力サンプリング周波数 (Hz). ゲームではMIX_DEFAULT_FREQUENCY(22050)がよい値である |
| format | 出力サンプル形式 |
| channels | 出力チャネル数. 2ならステレオ, 1ならモノラル. これはミキシングのチャネルとは無関係である |
| chunksize | 一度に出力するバイト数 |
| device | オープンするデバイス名. NULLのとき利用可能なデフォルトが選択される |
| allowed_changes | 変更フラグ(SDL_AUDIO_ALLOW_*フラグを参照) |
(これよりも単純な関数Mix_OpenAudio()が存在する. ほとんどのアプリケーションはこれで十分である.)
オーディオデバイスは音声を出力する. そのため, アプリケーションはこれをオープンする必要がある.
この関数はSDLオーディオシステムが初期化されているかチェックする. もし初期化されていなければ, あなたの代わりにSDL_Init(SDL_INIT_AUDIO)を呼び出して初期化する.
より詳細にあなたのプログラムを制御できるため, この関数を呼ぶ前に初期化することもできる. (そしてそれを推奨する!)
オーディオデバイスの設定に特にこだわりがなく, データが特定の形式でなければ, ここで設定するのは妥当とされる値のデフォルトで十分である. SDL_mixerはあなたが与えたオーディオデータを必要なときに自動的に変換する.
しかし, あなたがオーディオデータを自由に決められて, あらかじめその形式がわかっているならば, 背後でSDL_mixweは何も変換せず直接ハードウェアにデータを渡せるように一致する形式でオーディオデバイスをオープンしてCPUの負荷を減らすことができる. 一部の環境では, ハードウェアが特定の形式にのみ対応しており, 全てを一致させるために注意する必要があるが, 多くの場合は自分のデータの方が制御しやすいため, 必要な形式でデバイスをオープンする方がよい.
形式の特定には別の注意点もある. ミキシングバッファを(Mix_SetPostMix, エフェクトの登録, Mix_HookMusicで)直接操作する場合, コードが特定の形式を想定している場合があり, その部分にも形式を指定する必要がある.
オーディオデバイスの周波数はHzで指定する. 現在の環境では48000が妥当とされるデフォルト値である.
オーディオデバイスのサンプル形式はSDLのAUDIO_*から選択する. 恐らくAUDIO_S16SYS(16ビットオーディオ)が安全なデフォルトである. 現在のシステムではAUDIO_F32SYS(32ビット浮動小数点オーディオ)の方が好ましいかもしれない.
チャネル数は一般的にはモノラルの1またはステレオの2だが, 思い切ってサラウンドの4(クアッド), 6(5.1), 7(6.1), 8(7.1)を試してもよいだろう.
オーディオデバイスのチャンクサイズは一度にデバイスに渡されるサンプルフレーム数(モノラルならば1フレームあたり1サンプル, ステレオならば1フレームあたり2サンプルなど)である. 少ないほど遅れが少なくなるが, 少なすぎると取りこぼしのリスクが増大する. 通常は2048が妥当とされるデフォルトだが, アプリケーションによっては1024から4096の間を試すとよいだろう.
オーディオデバイスは一度に1つしかオープンできない. 設定を変更したい場合はデバイスを閉じて再オープンする必要があり, 再生中に途切れなく行うことはできない.
この関数のdeviceパラメータでシステム上の特定のオーディオハードウェアを選択することができる. NULLを指定するとSDL_mixerはあなたの代わりに(多くの場合はユーザの望み通りの)最適なデフォルトを選択する. SDL_mixerにはオープンするデバイス名を決定する仕組みは用意されていない. しかし, SDL_GetNumAudioDevices()で利用可能なデバイス数を得て, SDL_GetAudioDeviceName()でループすると一覧が得られる. これを行う場合, 初めにSDL_Init(SDL_INIT_AUDIO)を呼んでSDLオーディオシステムを初期化すること!
allowed_changesパラメータは設定変更の許容範囲を設定する. SDLにはSDL_AUDIO_ALLOW_*フラグが用意されている. これは特定の設定を変えてもアプリケーションは問題ないことをSDL_mixerに通知するためのものである. 例えば, アプリケーションはSint16形式のステレオデータを必要とするが, サンプルレートとチャックサイズは変更されても問題ないとする. この場合, アプリケーションはSDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGEを指定する. こうするとシステムのハードウェアが要求する形式に合わない場合, SDL_mixerはアプリケーションに代わってハードウェアが必要とするパラメータを選択する. SDL_AUDIO_ALLOW_フラグが指定されていない場合, SDL_mixerはデータをハードウェアが要求する形式に背後で変換しなければならない. もしアプリケーションが厳密な設定を必要とするならばallowed_changesを0にすること.
変更が許可されている場合, アプリケーションはMix_QuerySpec()で最終的なデバイス設定を得ることができる.
この関数が成功を戻したならば, 音を出力する準備が整っており, オーディオデータを読み込み再生することができる.
プログラムが終了してオーディオデバイスを使い終えたならば, アプリケーションはMix_CloseAudio()で破棄する必要がある.