power_meter.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * power_meter.h
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 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 General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: power_meter.h,v 1.6 2005/11/24 13:04:52 steveu Exp $
00027  */
00028 
00029 #if !defined(_POWER_METER_H_)
00030 #define _POWER_METER_H_
00031 
00032 /*! \page power_meter_page Power metering
00033 
00034 \section power_meter_page_sec_1 What does it do?
00035 The power metering module implements a simple IIR type running power meter. The damping
00036 factor of the IIR is selectable when the meter instance is created.
00037 
00038 Note that the definition of dBOv is quite vague in most places - is it peak since wave,
00039 peak square wave, etc.? This code is based on the well defined wording in RFC3389:
00040 
00041 "For example, in the case of a u-law system, the reference would be a square wave with
00042 values +/-8031, and this square wave represents 0dBov.  This translates into 6.18dBm0".
00043 
00044 \section power_meter_page_sec_2 How does it work?
00045 */
00046 
00047 /*!
00048     Power meter descriptor. This defines the working state for a
00049     single instance of a power measurement device.
00050 */
00051 typedef struct
00052 {
00053     int shift;
00054 
00055     int32_t reading;
00056 } power_meter_t;
00057 
00058 #ifdef __cplusplus
00059 extern "C" {
00060 #endif
00061 
00062 /*! Initialise a power meter context.
00063     \brief Initialise a power meter context.
00064     \param s The power meter context.
00065     \param shift The shift to be used by the IIR filter.
00066     \return The power meter context. */
00067 power_meter_t *power_meter_init(power_meter_t *s, int shift);
00068 
00069 /*! Change the damping factor of a power meter context.
00070     \brief Change the damping factor of a power meter context.
00071     \param s The power meter context.
00072     \param shift The new shift to be used by the IIR filter.
00073     \return The power meter context. */
00074 power_meter_t *power_meter_damping(power_meter_t *s, int shift);
00075 
00076 /*! Update a power meter.
00077     \brief Update a power meter.
00078     \param s The power meter context.
00079     \param amp The amplitude of the new audio sample.
00080     \return The current power meter reading. */
00081 int32_t power_meter_update(power_meter_t *s, int16_t amp);
00082 
00083 /*! Get the current power meter reading, in dBm0.
00084     \brief Get the current power meter reading, in dBm0.
00085     \param s The power meter context.
00086     \return The current power meter reading, in dBm0. */
00087 float power_meter_dbm0(power_meter_t *s);
00088 
00089 /*! Get the current power meter reading, in dBOv.
00090     \brief Get the current power meter reading, in dBOv.
00091     \param s The power meter context.
00092     \return The current power meter reading, in dBOv. */
00093 float power_meter_dbov(power_meter_t *s);
00094 
00095 /*! Get the power meter reading which represents a specified power level in dBm0.
00096     \brief Get the current power meter reading, in dBm0.
00097     \param level A power level, in dB0m.
00098     \return The equivalent power meter reading. */
00099 int32_t power_meter_level_dbm0(float level);
00100 
00101 /*! Get the power meter reading which represents a specified power level in dBOv.
00102     \brief Get the current power meter reading, in dBOv.
00103     \param level A power level, in dBOv.
00104     \return The equivalent power meter reading. */
00105 int32_t power_meter_level_dbov(float level);
00106 
00107 #ifdef __cplusplus
00108 }
00109 #endif
00110 
00111 #endif
00112 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1