#include <twl/snd.h>SNDEXResult
SNDEX_SetIirFilterAsync(SNDEXIirFilterTarget target,
const SNDEXIirFilterParam* pParam,
SNDEXCallback callback,
void* arg)| 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. |
| 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, this error is also returned while shutter sound playback is being processed. |
| 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_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. |
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.
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.
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 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.
SNDEX_SetIirFilter
SNDEXIirFilterTarget
SNDEXIirFilterParam
Using IIR_FilterBuilder
2009/05/27 Added a cautionary note about 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/11/06 Made a correction in Asynchronous Process Results (SNDEX_RESULT_EXCLUSIVE) under Return Values.
2008/09/26 Added a description of behavior during shutter sound playback.
2008/09/16 Added links to 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/08/26 Added a description of restrictions during function execution to Note.
2008/07/08 Initial version.
CONFIDENTIAL