RTF_FILTER(3)

💖 RTF_FILTER(3) — the rtfilter library, bestie edition 💖

okay so welcome to the glow-up of rtf_filter, a lil function from the rtfilter library that literally just filters a chunk of data. yes. that's the whole job. and she does it flawlessly. 💅

---

✨ 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 🦋

So here's the tea, bestie: this function takes the filter that filt is pointing at, applies it to ns samples, and the samples live at the pointer x. Then all that filtered goodness gets written into the array that y points at. ✨

The arrays that x and y point at are made of values that correspond to the type that got specified back when the filter was created, okay? And important: those two arrays must NOT overlap. like, at all. if they do? undefined results. 😭 so don't do that. that's a vibe check you will fail.

Now the number of elements in each array has to be equal to ns multiplied by the number of channels being processed — and that channel count was also specified at the creation of the filter. and the arrays should be packed by channels, like this lil pattern right here:

|S1C1|S1C2|...|S1Ck|S2C1|S2C2|....|S2Ck|...|SnsCk|

where SiCj is the data value of the i-th sample and the j-th channel, and k is the number of channels specified at the creation of the filter. iykyk. 🎀

---

💜 RETURN VALUE 💜

She returns the number of samples that got written into the array pointed at by y. 💫

For most of the filters, this value will always be equal to ns. periodt. however — and this is the plot twist — that is not the case for a downsampling filter, whose number of samples returned may vary from one call to another. 🙈 so don't go assuming, bestie.

---

🔥 PERFORMANCE CONSIDERATION 🔥

okay this part is lowkey iconic. on platforms that support SIMD instructions, rtf_filter() is implemented in 2 different versions: one normal, and one that uses the SIMD instruction set. and the SIMD one performs nearly 4x faster than the normal one when it's processing float data types. FOUR TIMES. ate. 👑

The SIMD version gets automatically selected at runtime if these conditions are met — and if they're not, the implementation just falls back to the normal version, no drama:

• 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 a memory allocation function that mandates a certain alignment — for example, posix_memalign(3) on a POSIX platform. 🧚

The second condition is met if the number of channels is carefully chosen. and given the boost you get with the SIMD version, it's often interesting to add unused channels into the input and output (when possible) just to make the strides multiples of 16 bytes. like, for example, always using a multiple of 4 channels when you're dealing with float and real values. 🌈

ngl, that last tip is basically free real estate. add a couple ghost channels, get a 4x speedup, main character energy. 💅

---

🌟 SEE ALSO 🌟

• rtf_create_filter(3)
• rtf_init_filter(3)

---

and that's the whole page, bestie!! brought to you by the fine folks at EPFL, dated 2010, living in section 3 of the manual like the queen she is. go forth and filter. 💖✨🎀🦋🌸