.\"Copyright 2010 (c) EPFL
.TH RTF_CREATE_FILTER 3 2010 "EPFL" "rtfilter library"
.SH NAME
rtf_create_filter - Creates a custom filter
.SH SYNOPSIS
.LP
.B #include <rtfilter.h>
.sp
.BI "hfilter rtf_create_filter(unsigned int " nchann ", int " proctype ","
.br
.BI "                          unsigned int " num_len ", const void *" num ","
.br
.BI "                          unsigned int " denum_len ", const void *" denum ","
.br
.BI "                          int " type ");"
.br
.SH DESCRIPTION
.LP
This function creates and initializes a digital linear filter whose the
Z-transform is rational and processing \fInchann\fP channels of a data type
specified by \fIproctype\fP.
.LP
The numerator and denominator of the rational expression are specified by
respectively two arrays \fInum\fP and \fIdenum\fP containing the
coefficients in the ascending order of the 2 polynoms. The number of
elements in each arrays is controlled by \fInum_len\fP and \fdenum_len\fP.
\fIdenum_len\fP is allowed to be equal to zero as well as \fIdenum\fP is
allowed to be NULL. In such case, the denominator will be set to 1.
The data type of the values in \fInum\fP and \fIdenum\fP are specified by
\fItype\fP.
.LP
The \fIproctype\fP and \fItype\fP must be one the following constants:
.IP "" 3
\fBRTF_FLOAT\fP specifies real single precision (\fBfloat\fP)
.IP "" 3
\fBRTF_DOUBLE\fP specifies real double precision (\fBdouble\fP)
.IP "" 3
\fBRTF_CFLOAT\fP specifies complex single precision (\fBcomplex float\fP)
.IP "" 3
\fBRTF_CDOUBLE\fP specifies complex double precision (\fBcomplex double\fP)
.LP
The expected data type of the output of the filter has the same precision as
the one specified by \fIproctype\fP and is complex \fIproctype\fP or
\fItype\fP specifies a complex type. Said otherwise:
.IP " *" 3
If \fIproctype\fP is \fBRTF_FLOAT\fP or \fBRTF_CFLOAT\fP then the output
data type will have single precision. Otherwise it will have double
precision.
.IP " *" 3
If \fIproctype\fP or \fItype\fP specifies a complex type, then the output
will be complex as well. Otherwise, it will be real.
.LP
\fBrtf_create_filter\fP() can be used to use a filter that has been
designed somewhere else. In particular, this function can be used directly
with the output of filter design function of MATLAB. In such case, the usual
B and A arrays returned by the filter design functions corresponds exactly
to respectively \fInum\fP and \fIdenum\fP.
.SH "RETURN VALUE"
.LP
Returns the handle to the created filter in case of success, NULL otherwise.
.SH "PERFORMANCE CONSIDERATION"
See note of \fBrtf_filter\fP(3)
.SH "SEE ALSO"
.BR rtf_destroy_filter (3),
.BR rtf_init_filter (3),
.BR rtf_filter (3)