# SNDEX_SetIgnoreHWVolume

## 構文

  `#include <twl/snd.h>`

      SNDEXResult SNDEX_SetIgnoreHWVolume( 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_SetVolume()` をカスタマイズした関数です。
スピーカー音量を同期的に変更します。ただし、変更の反映は即時とは限りません。

`SNDEX_SetVolume()` と異なり、変更前のスピーカー音量が保存され、`SNDEX_ResetIgnoreHWVolume()` によって保存した音量に戻します。
また、`SNDEX_ResetIgnoreHWVolume()` が実行されるまでの間は、ハードウェアリセットやシャットダウン時の後処理コールバックもしくはスリープ前コールバック内で保存されたスピーカー音量へ自動的に戻すようになります。

内部では `SNDEX_GetVolume()`によって現在音量を取得し、`SNDEX_SetVolume()`によって音量を `volume` へ変更しています。処理が完了するまで当関数を呼び出したスレッドを停止します。 スレッドからの呼び出しを前提としていますので、例外ハンドラ内からの呼び出しは失敗します。 また、各処理の完了はPXI受信割込みにより検知しますので、PXI受信割込みを禁止していると当関数内部でブロックし続けることに注意して下さい。

下の例は、あるタイミングで事前に指定された音量でサウンドを再生するサンプルコードです。

> (例)
> `u8　　target_volume;
> main()
> {
> ：
> SNDEX_Init();
> ：
> /* target_volume の設定処理 */
> ：
> SNDEX_SetIgnoreHWVolume( target_volume );　// コール直前の本体音量 v を保存
> /* サウンドの再生処理　　　　　　　　　　　　　　*
> * この間にハードウェアリセットやシャットダウン、*
> * スリープが行われると本体音量が v に戻る 　　　*/
> SNDEX_ResetIgnoreHWVolume( );　// スピーカー音量を v へ戻す
> ：
> }

> `

## 注意

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

本関数を連続で呼び出した場合（`SNDEX_ResetIgnoreHWVolume` を呼ぶ前に本関数を呼んだ場合）、
TWL-SDK 5.2 以前では後から本関数が呼ばれた際に、保存されている音量値（リセット時に変更される音量値）を上書きしていましたが
TWL-SDK 5.3 RC 以降では初回呼び出し時に保存されていた音量値を維持するようになりました。

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

## 参照

`SNDEX_GetVolume, SNDEX_SetVolume, SNDEX_ResetIgnoreHWVolume`

## 履歴

2009/07/09 「注意」項に本関数を連続で呼び出した際の挙動について追記
2009/02/02 初版