#include <twl/snd.h>SNDEXResult SNDEX_SetVolume( u8 volume );| volume | スピーカー音量を指定します。0（SNDEX_VOLUME_MIN と定義）〜7（SNDEX_VOLUME_MAX と定義）の値を指定できます。 |
|---|
| SNDEX_RESULT_SUCCESS | 一連の処理が正常に完了した場合に返ります。 |
|---|---|
| SNDEX_RESULT_ILLEGAL_STATE | NITROプラットフォーム上で当関数を呼び出した場合、 例外ハンドラ内から当関数を呼び出した場合に返ります。 |
| SNDEX_RESULT_INVALID_PARAM | 指定可能範囲外の値をvolumeに指定した場合に返ります。 |
| SNDEX_RESULT_BEFORE_INIT | サウンド拡張機能をSNDEX_Init()により初期化していない場合に返ります。 |
| SNDEX_RESULT_EXCLUSIVE | 他のサウンド拡張機能に関する処理を実行中の場合に返ります。サウンド拡張機能に関する各処理は排他制御により同時には行えませんのでご注意下さい。 また、ARM7内での排他制御エラーが発生した場合にも返ります。この場合はARM7内での処理進捗状況に依存したエラーですので、リトライすると状況が改善する可能性があります。 SNDEX ライブラリの概要にある通り、シャッター音再生処理中もこのエラーを返します。 |
| SNDEX_RESULT_PXI_SEND_ERROR | ARM7へのPXIコマンド発行に失敗した場合に返ります。 ARM7へのPXI送信キューが飽和した場合や、ハードウェアがエラーを検知した場合に発生するエラーですので、リトライすると状況が改善する可能性があります。 |
| SNDEX_RESULT_DEVICE_ERROR | ARM7内で外部デバイスに対するスピーカー音量変更操作に失敗した場合に返ります。 リトライすると状況が改善する可能性がありますが、数回リトライして失敗が続く場合には外部デバイスの暴走等の原因が考えられますので、 成功が返った場合と同様に扱って構いません。 |
| SNDEX_RESULT_FATAL_ERROR | 通常起こり得ないエラーです。 ライブラリの状態管理を無視して直接不正なPXIコマンドを発行した場合、 ARM7コンポーネントとサウンド拡張機能ライブラリのバージョンが異なる場合、 メモリ破壊等によりライブラリの状態管理が異常な状態に陥った場合等に発生する可能性があります。 ランタイムに復旧する手段はありません。 |
スピーカー音量を同期的に変更します。ただし、変更の反映は即時とは限りません。詳しくは「注意」をご覧下さい。
スピーカー音量は、この関数の他に、SNDEX_SetVolumeAsync()や、本体での音量スイッチ操作で変更することができます。
変更した値は本体に記憶され、次回起動時にも反映されます。
内部でSNDEX_SetVolumeAsync()を呼び出し、非同期処理が完了するまで当関数を呼び出したスレッドを停止します。
スレッドからの呼び出しを前提としていますので、例外ハンドラ内からの呼び出しは失敗します。
また、処理の完了はPXI受信割込みにより検知しますので、PXI受信割込みを禁止していると当関数内部でブロックし続けることに注意して下さい。
音量の変更方法については、必ずプログラミングガイドラインでの規定に従って下さい。
スピーカー音量は変更する毎に専用不揮発メモリに保存されます。このため、変更可能な回数が無制限ではありません。 プログラムから頻繁にスピーカー音量を変更するような使い方は避けて下さい。
変更回数を抑制するために本関数の実行についてライブラリ側で制限を設けています。
前回の音量変更時から約10フレーム間（約167msec）は、本関数を呼んでもすぐに変更が反映されずに一旦保留されます。この場合でも本関数は SNDEX_RESULT_SUCCESS を返します。
保留時間が終了した際に、一番最後に呼んだ SNDEX_SetVolume[Async] の引数で指定したスピーカー音量へ変更されます。
なお、SNDEX_GetVolume[Async] が返す値は変更が保留されているスピーカー音量です。保留状態でなければ、現在設定されているスピーカー音量が返ります。
SNDEX_SetVolumeAsync, SNDEX_GetVolume
2009/02/03 「注意」にプログラミングガイドラインについて追記
2009/01/06 スピーカー音量の変更に関するライブラリ側の制限について追記
2008/11/07 シャッター音再生処理時に SNDEX_RESULT_EXCLUSIVE が返ることを追記
2008/07/10 スピーカー音量の説明修正
2008/02/22 スピーカー音量に関する用語統一、説明追加
2008/02/15 初版