FIRFILTER - Construct an FIR filter

function gout=firfilter(name,M,varargin)
%FIRFILTER  Construct an FIR filter
%   Usage:  g=firfilter(name,M);
%           g=firfilter(name,M,...);
%
%   FIRFILTER(name,M) creates an FIR filter of length M. This is
%   exactly the same as calling FIRWIN. The name must be one of the
%   accepted window types of FIRWIN.
%
%   FIRFILTER(name,M,fc) constructs a filter with a centre
%   frequency of fc measured in normalized frequencies.
%
%   If one of the inputs is a vector, the output will be a cell array
%   with one entry in the cell array for each element in the vector. If
%   more input are vectors, they must have the same size and shape and the
%   the filters will be generated by stepping through the vectors. This
%   is a quick way to create filters for FILTERBANK and UFILTERBANK.
%
%   FIRFILTER accepts the following optional parameters:
%
%     'fs',fs     If the sampling frequency fs is specified then the length
%                 M is specified in seconds and the centre frequency
%                 fc in Hz.
%
%     'complex'   Make the filter complex valued if the centre frequency
%                 is non-zero. This is the default.
%
%     'real'      Make the filter real-valued if the centre frequency
%                 is non-zero.
%
%     'delay',d   Set the delay of the filter. Default value is zero.
%
%     'causal'    Create a causal filter starting at the first sample. If
%                 specified, this flag overwrites the delay setting.
%
%   It is possible to normalize the impulse response of the filter by
%   passing any of the flags from the SETNORM function. The default
%   normalization is 'energy'.
%
%   The filter can be used in the PFILT routine to filter a signal, or
%   in can be placed in a cell-array for use with FILTERBANK or UFILTERBANK.
%
%   See also: blfilter, firwin, pfilt, filterbank
%
%   Url: http://ltfat.github.io/doc/sigproc/firfilter.html

% Copyright (C) 2005-2023 Peter L. Soendergaard <peter@sonderport.dk> and others.
% This file is part of LTFAT version 2.6.0
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it 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 this program.  If not, see <http://www.gnu.org/licenses/>.

% XXX Implement passing additional parameters to firwin

% Define initial value for flags and key/value pairs.
definput.import={'setnorm'};
definput.importdefaults={'energy'};
definput.keyvals.delay=0;
definput.keyvals.fc=0;
definput.keyvals.fs=[];
definput.flags.delay={'delay','causal'};
definput.flags.real={'complex','real'};

[flags,kv]=ltfatarghelper({'fc'},definput,varargin);

[M,kv.fc,kv.delay]=scalardistribute(M,kv.fc,kv.delay);

if ~isempty(kv.fs)
    M=round(M*kv.fs);
    kv.fc=kv.fc/kv.fs*2;
end;

Nfilt=numel(M);
gout=cell(1,Nfilt);
for ii=1:Nfilt
    g=struct();
    
    if flags.do_causal
        g.offset=0;
        smallshift=0;
    else
        d=floor(kv.delay);
        smallshift=d-floor(d);
        g.offset=d-floor(M/2);
    end;

    g.h=fftshift(firwin(name,M(ii),'shift',smallshift(ii),flags.norm));
    g.fc=kv.fc(ii);
    g.realonly=flags.do_real;
    g.fs=kv.fs;
        
    gout{ii}=g;
end;
if Nfilt==1
    gout=g;
end;