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 ------------------------------------------------------------*/