1RTF_FILTER(3) rtfilter library RTF_FILTER(3)
2
6 rtf_filter - filters a chunk of data
7
9 #include <rtfilter.h>
10 unsigned int rtf_filter(hfilter filt, const void *x,
12 void *y, unsigned int ns);
13
15 This function applies the filter referenced by filt on ns samples spec‐
16 ified by the pointer x and writes the filtered data into the array
17 pointed by y. The arrays pointed by made of values whose correspond to
18 the type specified at the creation of the filter. In addition, the two
19 arrays must not overlap (failing to comply will lead to undefined
20 results).
21 Their number of elements have to be equal to ns multiplied by the num‐
23 ber of channels processed (specified at the creation of the filter).
24 The arrays should be packed by channels with the following pattern:
25 |S1C1|S1C2|...|S1Ck|S2C1|S2C2|....|S2Ck|...|SnsCk|
26 where SiCj refers to the data value of the i-th sample and the j-th
27 channel and k refers to the number of channel specified at the creation
28 of the filter.
29
31 Returns the number of samples written in the array pointer by y. For
32 most of the filters, this value will always be equal to ns. This is
33 however not the case of a downsampling filter whose the number of sam‐
34 ples returned may vary from one call to another.
35
37 On platforms that support SIMD instructions, rtf_filter() is imple‐
38 mented in 2 different versions: one normal and one using SIMD instruc‐
39 tion set which performs nearly 4x faster than the normal one when pro‐
40 cessing float data types. The SIMD version is automatically selected at
41 runtime if the following conditions are met (otherwise, the implementa‐
42 tion falls back to the normal version):
43 - The input x and output y are aligned on 16 bytes boundary (128 bits)
45 - The sample strides (the size of the data type multiplied by the num‐
47 ber of channel) of the input and output are multiples of 16 bytes.
48 The first condition is easily met by allocating x and y using memory
50 allocation function mandating a certain alignment (for example,
51 posix_memalign(3) on POSIX platform).
52 The second condition is met if the number of channels is carefully cho‐
54 sen. Given the boost obtained with the SIMD version, it is often
55 interesting to add unused channels into the input and output (when pos‐
56 sible) just to make the strides multiple of 16 bytes (for example using
57 always a multiple of 4 channels when dealing with float and real val‐
58 ues).
59
61 rtf_create_filter(3), rtf_init_filter(3)
62EPFL 2010 RTF_FILTER(3)