SNDEX_SetVolumeAsync

構文

#include <twl/snd.h>

SNDEXResult SNDEX_SetVolumeAsync( u8 volume, SNDEXCallback callback, void* arg );

引数

volume	スピーカー音量を指定します。0（`SNDEX_VOLUME_MIN` と定義）～7（`SNDEX_VOLUME_MAX` と定義）の値を指定できます。
callback	非同期処理完了の通知を受ける`SNDEXCallback型`コールバック関数を指定します。 NULLを指定しても非同期処理は行われますが、非同期処理の完了は検出できなくなります。
arg	callbackに指定した関数に渡す引数を指定します。

返り値

関数への返り値

SNDEX_RESULT_SUCCESS	非同期処理が正常に開始された場合に返ります。非同期処理の結果はcallbackに登録した関数の引数として通知されます。
SNDEX_RESULT_ILLEGAL_STATE	NITROプラットフォーム上で当関数を呼び出した場合に返ります。
SNDEX_RESULT_INVALID_PARAM	指定可能範囲外の値をvolumeに指定した場合に返ります。
SNDEX_RESULT_BEFORE_INIT	サウンド拡張機能を`SNDEX_Init()`により初期化していない場合に返ります。
SNDEX_RESULT_EXCLUSIVE	他のサウンド拡張機能に関する処理を実行中の場合に返ります。サウンド拡張機能に関する各処理は排他制御により同時には行えませんのでご注意下さい。 SNDEX ライブラリの概要にある通り、シャッター音再生処理中もこのエラーを返します。
SNDEX_RESULT_PXI_SEND_ERROR	ARM7へのPXIコマンド発行に失敗した場合に返ります。 ARM7へのPXI送信キューが飽和した場合や、ハードウェアがエラーを検知した場合に発生するエラーですので、リトライすると状況が改善する可能性があります。

非同期処理の結果

SNDEX_RESULT_SUCCESS	一連の処理が正常に完了した場合に通知されます。
SNDEX_RESULT_EXCLUSIVE	ARM7内での排他制御エラーが発生した場合に通知されます。 ARM7内での処理進捗状況に依存したエラーですので、リトライすると状況が改善する可能性があります。
SNDEX_RESULT_DEVICE_ERROR	ARM7内で外部デバイスに対するスピーカー音量変更操作に失敗した場合に通知されます。リトライすると状況が改善する可能性がありますが、数回リトライして失敗が続く場合には外部デバイスの暴走等の原因が考えられますので、成功が通知された場合と同様に扱って構いません。
SNDEX_RESULT_FATAL_ERROR	通常起こり得ないエラーです。ライブラリの状態管理を無視して直接不正なPXIコマンドを発行した場合、 ARM7コンポーネントとサウンド拡張機能ライブラリのバージョンが異なる場合、メモリ破壊等によりライブラリの状態管理が異常な状態に陥った場合等に発生する可能性があります。ランタイムに復旧する手段はありません。

説明

スピーカー音量を非同期的に変更します。ただし、変更の反映は即時とは限りません。詳しくは「注意」をご覧下さい。

スピーカー音量は、この関数の他に、SNDEX_SetVolume()や、本体での音量スイッチ操作で変更することができます。変更した値は本体に記憶され、次回起動時にも反映されます。

関数への返り値がSNDEX_RESULT_SUCCESSでない場合には、非同期処理は行われず、コールバックも発生しません。また、非同期処理の完了はPXI受信割込みによって通知されるため、PXI受信割込みを禁止しているとコールバックが発生しないことに注意して下さい。

注意

音量の変更方法については、必ずプログラミングガイドラインでの規定に従って下さい。

スピーカー音量は変更する毎に専用不揮発メモリに保存されます。このため、変更可能な回数が無制限ではありません。プログラムから頻繁にスピーカー音量を変更するような使い方は避けて下さい。

変更回数を抑制するために本関数の実行についてライブラリ側で制限を設けています。
前回の音量変更時から約10フレーム間（約167msec）は、本関数を呼んでもすぐに変更が反映されずに一旦保留されます。この場合でも本関数は SNDEX_RESULT_SUCCESS を返します。
保留時間が終了した際に、一番最後に呼んだ SNDEX_SetVolume[Async] の引数で指定したスピーカー音量へ変更されます。
なお、SNDEX_GetVolume[Async] が返す値は変更が保留されているスピーカー音量です。保留状態でなければ、現在設定されているスピーカー音量が返ります。

また、引数で指定したコールバック関数が呼ばれるのは本関数の処理完了時であり、スピーカー音量の変更が実際に反映されたときではありません。

参照

SNDEX_SetVolume, SNDEX_GetVolumeAsync

履歴

2009/02/03 「注意」にプログラミングガイドラインに関して追記
2009/01/06 スピーカー音量の変更に関するライブラリ側の制限について追記、音量の最小・最大値の定義について追記
2008/11/07 シャッター音再生処理時に SNDEX_RESULT_EXCLUSIVE が返ることを追記
2008/11/06 「返り値」非同期処理の結果の誤記修正(SNDEX_RESULT_EXCLUSIVE)
2008/07/10 スピーカー音量の説明修正
2008/02/22 スピーカー音量に関する用語統一、説明追加
2008/02/15 初版