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 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: power_meter.h,v 1.18 2009/02/10 13:06:47 steveu Exp $ 00026 */ 00027 00028 #if !defined(_POWER_METER_H_) 00029 #define _POWER_METER_H_ 00030 00031 /*! \page power_meter_page Power metering 00032 00033 \section power_meter_page_sec_1 What does it do? 00034 The power metering module implements a simple IIR type running power meter. The damping 00035 factor of the IIR is selectable when the meter instance is created. 00036 00037 Note that the definition of dBOv is quite vague in most places - is it peak since wave, 00038 peak square wave, etc.? This code is based on the well defined wording in RFC3389: 00039 00040 "For example, in the case of a u-law system, the reference would be a square wave with 00041 values +/-8031, and this square wave represents 0dBov. This translates into 6.18dBm0". 00042 00043 \section power_meter_page_sec_2 How does it work? 00044 */ 00045 00046 /*! 00047 Power meter descriptor. This defines the working state for a 00048 single instance of a power measurement device. 00049 */ 00050 typedef struct 00051 { 00052 /*! The shift factor, which controls the damping of the power meter. */ 00053 int shift; 00054 00055 /*! The current power reading. */ 00056 int32_t reading; 00057 } power_meter_t; 00058 00059 #if defined(__cplusplus) 00060 extern "C" 00061 { 00062 #endif 00063 00064 /*! Initialise a power meter context. 00065 \brief Initialise a power meter context. 00066 \param s The power meter context. 00067 \param shift The shift to be used by the IIR filter. 00068 \return The power meter context. */ 00069 SPAN_DECLARE(power_meter_t *) power_meter_init(power_meter_t *s, int shift); 00070 00071 SPAN_DECLARE(int) power_meter_release(power_meter_t *s); 00072 00073 SPAN_DECLARE(int) power_meter_free(power_meter_t *s); 00074 00075 /*! Change the damping factor of a power meter context. 00076 \brief Change the damping factor of a power meter context. 00077 \param s The power meter context. 00078 \param shift The new shift to be used by the IIR filter. 00079 \return The power meter context. */ 00080 SPAN_DECLARE(power_meter_t *) power_meter_damping(power_meter_t *s, int shift); 00081 00082 /*! Update a power meter. 00083 \brief Update a power meter. 00084 \param s The power meter context. 00085 \param amp The amplitude of the new audio sample. 00086 \return The current power meter reading. */ 00087 SPAN_DECLARE(int32_t) power_meter_update(power_meter_t *s, int16_t amp); 00088 00089 /*! Get the current power meter reading. 00090 \brief Get the current power meter reading. 00091 \param s The power meter context. 00092 \return The current power meter reading. */ 00093 SPAN_DECLARE(int32_t) power_meter_current(power_meter_t *s); 00094 00095 /*! Get the current power meter reading, in dBm0. 00096 \brief Get the current power meter reading, in dBm0. 00097 \param s The power meter context. 00098 \return The current power meter reading, in dBm0. */ 00099 SPAN_DECLARE(float) power_meter_current_dbm0(power_meter_t *s); 00100 00101 /*! Get the current power meter reading, in dBOv. 00102 \brief Get the current power meter reading, in dBOv. 00103 \param s The power meter context. 00104 \return The current power meter reading, in dBOv. */ 00105 SPAN_DECLARE(float) power_meter_current_dbov(power_meter_t *s); 00106 00107 /*! Get the power meter reading which represents a specified power level in dBm0. 00108 \brief Get the current power meter reading, in dBm0. 00109 \param level A power level, in dB0m. 00110 \return The equivalent power meter reading. */ 00111 SPAN_DECLARE(int32_t) power_meter_level_dbm0(float level); 00112 00113 /*! Get the power meter reading which represents a specified power level in dBOv. 00114 \brief Get the current power meter reading, in dBOv. 00115 \param level A power level, in dBOv. 00116 \return The equivalent power meter reading. */ 00117 SPAN_DECLARE(int32_t) power_meter_level_dbov(float level); 00118 00119 #if defined(__cplusplus) 00120 } 00121 #endif 00122 00123 #endif 00124 /*- End of file ------------------------------------------------------------*/