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