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)