#include <twl/snd.h>SNDEXResult SNDEX_SetIgnoreHWVolume( u8 volume );| volume | Speaker volume. You can specify any value between 0 (defined as SNDEX_VOLUME_MIN) and 7 (defined as SNDEX_VOLUME_MAX). |
|---|
SNDEX_RESULT_SUCCESS |
The whole series of operations completed successfully. |
|---|---|
SNDEX_RESULT_ILLEGAL_STATE |
This function has been called on the NITRO platform or from an exception handler. |
SNDEX_RESULT_INVALID_PARAM |
A value outside of the specifiable range is given for volume. |
SNDEX_RESULT_BEFORE_INIT |
Extended sound features have not been initialized by the SNDEX_Init function. |
SNDEX_RESULT_EXCLUSIVE |
Processing for other extended sound features is running. Note that mutexes are used for each of the extended sound features, so they cannot be used simultaneously. This is also returned when a mutex error occurred in the ARM7. When this is the case, the situation may improve on a retry because the error is dependent on the progress of processing in ARM7. As mentioned in the SNDEX Library Overview, the error also returns during processing of shutter sound playback. |
SNDEX_RESULT_PXI_SEND_ERROR |
A PXI command failed to be sent to the ARM7. This error occurs when the PXI send queue for the ARM7 has filled up or when the hardware has detected an error. As a result, the state may improve when a retry is made. |
SNDEX_RESULT_DEVICE_ERROR |
The ARM7 failed to change the speaker volume for an external device. Conditions may improve on a retry, but continued failures after multiple retries could indicate that the external device is not responding, so you may handle this as if it were a return value indicating success. |
SNDEX_RESULT_FATAL_ERROR |
This error should not ordinarily occur. This may occur when an illegal PXI command was sent directly, ignoring library state management; when the ARM7 component and the extended sound feature library have different versions; when library state management has fallen into an abnormal state due to memory corruption; or when other such conditions arise. There is no way to recover from this at run time. |
Customized version of the SNDEX_SetVolume function, designed to play sounds at a prespecified volume at a certain time, regardless of the console's speaker volume setting.
The function synchronously changes the speaker volume. The changes are not necessarily applied immediately.
This function differs from the SNDEX_SetVolume function in that it saves the value of the speaker volume before making the change, and this can be used to later restore the volume with the SNDEX_ResetIgnoreHWVolume function. During the time up until the SNDEX_ResetIgnoreHWVolume function is executed, the saved speaker volume is restored automatically in the post-process callback at the time of a hardware reset or a shutdown, and in the callback before sleep.
The function uses the SNDEX_GetVolume function to get the current volume and the SNDEX_SetVolume function to change the value to volume. The function's calling thread is stopped until the process completes. This function expects to be called from a thread, so it fails if it is called from an exception handler. Because the completion of processes are detected by PXI receive interrupts, be aware that this function continues to block if PXI receive interrupts have been prohibited.
The example below shows sample code for the playing sounds at a prespecified volume with specific timing.
Example:
u8 target_volume;
main()
{
:
SNDEX_Init();
:
/* Configuring target_volume */
:
SNDEX_SetIgnoreHWVolume( target_volume ); // Save v, the console's volume before the call
/* The sound playback process *
* During this time, console volume restored to v upon hardware reset, shutdown or sleep */
SNDEX_ResetIgnoreHWVolume( ); // Speaker volume restored to v
:
}
Be sure that your method for changing the volume adheres to the Programming Guidelines.
Before, if this function was repeatedly called (if you called this function before calling the SNDEX_ResetIgnoreHWVolume function), the saved volume value (this value was changed at the time a reset is applied) was overwritten when this function was called later, in TWL-SDK 5.2 and earlier versions.
However, in TWL-SDK 5.3 RC and later versions, the volume value saved when the function is first called is now maintained.
The speaker volume is saved in dedicated nonvolatile memory each time it is changed. It consequently cannot be modified an infinite number of times. Avoid frequent changes to the speaker volume from the program.
For more information, see Note for the SNDEX_SetVolume function.
SNDEX_GetVolume
SNDEX_SetVolume
SNDEX_ResetIgnoreHWVolume
2009/07/09 Added to Note a description of behavior when this function is repeatedly called.
2009/02/02 Initial version.
CONFIDENTIAL