Provided by: librtfilter-dev_1.1-4_amd64 
NAME
rtf_filter - filters a chunk of data
SYNOPSIS
#include <rtfilter.h>
unsigned int rtf_filter(hfilter filt, const void *x,
void *y, unsigned int ns);
DESCRIPTION
This function applies the filter referenced by filt on ns samples specified by the pointer x and writes
the filtered data into the array pointed by y. The arrays pointed by made of values whose correspond to
the type specified at the creation of the filter. In addition, the two arrays must not overlap (failing
to comply will lead to undefined results).
Their number of elements have to be equal to ns multiplied by the number of channels processed (specified
at the creation of the filter). The arrays should be packed by channels with the following pattern:
|S1C1|S1C2|...|S1Ck|S2C1|S2C2|....|S2Ck|...|SnsCk|
where SiCj refers to the data value of the i-th sample and the j-th channel and k refers to the number of
channel specified at the creation of the filter.
RETURN VALUE
Returns the number of samples written in the array pointer by y. For most of the filters, this value will
always be equal to ns. This is however not the case of a downsampling filter whose the number of samples
returned may vary from one call to another.
PERFORMANCE CONSIDERATION
On platforms that support SIMD instructions, rtf_filter() is implemented in 2 different versions: one
normal and one using SIMD instruction set which performs nearly 4x faster than the normal one when
processing float data types. The SIMD version is automatically selected at runtime if the following
conditions are met (otherwise, the implementation falls back to the normal version):
- The input x and output y are aligned on 16 bytes boundary (128 bits)
- The sample strides (the size of the data type multiplied by the number of channel) of the input and
output are multiples of 16 bytes.
The first condition is easily met by allocating x and y using memory allocation function mandating a
certain alignment (for example, posix_memalign(3) on POSIX platform).
The second condition is met if the number of channels is carefully chosen. Given the boost obtained with
the SIMD version, it is often interesting to add unused channels into the input and output (when
possible) just to make the strides multiple of 16 bytes (for example using always a multiple of 4
channels when dealing with float and real values).
SEE ALSO
rtf_create_filter(3), rtf_init_filter(3)