GNU Radio 3.6.5 C++ API

atsci_equalizer.h

Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2002 Free Software Foundation, Inc.
00004  *
00005  * This file is part of GNU Radio
00006  *
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  *
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef _ATSC_EQUALIZER_H_
00024 #define _ATSC_EQUALIZER_H_
00025 
00026 #include <atsc_api.h>
00027 #include <atsci_syminfo.h>
00028 #include <vector>
00029 
00030 /*!
00031  * \brief abstract base class for ATSC equalizer
00032  */
00033 class ATSC_API atsci_equalizer {
00034 
00035 private:
00036 
00037   /*
00038    * have we seen a field sync since the last reset or problem?
00039    */
00040   bool  d_locked_p;
00041 
00042   /*
00043    * sample offset from the beginning of the last field sync we saw
00044    * to the beginning of our current input stream.  When we're locked
00045    * this will be in [0, 313*832] i.e., [0, 260416]
00046    */
00047   int   d_offset_from_last_field_sync;
00048 
00049   int   d_current_field;                // [0,1]
00050 
00051 
00052 public:
00053 
00054   // CREATORS
00055   atsci_equalizer ();
00056   virtual ~atsci_equalizer ();
00057 
00058   virtual std::vector<double> taps () {
00059     return std::vector<double>();
00060   }
00061 
00062   // MANIPULATORS
00063 
00064   /*!
00065    * \brief reset state (e.g., on channel change)
00066    *
00067    * Note, subclasses must invoke the superclass's method too!
00068    */
00069   virtual void reset ();
00070 
00071   /*!
00072    * \brief produce \p nsamples of output from given inputs and tags
00073    *
00074    * This is the main entry point.  It examines the input_tags
00075    * and local state and invokes the appropriate virtual function
00076    * to handle each sub-segment of the input data.
00077    *
00078    * \p input_samples must have (nsamples + ntaps() - 1) valid entries.
00079    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] are
00080    * referenced to compute the output values.
00081    *
00082    * \p input_tags must have nsamples valid entries.
00083    * input_tags[0] .. input_tags[nsamples - 1] are referenced to
00084    * compute the output values.
00085    */
00086   virtual void filter (const float         *input_samples,
00087                        const atsc::syminfo *input_tags,
00088                        float               *output_samples,
00089                        int                  nsamples);
00090 
00091   // ACCESSORS
00092 
00093   /*!
00094    * \brief how much history the input data stream requires.
00095    *
00096    * This must return a value >= 1.  Think of this as the number
00097    * of samples you need to look at to compute a single output sample.
00098    */
00099   virtual int ntaps () const = 0;
00100 
00101   /*!
00102    * \brief how many taps are "in the future".
00103    *
00104    * This allows us to handle what the ATSC folks call "pre-ghosts".
00105    * What it really does is allow the caller to jack with the offset
00106    * between the tags and the data so that everything magically works out.
00107    *
00108    * npretaps () must return a value between 0 and ntaps() - 1.
00109    *
00110    * If npretaps () returns 0, this means that the equalizer will only handle
00111    * multipath "in the past."  I suspect that a good value would be something
00112    * like 15% - 20% of ntaps ().
00113    */
00114   virtual int npretaps () const = 0;
00115 
00116 
00117 protected:
00118 
00119   /*!
00120    * Input range is known NOT TO CONTAIN data segment syncs
00121    * or field syncs.  This should be the fast path.  In the
00122    * non decicion directed case, this just runs the input
00123    * through the filter without adapting it.
00124    *
00125    * \p input_samples has (nsamples + ntaps() - 1) valid entries.
00126    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] may be
00127    * referenced to compute the output values.
00128    */
00129   virtual void filter_normal (const float *input_samples,
00130                               float *output_samples,
00131                               int   nsamples) = 0;
00132 
00133   /*!
00134    * Input range is known to consist of only a data segment sync or a
00135    * portion of a data segment sync.  \p nsamples will be in [1,4].
00136    * \p offset will be in [0,3].  \p offset is the offset of the input
00137    * from the beginning of the data segment sync pattern.
00138    *
00139    * \p input_samples has (nsamples + ntaps() - 1) valid entries.
00140    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] may be
00141    * referenced to compute the output values.
00142    */
00143   virtual void filter_data_seg_sync (const float *input_samples,
00144                                      float *output_samples,
00145                                      int   nsamples,
00146                                      int   offset) = 0;
00147 
00148   /*!
00149    * Input range is known to consist of only a field sync segment or a
00150    * portion of a field sync segment.  \p nsamples will be in [1,832].
00151    * \p offset will be in [0,831].  \p offset is the offset of the input
00152    * from the beginning of the data segment sync pattern.  We consider the
00153    * 4 symbols of the immediately preceding data segment sync to be the
00154    * first symbols of the field sync segment.  \p which_field is in [0,1]
00155    * and specifies which field (duh).
00156    *
00157    * \p input_samples has (nsamples + ntaps() - 1) valid entries.
00158    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] may be
00159    * referenced to compute the output values.
00160    */
00161   virtual void filter_field_sync (const float *input_samples,
00162                                   float *output_samples,
00163                                   int   nsamples,
00164                                   int   offset,
00165                                   int   which_field) = 0;
00166 };
00167 
00168 
00169 #endif /* _ATSC_EQUALIZER_H_ */