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 
00026 /*! \file */
00027 
00028 #if !defined(_SPANDSP_TONE_GENERATE_H_)
00029 #define _SPANDSP_TONE_GENERATE_H_
00030 
00031 /*! \page tone_generation_page Tone generation
00032 \section tone_generation_page_sec_1 What does it do?
00033 The tone generation module provides for the generation of cadenced tones,
00034 suitable for a wide range of telephony applications. 
00035 
00036 \section tone_generation_page_sec_2 How does it work?
00037 Oscillators are a problem. They oscillate due to instability, and yet we need
00038 them to behave in a stable manner. A look around the web will reveal many papers
00039 on this subject. Many describe rather complex solutions to the problem. However,
00040 we are only concerned with telephony applications. It is possible to generate
00041 the tones we need with a very simple efficient scheme. It is also practical to
00042 use an exhaustive test to prove the oscillator is stable under all the
00043 conditions in which we will use it. 
00044 */
00045 
00046 typedef struct tone_gen_tone_descriptor_s tone_gen_tone_descriptor_t;
00047 
00048 /*!
00049     Cadenced multi-tone generator descriptor.
00050 */
00051 typedef struct tone_gen_descriptor_s tone_gen_descriptor_t;
00052 
00053 /*!
00054     Cadenced multi-tone generator state descriptor. This defines the state of
00055     a single working instance of a generator.
00056 */
00057 typedef struct tone_gen_state_s tone_gen_state_t;
00058 
00059 #if defined(__cplusplus)
00060 extern "C"
00061 {
00062 #endif
00063 
00064 /*! Create a tone generator descriptor
00065     \brief Create a tone generator descriptor
00066     \param s The descriptor
00067     \param f1 The first frequency, in Hz
00068     \param l1 The level of the first frequency, in dBm0
00069     \param f2 0 for no second frequency, a positive number for the second frequency,
00070            in Hz, or a negative number for an AM modulation frequency, in Hz
00071     \param l2 The level of the second frequency, in dBm0, or the percentage modulation depth
00072            for an AM modulated tone.
00073     \param d1 x
00074     \param d2 x
00075     \param d3 x
00076     \param d4 x
00077     \param repeat x */
00078 SPAN_DECLARE(tone_gen_descriptor_t *) tone_gen_descriptor_init(tone_gen_descriptor_t *s,
00079                                                                int f1,
00080                                                                int l1,
00081                                                                int f2,
00082                                                                int l2,
00083                                                                int d1,
00084                                                                int d2,
00085                                                                int d3,
00086                                                                int d4,
00087                                                                int repeat);
00088 
00089 /* For backwards compatibility */
00090 #define make_tone_gen_descriptor    tone_gen_descriptor_init
00091 
00092 SPAN_DECLARE(void) tone_gen_descriptor_free(tone_gen_descriptor_t *s);
00093 
00094 SPAN_DECLARE_NONSTD(int) tone_gen(tone_gen_state_t *s, int16_t amp[], int max_samples);
00095 
00096 SPAN_DECLARE(tone_gen_state_t *) tone_gen_init(tone_gen_state_t *s, tone_gen_descriptor_t *t);
00097 
00098 SPAN_DECLARE(int) tone_gen_release(tone_gen_state_t *s);
00099 
00100 SPAN_DECLARE(int) tone_gen_free(tone_gen_state_t *s);
00101 
00102 #if defined(__cplusplus)
00103 }
00104 #endif
00105 
00106 #endif
00107 /*- End of file ------------------------------------------------------------*/

Generated on Thu Oct 18 15:29:15 2012 for spandsp by  doxygen 1.4.7