mlib_SignalLMSFilterInit_F32S_F32S(3mlib)

1mlib_SignalLMSFilter(3MLIB)mediaLib Library Functionsmlib_SignalLMSFilter(3MLIB)
2
3
4

NAME

6       mlib_SignalLMSFilter, mlib_SignalLMSFilterInit_S16_S16, mlib_SignalLMS‐
7       FilterInit_S16S_S16S, mlib_SignalLMSFilterInit_F32_F32, mlib_SignalLMS‐
8       FilterInit_F32S_F32S, mlib_SignalLMSFilter_S16_S16_Sat, mlib_SignalLMS‐
9       Filter_S16S_S16S_Sat, mlib_SignalLMSFilter_F32_F32,  mlib_SignalLMSFil‐
10       ter_F32S_F32S,    mlib_SignalLMSFilterNonAdapt_S16_S16_Sat,   mlib_Sig‐
11       nalLMSFilterNonAdapt_S16S_S16S_Sat,            mlib_SignalLMSFilterNon‐
12       Adapt_F32_F32,  mlib_SignalLMSFilterNonAdapt_F32S_F32S, mlib_SignalLMS‐
13       FilterFree_S16_S16, mlib_SignalLMSFilterFree_S16S_S16S, mlib_SignalLMS‐
14       FilterFree_F32_F32,  mlib_SignalLMSFilterFree_F32S_F32S  -  least  mean
15       square (LMS) adaptive filtering
16

SYNOPSIS

18       cc [ flag... ] file... -lmlib [ library... ]
19       #include <mlib.h>
20
21       mlib_status mlib_SignalLMSFilterInit_S16_S16(void **filter,
22            const mlib_f32 *flt,
23            mlib_s32 tap, mlib_f32 beta);
24
25
26       mlib_status mlib_SignalLMSFilterInit_S16S_S16S(void **filter,
27            const mlib_f32 *flt,
28            mlib_s32 tap, mlib_f32 beta);
29
30
31       mlib_status mlib_SignalLMSFilterInit_F32_F32(void **filter,
32            const mlib_f32 *flt,
33            mlib_s32 tap, mlib_f32 beta);
34
35
36       mlib_status mlib_SignalLMSFilterInit_F32S_F32S(void **filter,
37            const mlib_f32 *flt,
38            mlib_s32 tap, mlib_f32 beta);
39
40
41       mlib_status mlib_SignalLMSFilter_S16_S16_Sat(mlib_s16 *dst,
42            const mlib_s16 *src,
43            const mlib_s16 *ref, void *filter, mlib_s32 n);
44
45
46       mlib_status mlib_SignalLMSFilter_S16S_S16S_Sat(mlib_s16 *dst,
47            const mlib_s16 *src,
48            const mlib_s16 *ref, void *filter, mlib_s32 n);
49
50
51       mlib_status mlib_SignalLMSFilter_F32_F32(mlib_f32 *dst,
52            const mlib_f32 *src,
53            const mlib_f32 *ref, void *filter, mlib_s32 n);
54
55
56       mlib_status mlib_SignalLMSFilter_F32S_F32S(mlib_f32 *dst,
57            const mlib_f32 *src,
58            const mlib_f32 *ref, void *filter, mlib_s32 n);
59
60
61       mlib_status mlib_SignalLMSFilterNonAdapt_S16_S16_Sat(mlib_s16 *dst,
62            const mlib_s16 *src, const mlib_s16 *ref,
63            void *filter, mlib_s32 n);
64
65
66       mlib_status mlib_SignalLMSFilterNonAdapt_S16S_S16S_Sat(mlib_s16 *dst,
67            const mlib_s16 *src, const mlib_s16 *ref,
68            void *filter, mlib_s32 n);
69
70
71       mlib_status mlib_SignalLMSFilterNonAdapt_F32_F32(mlib_f32 *dst,
72            const mlib_f32 *src, const mlib_f32 *ref,
73            void *filter, mlib_s32 n);
74
75
76       mlib_status mlib_SignalLMSFilterNonAdapt_F32S_F32S(mlib_f32 *dst,
77            const mlib_f32 *src, const mlib_f32 *ref,
78            void *filter, mlib_s32 n);
79
80
81       void mlib_SignalLMSFilterFree_S16_S16(void *filter);
82
83
84       void mlib_SignalLMSFilterFree_S16S_S16S(void *filter);
85
86
87       void mlib_SignalLMSFilterFree_F32_F32(void *filter);
88
89
90       void mlib_SignalLMSFilterFree_F32S_F32S(void *filter);
91
92

