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.38 2009/02/10 13:06:47 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 tone_gen_tone_descriptor_s tone_gen_tone_descriptor_t;
00049 
00050 /*!
00051     Cadenced multi-tone generator descriptor.
00052 */
00053 typedef struct tone_gen_descriptor_s tone_gen_descriptor_t;
00054 
00055 /*!
00056     Cadenced multi-tone generator state descriptor. This defines the state of
00057     a single working instance of a generator.
00058 */
00059 typedef struct tone_gen_state_s tone_gen_state_t;
00060 
00061 #if defined(__cplusplus)
00062 extern "C"
00063 {
00064 #endif
00065 
00066 /*! Create a tone generator descriptor
00067     \brief Create a tone generator descriptor
00068     \param s The descriptor
00069     \param f1 The first frequency, in Hz
00070     \param l1 The level of the first frequency, in dBm0
00071     \param f2 0 for no second frequency, a positive number for the second frequency,
00072            in Hz, or a negative number for an AM modulation frequency, in Hz
00073     \param l2 The level of the second frequency, in dBm0, or the percentage modulation depth
00074            for an AM modulated tone.
00075     \param d1 x
00076     \param d2 x
00077     \param d3 x
00078     \param d4 x
00079     \param repeat x */
00080 SPAN_DECLARE(void) make_tone_gen_descriptor(tone_gen_descriptor_t *s,
00081                                             int f1,
00082                                             int l1,
00083                                             int f2,
00084                                             int l2,
00085                                             int d1,
00086                                             int d2,
00087                                             int d3,
00088                                             int d4,
00089                                             int repeat);
00090 
00091 SPAN_DECLARE(int) tone_gen(tone_gen_state_t *s, int16_t amp[], int max_samples);
00092 
00093 SPAN_DECLARE(tone_gen_state_t *) tone_gen_init(tone_gen_state_t *s, tone_gen_descriptor_t *t);
00094 
00095 SPAN_DECLARE(int) tone_gen_release(tone_gen_state_t *s);
00096 
00097 SPAN_DECLARE(int) tone_gen_free(tone_gen_state_t *s);
00098 
00099 #if defined(__cplusplus)
00100 }
00101 #endif
00102 
00103 #endif
00104 /*- End of file ------------------------------------------------------------*/

Generated on Tue Aug 4 03:36:11 2009 for spandsp by  doxygen 1.5.9