#include <twl/snd.h>SNDEXResult SNDEX_GetVolumeAsync( u8* volume, SNDEXCallback callback, void* arg );| volume | スピーカー音量を取得する変数へのポインタを指定します。 この変数には非同期処理中に値が書き込まれますので、非同期処理が完了するまで他の用途に使用すべきではありません。 |
|---|---|
| callback | 非同期処理完了の通知を受けるSNDEXCallback型コールバック関数を指定します。
NULLを指定しても非同期処理は行われますが、非同期処理の完了は検出できなくなります。 |
| arg | callbackに指定した関数に渡す引数を指定します。 |
| SNDEX_RESULT_SUCCESS | 非同期処理が正常に開始された場合に返ります。非同期処理の結果はcallbackに登録した関数の引数として通知されます。 |
|---|---|
| SNDEX_RESULT_ILLEGAL_STATE | NITROプラットフォーム上で当関数を呼び出した場合に返ります。 |
| 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内で外部デバイスに対するスピーカー音量取得操作に失敗した場合に通知されます。 リトライすると状況が改善する可能性がありますが、数回リトライして失敗が続く場合には外部デバイスの暴走等の原因が考えられますので、 成功が通知された場合と同様に扱って構いません。このエラーが発生した場合、volumeには0が格納されます。 |
| SNDEX_RESULT_FATAL_ERROR | 通常起こり得ないエラーです。 ライブラリの状態管理を無視して直接不正なPXIコマンドを発行した場合、 ARM7コンポーネントとサウンド拡張機能ライブラリのバージョンが異なる場合、 メモリ破壊等によりライブラリの状態管理が異常な状態に陥った場合等に発生する可能性があります。 ランタイムに復旧する手段はありません。 |
スピーカー音量を非同期的に取得します。スピーカー音量は0(最小 SNDEX_VOLUME_MIN と定義)〜7(最大 SNDEX_VOLUME_MAX と定義)の値です。
GetVolumeAsync と GetCurrentVolumeAsync の違いは、保留状態にある音量値を取得できるかどうかのみです（前者が取得可能です）。
保留状態に関しては SNDEX_SetVolume[Async] の説明、本ページの「注意」をご覧下さい。
保留された音量値は数フレーム後には反映されるため、厳密に本関数をコールしたときの音量を取得する必要がない場合、
および SNDEX_SetVolume[Async]() を使用しない場合は従来通り SNDEX_GetVolumeAsync を使用すれば問題ありません。
スピーカー音量は、SNDEX_SetVolumeAsync()やSNDEX_SetVolume()の他に、
本体での音量スイッチ操作でも変更されることがあります。
変更された値は本体に記憶され、次回起動時にも反映されます。
関数への返り値がSNDEX_RESULT_SUCCESSでない場合には、非同期処理は行われず、コールバックも発生しません。 また、非同期処理の完了はPXI受信割込みによって通知されるため、PXI受信割込みを禁止しているとコールバックが発生しないことに注意して下さい。
SNDEX_SetVolume[Async]() によるスピーカー音量の連続変更を避けるため、一度変更すると約10フレームの間、変更が保留されます。
約10フレームの保留時間の終了後、保留されていたスピーカー音量への設定が行われます。
SNDEX_GetVolume, SNDEX_SetVolumeAsync
2009/01/06 SNDEX_SetCurrentVolume の追加に伴う返り値の違いについて追記
2008/11/07 シャッター音再生処理時に SNDEX_RESULT_EXCLUSIVE が返ることを追記
2008/11/06 「返り値」非同期処理の結果の誤記修正(SNDEX_RESULT_EXCLUSIVE)
2008/07/10 スピーカー音量の説明修正
2008/02/22 スピーカー音量に関する用語統一、説明追加
2008/02/15 初版