DESCRIPTION

94       The basic LMS adaptive algorithm is summarized as follows:
95
96           1.     Initialize the weights Wk(i), i = 0, 1, ..., tap - 1.
97
98           2.     Initialize previous source elements Xo(i), i =  0,  1,  ...,
99                  tap - 1.
100
101           3.     Read  Xk(t)  from src and Yk(t) from ref, t = 0, 1, ..., n -
102                  1.
103
104           4.     Compute filter output: nk = sum(Wk(i) * Xk(t - i)), i  =  0,
105                  1,  ...,  tap  -  1.  If i > t, use previous source elements
106                  stored in the Xo vector.
107
108           5.     Store filter output : dst[t] = nk.
109
110           6.     Compute the error estimate: Ek = Yk - nk.
111
112           7.     Compute factor BE0 = 2 * beta * Ek.
113
114           8.     Update filter weights: Wk(i) += BE0 * Xk(t - i), i =  0,  1,
115                  ...,  tap - 1. If i > t, use previous source elements stored
116                  in Xo vector.
117
118           9.     Next t, go to step 3.
119
120           10.    Store N ending source elements in previous  source  elements
121                  vector Xo: if N > n, N = n; else N = tap.
122
123
124       The functions assume that the input signal has a power maximum equal to
125       1. If it is not, beta should be divided by power maximum. Power maximum
126       is calculated according to the following formula:
127
128                              flt_len
129             Power_max = MAX {  SUM  signal(n + k)**2 }
130                          n     k=0
131
132
133
134       It  is necessary to consider the maximum of power maxima of both compo‐
135       nents as the stereo signal's power maximum.
136
137
138       Each of the FilterInit functions allocates memory for the internal fil‐
139       ter structure and converts the parameters into the internal representa‐
140       tion.
141
142
143       Each of the Filter functions applies the LMS  adaptive  filter  on  one
144       signal packet and updates the filter states.
145
146
147       Each  of the FilterNoAdapt functions applies the LMS filter on one sig‐
148       nal packet and updates the filter states but without changing the  fil‐
149       ter weights.
150
151
152       Each  of the FilterFree functions releases the memory allocated for the
153       internal filter structure.
154

PARAMETERS

156       Each of the functions takes some of the following arguments:
157
158       filter    Internal filter structure.
159
160
161       flt       Filter coefficient array.
162
163
164       tap       Taps of the filter.
165
166
167       beta      Error weighting factor. 0 < beta < 1.
168
169
170       dst       Destination signal array.
171
172
173       src       Source signal array.
174
175
176       ref       Reference or "desired" signal array.
177
178
179       n         Number of samples in the source signal array.
180
181

RETURN VALUES

183       Each of the FilterInit, Filter  and  FilterNonAdapt  functions  returns
184       MLIB_SUCCESS if successful. Otherwise it returns MLIB_FAILURE. The Fil‐
185       terFree functions don't return anything.
186

ATTRIBUTES

188       See attributes(5) for descriptions of the following attributes:
189
190
191
192
193       ┌─────────────────────────────┬─────────────────────────────┐
194       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
195       ├─────────────────────────────┼─────────────────────────────┤
196       │Interface Stability          │Committed                    │
197       ├─────────────────────────────┼─────────────────────────────┤
198       │MT-Level                     │MT-Safe                      │
199       └─────────────────────────────┴─────────────────────────────┘
200

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

ATTRIBUTES

SEE ALSO