bool SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
| SDL_AudioStream * | stream | 変更するオーディオストリーム |
| const int * | chmap | 新しいチャネルマップ. NULLのときデフォルトに戻す |
| int | count | チャネルの数 |
(bool) 成功のとき真, 失敗のとき偽を戻す SDL_GetError()を呼んで詳細を知ることができる.
チャネルマップは任意で, ほとんどの場合は必要なく, SDLが求める順序でデータを渡せばよい.
出力チャネルマップは, SDL_GetAudioStreamDataでストリームから取り出されるデータのチャネルの順序を入れ替える.
配列の各項目は出力チャネルを表していて, チャネルはその値に再マップされる.
ステレオの左右を入れ替えるには, 配列を { 1, 0 } のようにする.
複数のチャネルを同一のチャネルに再マップすることも可能で, その場合は { 1, 1 } のようにすると, ステレオの両チャネルが右チャネルにマップされる.
チャネルマップに有効なチャネルではなく-1を設定すると, そのチャネルはミュートされ無音になる.
チャネルマップでチャネルの数を変更することはできない. 録音またはミュートを設定するのみである.
SDL_GetAudioStreamDataの出力中でも再マップが適応されるため, 出力チャネルマップはいつでも変更できる.
オーディオストリームはデフォルトでは再マップが適用されていない. チャネルマップにNULLを渡すことができ, 再マップを無効にすることができる.
SDLはチャネルマップをコピーする. 呼び出し側は, この関数の呼び出し後に配列を保存する必要はない.
countが現在のオーディオストリームの形式のチャネル数と等しくない場合, 失敗する.
これは, チャネルマップを設定とオーディオストリームの形式の変更で競合が発生しないようにするための対策である.
ストリームの形式の変更とは異なり, 再生デバイスにバインドされたストリームの出力チャネルマップはいつでも変更できる. この関数の呼び出しの後にデバイスからストリームに加えられたデータは新しくマップされているが, 既に加えられたデータは前のマップのままである. チャネルマップがハードウェアのチャネル配置と一致しない場合, SDLは再生デバイスにデータを渡す前に変換する.
この関数はストリーム固有のミューテックスが行われている限りどのスレッドからも安全に呼べる. しかし, 異なるスレッドから同時に形式を異なるチャネル数に変更してはならない.