git.gag.com Git - debian/gnuradio/blob - gr-atsc/src/lib/atsci_equalizer.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2002 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   7  * GNU Radio is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2, or (at your option)
  10  * any later version.
  11  *
  12  * GNU Radio is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with GNU Radio; see the file COPYING.  If not, write to
  19  * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef _ATSC_EQUALIZER_H_
  24 #define _ATSC_EQUALIZER_H_
  25
  26 #include <atsci_syminfo.h>
  27
  28 /*!
  29  * \brief abstract base class for ATSC equalizer
  30  */
  31 class atsci_equalizer {
  32
  33 private:
  34
  35   /*
  36    * have we seen a field sync since the last reset or problem?
  37    */
  38   bool  d_locked_p;
  39
  40   /*
  41    * sample offset from the beginning of the last field sync we saw
  42    * to the beginning of our current input stream.  When we're locked
  43    * this will be in [0, 313*832] i.e., [0, 260416]
  44    */
  45   int   d_offset_from_last_field_sync;
  46
  47   int   d_current_field;                // [0,1]
  48
  49
  50 public:
  51
  52   // CREATORS
  53   atsci_equalizer ();
  54   virtual ~atsci_equalizer ();
  55
  56   // MANIPULATORS
  57
  58   /*!
  59    * \brief reset state (e.g., on channel change)
  60    *
  61    * Note, subclasses must invoke the superclass's method too!
  62    */
  63   virtual void reset ();
  64
  65   /*!
  66    * \brief produce \p nsamples of output from given inputs and tags
  67    *
  68    * This is the main entry point.  It examines the input_tags
  69    * and local state and invokes the appropriate virtual function
  70    * to handle each sub-segment of the input data.
  71    *
  72    * \p input_samples must have (nsamples + ntaps() - 1) valid entries.
  73    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] are
  74    * referenced to compute the output values.
  75    *
  76    * \p input_tags must have nsamples valid entries.
  77    * input_tags[0] .. input_tags[nsamples - 1] are referenced to
  78    * compute the output values.
  79    */
  80   virtual void filter (const float         *input_samples,
  81                        const atsc::syminfo *input_tags,
  82                        float               *output_samples,
  83                        int                  nsamples);
  84
  85   // ACCESSORS
  86
  87   /*!
  88    * \brief how much history the input data stream requires.
  89    *
  90    * This must return a value >= 1.  Think of this as the number
  91    * of samples you need to look at to compute a single output sample.
  92    */
  93   virtual int ntaps () const = 0;
  94
  95   /*!
  96    * \brief how many taps are "in the future".
  97    *
  98    * This allows us to handle what the ATSC folks call "pre-ghosts".
  99    * What it really does is allow the caller to jack with the offset
 100    * between the tags and the data so that everything magically works out.
 101    *
 102    * npretaps () must return a value between 0 and ntaps() - 1.
 103    *
 104    * If npretaps () returns 0, this means that the equalizer will only handle
 105    * multipath "in the past."  I suspect that a good value would be something
 106    * like 15% - 20% of ntaps ().
 107    */
 108   virtual int npretaps () const = 0;
 109
 110
 111 protected:
 112
 113   /*!
 114    * Input range is known NOT TO CONTAIN data segment syncs
 115    * or field syncs.  This should be the fast path.  In the
 116    * non decicion directed case, this just runs the input
 117    * through the filter without adapting it.
 118    *
 119    * \p input_samples has (nsamples + ntaps() - 1) valid entries.
 120    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] may be
 121    * referenced to compute the output values.
 122    */
 123   virtual void filter_normal (const float *input_samples,
 124                               float *output_samples,
 125                               int   nsamples) = 0;
 126
 127   /*!
 128    * Input range is known to consist of only a data segment sync or a
 129    * portion of a data segment sync.  \p nsamples will be in [1,4].
 130    * \p offset will be in [0,3].  \p offset is the offset of the input
 131    * from the beginning of the data segment sync pattern.
 132    *
 133    * \p input_samples has (nsamples + ntaps() - 1) valid entries.
 134    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] may be
 135    * referenced to compute the output values.
 136    */
 137   virtual void filter_data_seg_sync (const float *input_samples,
 138                                      float *output_samples,
 139                                      int   nsamples,
 140                                      int   offset) = 0;
 141
 142   /*!
 143    * Input range is known to consist of only a field sync segment or a
 144    * portion of a field sync segment.  \p nsamples will be in [1,832].
 145    * \p offset will be in [0,831].  \p offset is the offset of the input
 146    * from the beginning of the data segment sync pattern.  We consider the
 147    * 4 symbols of the immediately preceding data segment sync to be the
 148    * first symbols of the field sync segment.  \p which_field is in [0,1]
 149    * and specifies which field (duh).
 150    *
 151    * \p input_samples has (nsamples + ntaps() - 1) valid entries.
 152    * input_samples[0] .. input_samples[nsamples - 1 + ntaps() - 1] may be
 153    * referenced to compute the output values.
 154    */
 155   virtual void filter_field_sync (const float *input_samples,
 156                                   float *output_samples,
 157                                   int   nsamples,
 158                                   int   offset,
 159                                   int   which_field) = 0;
 160 };
 161
 162
 163 #endif /* _ATSC_EQUALIZER_H_ */