qccfilter.3

spiht for linux this is used to decod and encode vedio i wich all enjoy

.TH QCCFILTER 3 "QCCPACK" ""
.SH NAME
QccFilter \- generic data structure for FIR filtering of signals
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "int QccFilterInitialize(QccFilter *" filter );
.br
.BI "int QccFilterAlloc(QccFilter *" filter );
.br
.BI "void QccFilterFree(QccFilter *" filter );
.br
.BI "int QccFilterCopy(QccFilter *" filter1 ", const QccFilter *" filter2 );
.br
.BI "int QccFilterReversal(const QccFilter *" filter1 ", QccFilter *" filter2 );
.br
.BI "int QccFilterAlternateSignFlip(QccFilter *" filter );
.br
.BI int QccFilterRead(FILE *" infile ", QccFilter *" filter );
.br
.BI "int QccFilterWrite(FILE *" outfile ", const QccFilter *" filter );
.br
.BI "int QccFilterPrint(const QccFilter *" filter );
.SH DESCRIPTION
QccPack provides the
.B QccFilter
data structure to specify FIR filters for one-dimensional signals.
The
.B QccFilter
structure contains filter coefficients, as well as information on
the filters causality.  These coefficients then are used in 
routines like
.BR QccFilterVector (3)
and
.BR QccFilterMultiRateFilterVector (3)
to filter signals using time-domain convolution.
.SH "DATA STRUCTURE"
The
.B QccFilter
data structure is defined as:
.RS
.nf

typedef struct
{
  int causality;
  int length;
  QccVector coefficients;
} QccFilter;
.fi
.RE
.LP
The fields of
.B QccFilter
are as follows:
.TP
.I causality
The causality of the filter, that is, how the filter coefficients are
arranged with respect to the time-domain origin.  Possible values are
.BR QCCFILTER_CAUSAL ,
.BR QCCFILTER_ANTICAUSAL ,
.BR QCCFILTER_SYMMETRICWHOLE ,
and
.BR QCCFILTER_SYMMETRICHALF .
.BR
.TP
.I length
The number of coefficients in the filter.
.TP
.I coefficients
A vector of the filter coefficients.
.LP
Suppose that
.I length is
.IR N .
If
.I causality
is
.BR QCCFILTER_CAUSAL ,
then the coefficients,
.IR h[n] ,
of the
.RI length- N
causal FIR filter in
.I coefficients
are in the order:
.RS
.IR "h[0] h[1] h[2]" " ... " h[N-1]
.RE
If
.I causality
is
.BR QCCFILTER_ANTICAUSAL ,
then the coefficients,
.IR h[n] ,
of the
.RI length- N
anti-causal FIR filter in
.I coefficients
are in the order:
.RS
.IR "h[N-1] h[N-2]" " ... " "h[1] h[0]"
.RE
If
.I causality
is
.BR QCCFILTER_SYMMETRICWHOLE ,
then the coefficients,
.IR h[n] ,
of the
.RI length- (2N - 1)
whole-sample symmetric FIR filter in
.I coefficients
are in the order:
.RS
.IR "h[0] h[1] h[2]" " ... " h[N-1]
.RE
That is, only the right half of the filter coefficients are stored
for a whole-sample symmetric filter.
If
.I causality
is
.BR QCCFILTER_SYMMETRICHALF ,
then the coefficients,
.IR h[n] ,
of the
.RI length- 2N
half-sample symmetric FIR filter in
.I coefficients
are in the order:
.RS
.IR "h[0] h[1] h[2]" " ... " h[N-1]
.RE
That is, only the right half of the filter coefficients are stored
for a half-sample symmetric filter.
.SH "FILE FORMAT"
For reading and reading
.BR QccFilter
structures, QccPack uses the following file format.
The file is in ASCII with no magic number. The file consists of
the following information:
.RS
.sp
.I c
.br
.I d
.br
.I f0
.br
.I f1
.br
\|.
.br
\|.
.br
\|.
.br
.sp
.RE
where
.I c
is
.IR filter->causality ,
.I d
is
.IR filter->length ,
and the
.IR fi
are the filter coefficients,
.IR filter->coefficients .
.SH "ROUTINES"
.B QccFilterInitialize()
should be called before any use of a
.B QccFilter
structure.
.B QccFilterInitialize()
initializes the fields of
.I filter
to the following values:
.RS

.IR casuality :
.B QCCFILTER_CAUSAL
.br
.IR length :
0
.br
.IR coefficients :
.B NULL
.RE
.LP
.B QccFilterAlloc()
Alloctates storage space for the filters coefficients.
.IR filter -> length
must give a nonzero filter length.
The appropriate amount of storage space is allocated by calling
.BR QccVectorAlloc (3),
with a pointer to the vector returned as
.IR filter -> coefficients .
.LP
.B QccFilterFree()
frees space previously allocated by
.BR QccFilterAlloc() .
.LP
.B QccFilterCopy()
copies
.I filter2
to
.IR filter1 .
If
.I filter1
has not been allocated prior to calling
.B QccFilterCopy() 
(as is evidenced by a
.B NULL
.IR filter1 -> coefficients
pointer), then
.B QccFilterAlloc()
is called to allocate space for
.I filter1
with the same size as
.IR filter2 .
Otherwise
.RB (non- NULL
.IR filter1 -> coefficients
pointer), it is assumed that sufficient space as already been
allocated to
.IR filter1 .
.LP
.B QccFilterReversal()
creates the time reversal of
.IR filter2 ,
storing the resulting time-reversed filter in
.IR filter1 .
Sufficient storage space for the coefficients of
.I filter1
must be allocated prior to calling
.BR QccFilterReversal() .
For example, if
.I filter2 
is a
.RI length- N
causal filter,
.B QccFilterReversal()
produces a
.RI length- N
anti-causal filter, which is returned as
.IR filter1 .
.LP
.B QccFilterAlternateSignFlip()
changes the sign of every other coefficient in
.IR filter .
For example, if 
.I filter
is a
.RI length- N
.RI ( N
even) casual filter
.RS
.IR "h[0] h[1] h[2]" " ... " "h[N-3] h[N-2] h[n-1]" ,
.RE
then, after 
.B QccFilterAlternateSignFlip()
returns,
.I filter
is
.RS
.IR "-h[0] h[1] -h[2]" " ... " "h[N-3] -h[N-2] h[N-1]" .
.RE
.LP
.BR QccFilterRead()
reads the
.I filter
structure from the file pointed to by
.IR infile 
which must be already opened for reading via a call to
.IR QccFileOpen (3).
.LP
.BR QccFilterWrite()
writes the
.I filter
structure to the file pointed to by
.IR outfile 
which must be already opened for writing via a call to
.IR QccFileOpen (3).
.LP
.B QccFilterPrint()
prints a formated list of the filter coefficients of
.I filter
to stdout.
.SH "RETURN VALUE"
Each of these routines (except
.BR QccFilterFree() )
return 0 upon successful completion, 1 on error.
.SH "SEE ALSO"
.BR QccFilterVector (3),
.BR QccFilterMultiRateFilterVector (3),
.BR QccFilterMatrixSeparable (3),
.BR QccPack (3)
.SH AUTHOR
Copyright (C) 1997-2009  James E. Fowler
.\"  The programs herein are free software; you can redistribute them an.or
.\"  modify them under the terms of the GNU General Public License
.\"  as published by the Free Software Foundation; either version 2
.\"  of the License, or (at your option) any later version.
.\"  
.\"  These programs are distributed in the hope that they will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"  
.\"  You should have received a copy of the GNU General Public License
.\"  along with these programs; if not, write to the Free Software
.\"  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.