function inoutsig = setdbspl(inoutsig,lvl,varargin);
%SETDBSPL  Set level of signal in dB
%   Usage: outsig = setdbspl(insig,lvl);
%          outsig = setdbspl(insig,lvl,'ac');
%
%   `setdbspl(insig,lvl)` sets the SPL (sound pressure level) of the signal
%   insig to *lvl* dB, using the convention that a pure tone with an RMS value
%   of 1 corresponds to 100 dB SPL.
%
%   `setdbspl(lvl)` returns a scaling constant that will scale a signal
%   with RMS value of 1 to the correct level. 
%
%   If the input is a matrix, it is assumed that each column is a signal.
%
%   `setdbspl(insig,lvl,'ac')` does the same, but considers only the AC
%   component of the signal (i.e. the mean is removed).
%
%   References: moore2003introduction
  
%   See also: dbspl
  
%   Author: Peter L. Søndergaard, 2009

% ------ Checking of input parameters ---------

definput.flags.mean={'noac','ac'};
definput.keyvals.dboffset=100;
[flags,kv]=ltfatarghelper({'dboffset'},definput,varargin);

error(nargchk(1,5,nargin));

if ~isnumeric(inoutsig)
  error('%s: insig must be numeric.',upper(mfilename));
end;

% In the code below, "setdbspl" obtains the reference level from "dbspl"
% by calling "dbspl(1)", which will return only the offset measured in dB.

if nargin==1
  % Special mode, only the level has been given
  lvl=inoutsig;
  
  if ~isscalar(lvl) 
    error('%s: lvl must be a scalar.',upper(mfilename));
  end;

  inoutsig=gaindb(1,lvl-dbspl(1));
  return;
end;


if ~isnumeric(lvl) || ~isscalar(lvl) 
  error('%s: lvl must be a scalar.',upper(mfilename));
end;

% if (nargin<3) || (~ischar(options))
%   options='';
% end;


% ------ Computation --------------------------

if isvector(inoutsig)
  inoutsig = gaindb(inoutsig/rms(inoutsig,flags.mean),...
    lvl-dbspl(1,'dboffset',kv.dboffset));
else
  % If we have a matrix, set the level for every column.
  for ii=1:size(inoutsig,2);
    inoutsig(:,ii) = gaindb(inoutsig(:,ii)/rms(inoutsig(:,ii),flags.mean),...
      lvl-dbspl(1,'dboffset',kv.dboffset));
  end;
end;