# SNDEX_SetIirFilterAsync

## Definition

  `#include <twl/snd.h>`

      SNDEXResult
      SNDEX_SetIirFilterAsync(SNDEXIirFilterTarget target,
                              const SNDEXIirFilterParam* pParam,
                              SNDEXCallback callback,
      void* arg)

## Arguments

target | Target to which to apply an IIR filter, indicated as an `SNDEXIirFilterTarget` enumerated type.
pParam | `SNDEXIirFilterParam` structure that determines the attributes of the IIR filter.
callback | Callback function to invoke after the IIR filter is set.
arg | Argument to pass to the callback function.

## Return Values

### Function Return Values

SNDEX_RESULT_SUCCESS | Asynchronous processing started successfully. The asynchronous processing results will be passed as an argument to the function registered in callback.
SNDEX_RESULT_ILLEGAL_STATE | Returned when this function is called on the NITRO platform or when the codec is running in CODEC-DS mode.
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. 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.

### Asynchronous Process Results

SNDEX_RESULT_SUCCESS | The whole series of operations completed successfully.
SNDEX_RESULT_ILLEGAL_STATE | This function has been called on the NITRO platform, when the codec is running in CODEC-DS mode, or while the shutter sound is being played by the `DSP_PlayShutterSound` function.
SNDEX_RESULT_EXCLUSIVE | A mutex error occurred in the ARM7. This error depends upon the progress of ARM7 processing, so conditions may improve when a retry is made.
SNDEX_RESULT_DEVICE_ERROR | The ARM7 internally 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 was a notification of 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.

## Description

Sets the IIR filters (from 1 to 5 stages) to apply to the audio data that is either input from the microphone or output from the speakers. This function must be called once for each filter stage being set in a multistage filter.
After configuration is complete, the user-specified callback function will be invoked.

To generate parameters for a low-pass filter, high-pass filter, band-pass filter, and band-elimination filter, use `$TwlSDK/docs/TechnicalNotes/IIR_FilterBuilder.xls`. However, you cannot calculate parameters by specifying characteristics of the filter. See How to Use IIR_FilterBuilder for more details.

If this function does not return a value of `SNDEX_RESULT_SUCCESS`, the asynchronous processing and callback will not be run.
Also note that a PXI receive interrupt will send notification when the asynchronous processing is complete, so callbacks will not occur if PXI receive interrupts are prohibited.

To maintain the shutter sound playback volume, this function returns `SNDEX_RESULT_ILLEGAL_STATE` and quits without doing anything while the `DSP_PlayShutterSound` function is executing.
The library initializes the IIR filter settings while the shutter sound is playing and then reconfigures the settings after playback has finished.

The system will wait for the IIR filters to finish being set before either entering sleep mode or performing hardware reset. For more information, see the Sleep and Hardware Reset and Shutdown overviews.

## Note

You can only set one IIR filter stage at a time. This function will return a `SNDEX_RESULT_EXCLUSIVE` error if it is called again while an IIR filter is currently being set.

It takes somewhere between 10 and several hundred milliseconds to set a single IIR filter stage. While it is being set, SPI mutexes will be used on the ARM7. During this time, microphone sampling, Touch Screen sampling, power management, and NVRAM will be forced to wait, causing delays. Accordingly, use caution when using the devices listed above in parallel with this function.

If you configure an IIR filter to increase the gain of input audio data, depending on the input source, the calculation results will be saturated (that is, top out at the maximum value), causing the sound to be distorted. IIR filters should usually be used to reduce the gain for uncertain input sources.

When setting multiple IIR filters, make sure no stage is saturated. This is because filters will be applied in order, one stage at a time, to the input waveform (see `SNDEXIirFilterTarget` for information on the order in which filters are applied).

Restrictions will be applied depending on the filter target target when this function is used.

When target indicates microphone input data (`SNDEX_IIR_FILTER_ADC_*`), proper sampling data cannot be obtained because the A/D converter is stopped during configuration. Because it is acceptable to simply avoid using the sampling data from this interval, microphone sampling itself does not need to be stopped.

When target indicates speaker output data (`SNDEX_IIR_FILTER_DAC_*`), sounds currently being played will not be output correctly because the D/A converter is stopped during configuration. Specifically, audio will be cut off during the interval while the converter is stopped. Although afterward audio playback will resume from the point where it was cut off, it may sometimes sound like noise immediately after playback resumes. Audio may sound better if it is faded in or out by the application.

## See Also

`SNDEX_SetIirFilter`
`SNDEXIirFilterTarget`
`SNDEXIirFilterParam`
`Using IIR_FilterBuilder`

## Revision History

2008/11/07 Added mention that `SNDEX_RESULT_EXCLUSIVE` is returned during shutter sound playback (deleted the text added in 2008/09/26 version).
2008/11/06 Made correction in Asynchronous Process Results (`SNDEX_RESULT_EXCLUSIVE`) in Return Values.
2008/09/26 Added description of behavior during shutter sound playback.
2008/09/16 Added links to Sleep, Hardware Reset and Shutdown overview pages.
2008/09/11 Revised the text in Return Values. Added mention of the processing time and effect on other devices to Note.
2008/09/06 Added a link to Using IIR_FilterBuilder.
2008/08/26 Added a description of restrictions during function execution to Note.
2008/07/08 Initial version.

CONFIDENTIAL