bool MIX_PlayTrack(MIX_Track *track, SDL_PropertiesID options);
| MIX_Track * | track | ミキシングを開始(または再開)するトラック |
| SDL_PropertiesID | options | 再生のプロパティ. 0も可 |
トラックは再生のとき最後に割り付けられた入力を使用する. トラックは入力が割り付けられている必要がある. そうでなければこの関数は失敗する. 入力はMIX_SetTrackAudio(), MIX_SetTrackAudioStream(), またはMIX_SetTrackIOStream()で割り付ける.
トラックが既に再生中または一時停止中の場合, この関数はトラックを新しいパラメータで再再生する.
いくつかのパラメータがあり, 将来的には追加される可能性がある. パラメータはSDL_PropertiesIDで指定する.
パラメータには妥当なデフォルトがあり, optionsに0を指定すると全てデフォルトを選択したことになる.
SDL_PropertiesIDについてはSDLのドキュメントに詳細がある.
これらのプロパティに対応している:
MIX_PROP_PLAY_LOOPS_NUMBER: 終わりに達したときのループ回数.
この値が1ならば先頭から1回ループする.
0のときループしない.
-1のとき無限にループする.
入力がシーク不能で値が0でない場合, この関数は成功を戻すがトラックはループすべき位置で停止する.
デフォルトは0
MIX_PROP_PLAY_MAX_FRAME_NUMBER: トラックをこのサンプルフレーム位置までミックスする.
これはオーディオファイルのEOFに達したように扱われる.
-1の場合, 全てのオーディオデータが制限なく使用される.
デフォルトは-1
MIX_PROP_PLAY_MAX_MILLISECONDS_NUMBER: MIX_PROP_PLAY_MAX_FRAME_NUMBERプロパティと目的は同じだが, サンプルフレームの代わりにミリ秒で指定する.
両方のプロパティを設定すると, サンプルフレームが優先される.
デフォルトは-1
MIX_PROP_PLAY_START_FRAME_NUMBER: ミックスを開始するトラックの入力のサンプルフレーム位置.
値が0以下のときトラックの先頭から開始する.
入力がシーク不能で0より大きな値のとき, この関数は失敗する.
デフォルトは0
MIX_PROP_PLAY_START_MILLISECOND_NUMBER: MIX_PROP_PLAY_START_FRAME_NUMBERプロパティと目的は同じだが, サンプルフレーム数の代わりにミリ秒で指定する.
両方のプロパティを設定すると, サンプルフレームが優先される.
デフォルトは0
MIX_PROP_PLAY_LOOP_START_FRAME_NUMBER: トラックがループする場合, ループで戻るサンプルフレーム位置.
これで最初はトラックの先頭のイントロを再生するが, 途中の位置をループ地点とすることができる.
値が0以下のときトラックの先頭からループする.
デフォルトは0
MIX_PROP_PLAY_LOOP_START_MILLISECOND_NUMBER: MIX_PROP_PLAY_LOOP_START_FRAME_NUMBERプロパティと目的は同じだが, サンプルフレーム数の代わりにミリ秒で指定する.
両方のプロパティを設定すると, サンプルフレームが優先される.
デフォルトは0
MIX_PROP_PLAY_FADE_IN_FRAMES_NUMBER: 新しく開始したトラックでフェードインするサンプルフレーム数.
トラックのミックスは無音から始まり多くのサンプルフレームを渡りながらスムーズに全ボリュームに達する.
トラックのフェードインが完了する前にループした場合は, ループ地点から正しくフェードが続く.
値は0以下の場合, フェードインは無効になり, トラックは全ボリュームからミックスされる.
デフォルトは0
MIX_PROP_PLAY_FADE_IN_MILLISECONDS_NUMBER: MIX_PROP_PLAY_FADE_IN_FRAMES_NUMBERプロパティと目的は同じだが, サンプルフレーム数の代わりにミリ秒で指定する.
両方のプロパティを設定すると, サンプルフレームが優先される.
デフォルトは0
MIX_PROP_PLAY_FADE_IN_START_GAIN_FLOAT: フェードインの場合の開始時点のボリュームレベル.
0.0fは無音で1.0fは全ボリュームで, その間は全て線形にゲインが変化する.
値は0.0fから1.0fの間にクリッピングされる.
デフォルトは0.0f
MIX_PROP_PLAY_APPEND_SILE。E_FRAMES_NUMBER: このトラックのミックスの終わりに, 全てのループが完了した後で, このサンプリングフレーム数の無音をオーディオファイルに書き込まれているものであるかのように追加する.
これは, リバーブのような音声の終点を超えてサンプルを生成する必要があるエフェクトをアプリケーションがコールバックで実装することや, 直接管理せずに新しい音声を開始する前に待ち時間を挿入することができるようにする.
値が0以下の場合, トラックが停止する前に無音を生成しない.
デフォルトは0
MIX_PROP_PLAY_APPEND_SILENCE_MILLISECONDS_NUMBER: MIX_PROP_PLAY_APPEND_SILENCE_FRAMES_NUMBERプロパティと目的は同じだが, サンプルフレーム数の代わりにミリ秒で指定する.
両方のプロパティを設定すると, サンプルフレームが優先される.
デフォルトは0
MIX_PROP_PLAY_HALT_WHEN_EXHAUSTED_BOOLEAN: 真のとき, トラックが入力を完全に使い果たしたとき, ミキサーはトラックを停止にする(そして適切にMIX_TrackStoppedCallbackなどを呼ぶ).
さらに再生を続けるには, トラックを再開する必要がある.
偽のとき, トラックは単にミックスを行わないだけで停止しない.
これは様々な巧妙なロジックになりうるが, 特にトラックの入力がMIX_SetTrackAudioStream()で割り付けられたSDL_AudioStreamの場合に有用である.
このプロパティを真に設定して, 明確な終わりのある完全なオーディオデータをストリームにプッシュすると, トラックは他のオーディオ入力が適用されたときと同じように動作する.
偽を設定すると, ストリームに新しいデータが追加されたときミキサーは可能な限り早くそのデータを使用する. これは新たなVoIPソケットなどでストリームに少しずつ入れられるデータを再生したい場合に有用である.
この場合, 必要なときにオーディオデータがなければミックスした出力が途切れてしまうため, これを避けるために十分なデータをバッファすること.
トラックは, ループと追加された無音がミックスされるまで入力を使い果たしたとみなされない. (また, 入力がSDL_AudioStreamの場合, ループは無意味である.)
デフォルトは真
MIX_PROP_PLAY_START_ORDER_NUMBER: これは特別な場合のプロパティで, ほとんどのアプリケーションは無視できる.
modファイル形式の場合, ファイルの先頭ではなく指定した"order"インデックスからミックスを開始する.
値が0未満のとき, このプロパティは無視される.
デコーダがこのプロパティに対応していない場合も無視される.
このプロパティが無視されなかった場合, 代わりにMIX_PROP_PLAY_START_FRAME_NUMBERプロパティとMIX_PROP_PLAY_START_MILLISECOND_NUMBERプロパティが無視される.
デフォルトは-1.
SDL_mixer 3.2.2以降
この関数が失敗したとき, このトラックのミックスは開始(既に開始した場合は再開)されない.
この関数はどのスレッドからも安全に呼べる.