tone_generate.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * tone_generate.h - General telephony tone generation.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2001 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: tone_generate.h,v 1.33 2008/04/17 14:27:01 steveu Exp $
00026  */
00027 
00028 /*! \file */
00029 
00030 #if !defined(_SPANDSP_TONE_GENERATE_H_)
00031 #define _SPANDSP_TONE_GENERATE_H_
00032 
00033 /*! \page tone_generation_page Tone generation
00034 \section tone_generation_page_sec_1 What does it do?
00035 The tone generation module provides for the generation of cadenced tones,
00036 suitable for a wide range of telephony applications. 
00037 
00038 \section tone_generation_page_sec_2 How does it work?
00039 Oscillators are a problem. They oscillate due to instability, and yet we need
00040 them to behave in a stable manner. A look around the web will reveal many papers
00041 on this subject. Many describe rather complex solutions to the problem. However,
00042 we are only concerned with telephony applications. It is possible to generate
00043 the tones we need with a very simple efficient scheme. It is also practical to
00044 use an exhaustive test to prove the oscillator is stable under all the
00045 conditions in which we will use it. 
00046 */
00047 
00048 typedef struct
00049 {
00050     int32_t phase_rate;
00051     float gain;
00052 } tone_gen_tone_descriptor_t;
00053 
00054 /*!
00055     Cadenced dual tone generator descriptor.
00056 */
00057 typedef struct
00058 {
00059     tone_gen_tone_descriptor_t tone[4];
00060     int duration[4];
00061     int repeat;
00062 } tone_gen_descriptor_t;
00063 
00064 /*!
00065     Cadenced dual tone generator state descriptor. This defines the state of
00066     a single working instance of a generator.
00067 */
00068 typedef struct
00069 {
00070     tone_gen_tone_descriptor_t tone[4];
00071 
00072     uint32_t phase[4];
00073     int duration[4];
00074     int repeat;
00075 
00076     int current_section;
00077     int current_position;
00078 } tone_gen_state_t;
00079 
00080 #if defined(__cplusplus)
00081 extern "C"
00082 {
00083 #endif
00084 
00085 /*! Create a tone generator descriptor
00086     \brief Create a tone generator descriptor
00087     \param s The descriptor
00088     \param f1 The first frequency, in Hz
00089     \param l1 The level of the first frequency, in dBm0
00090     \param f2 0 for no second frequency, a positive number for the second frequency,
00091            in Hz, or a negative number for an AM modulation frequency, in Hz
00092     \param l2 The level of the second frequency, in dBm0, or the percentage modulation depth
00093            for an AM modulated tone.
00094     \param d1 x
00095     \param d2 x
00096     \param d3 x
00097     \param d4 x
00098     \param repeat x */
00099 void make_tone_gen_descriptor(tone_gen_descriptor_t *s,
00100                               int f1,
00101                               int l1,
00102                               int f2,
00103                               int l2,
00104                               int d1,
00105                               int d2,
00106                               int d3,
00107                               int d4,
00108                               int repeat);
00109 
00110 tone_gen_state_t *tone_gen_init(tone_gen_state_t *s, tone_gen_descriptor_t *t);
00111 
00112 int tone_gen(tone_gen_state_t *s, int16_t amp[], int max_samples);
00113 
00114 #if defined(__cplusplus)
00115 }
00116 #endif
00117 
00118 #endif
00119 /*- End of file ------------------------------------------------------------*/

Generated on Wed Jul 30 12:44:39 2008 for libspandsp by  doxygen 1.5.6