SNDEX_SetIirFilter

Definition

#include <twl/snd.h>

SNDEXResult
SNDEX_SetIirFilter(SNDEXIirFilterTarget target,
                   const SNDEXIirFilterParam* pParam)

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.

Return Values

`SNDEX_RESULT_SUCCESS`	The whole series of operations completed successfully.
`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. 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.

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.

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.

Note that because PXI receive interrupts are used to detect the processing's completion, this function continues to block internally 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 waits 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 returns 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 are used on the ARM7. During this time, microphone sampling, Touch Screen sampling, power management, and NVRAM are forced to wait, causing delays. Accordingly, use caution when using the devices listed above in parallel with this function.

You must take special care when setting IIR filter parameters. If you configure an IIR filter to increase the gain of input audio data, some input sources will cause the calculation results to be saturated (topped out at the maximum value) and hence distort the sound. As a basic rule, with uncertain input sources IIR filters should be used to reduce the gain. 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). In particular, because IIR filters use previous output data, setting parameters to amplify it may cause sound to be emitted from the speakers regardless of the system volume or mute state set by the SNDEX_SetMute function.

Restrictions are 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 are not output correctly because the D/A converter is stopped during configuration. Specifically, audio is cut off during the interval while the converter is stopped. Although afterward audio playback resumes 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.

Revision History

2009/05/27 Added a note related to setting IIR filter parameters.
2008/11/07 Mentioned that SNDEX_RESULT_EXCLUSIVE is returned during shutter sound playback (deleted the text added on 2008/09/26).
2008/09/26 Added a description of behavior during shutter sound playback.
2008/09/16 Added links to the overview pages for Sleep and Hardware Reset and Shutdown.
2008/09/11 Revised 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/09/02 Added descriptions to Note.
2008/08/26 Added a description of restrictions during function execution to Note.
2008/07/08 Initial version.

CONFIDENTIAL