juce/source/src/audio/dsp/juce_Decibels.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_DECIBELS_JUCEHEADER__
  27 #define __JUCE_DECIBELS_JUCEHEADER__
  28
  29 //==============================================================================
  30 /**
  31     This class contains some helpful static methods for dealing with decibel values.
  32 */
  33 class Decibels
  34 {
  35 public:
  36     //==============================================================================
  37     /** Converts a dBFS value to its equivalent gain level.
  38
  39         A gain of 1.0 = 0 dB, and lower gains map onto negative decibel values. Any
  40         decibel value lower than minusInfinityDb will return a gain of 0.
  41     */
  42     template <typename Type>
  43     static Type decibelsToGain (const Type decibels,
  44                                 const Type minusInfinityDb = (Type) defaultMinusInfinitydB)
  45     {
  46         return decibels > minusInfinityDb ? powf ((Type) 10.0, decibels * (Type) 0.05)
  47                                           : Type();
  48     }
  49
  50     /** Converts a gain level into a dBFS value.
  51
  52         A gain of 1.0 = 0 dB, and lower gains map onto negative decibel values.
  53         If the gain is 0 (or negative), then the method will return the value
  54         provided as minusInfinityDb.
  55     */
  56     template <typename Type>
  57     static Type gainToDecibels (const Type gain,
  58                                 const Type minusInfinityDb = (Type) defaultMinusInfinitydB)
  59     {
  60         return gain > Type() ? jmax (minusInfinityDb, (Type) std::log10 (gain) * (Type) 20.0)
  61                              : minusInfinityDb;
  62     }
  63
  64     //==============================================================================
  65     /** Converts a decibel reading to a string, with the 'dB' suffix.
  66         If the decibel value is lower than minusInfinityDb, the return value will
  67         be "-INF dB".
  68     */
  69     template <typename Type>
  70     static String toString (const Type decibels,
  71                             const int decimalPlaces = 2,
  72                             const Type minusInfinityDb = (Type) defaultMinusInfinitydB)
  73     {
  74         String s;
  75
  76         if (decibels <= minusInfinityDb)
  77         {
  78             s = "-INF dB";
  79         }
  80         else
  81         {
  82             if (decibels >= Type())
  83                 s << '+';
  84
  85             s << String (decibels, decimalPlaces) << " dB";
  86         }
  87
  88         return s;
  89     }
  90
  91
  92 private:
  93     //==============================================================================
  94     enum
  95     {
  96         defaultMinusInfinitydB = -100
  97     };
  98
  99     Decibels(); // This class can't be instantiated, it's just a holder for static methods..
 100     JUCE_DECLARE_NON_COPYABLE (Decibels);
 101 };
 102
 103
 104 #endif   // __JUCE_DECIBELS_JUCEHEADER__