source/modules/juce_audio_basics/utilities/juce_Decibels.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    The code included in this file is provided under the terms of the ISC license
  11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  12    To use, copy, modify, and/or distribute this software for any purpose with or
  13    without fee is hereby granted provided that the above copyright notice and
  14    this permission notice appear in all copies.
  15
  16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  18    DISCLAIMED.
  19
  20   ==============================================================================
  21 */
  22
  23 namespace juce
  24 {
  25
  26 //==============================================================================
  27 /**
  28     This class contains some helpful static methods for dealing with decibel values.
  29
  30     @tags{Audio}
  31 */
  32 class Decibels
  33 {
  34 public:
  35     //==============================================================================
  36     /** Converts a dBFS value to its equivalent gain level.
  37
  38         A gain of 1.0 = 0 dB, and lower gains map onto negative decibel values. Any
  39         decibel value lower than minusInfinityDb will return a gain of 0.
  40     */
  41     template <typename Type>
  42     static Type decibelsToGain (Type decibels,
  43                                 Type minusInfinityDb = Type (defaultMinusInfinitydB))
  44     {
  45         return decibels > minusInfinityDb ? std::pow (Type (10.0), decibels * Type (0.05))
  46                                           : Type();
  47     }
  48
  49     /** Converts a gain level into a dBFS value.
  50
  51         A gain of 1.0 = 0 dB, and lower gains map onto negative decibel values.
  52         If the gain is 0 (or negative), then the method will return the value
  53         provided as minusInfinityDb.
  54     */
  55     template <typename Type>
  56     static Type gainToDecibels (Type gain,
  57                                 Type minusInfinityDb = Type (defaultMinusInfinitydB))
  58     {
  59         return gain > Type() ? jmax (minusInfinityDb, static_cast<Type> (std::log10 (gain)) * Type (20.0))
  60                              : minusInfinityDb;
  61     }
  62
  63     //==============================================================================
  64     /** Converts a decibel reading to a string.
  65
  66         By default the returned string will have the 'dB' suffix added, but this can be removed by
  67         setting the shouldIncludeSuffix argument to false. If a customMinusInfinityString argument
  68         is provided this will be returned if the value is lower than minusInfinityDb, otherwise
  69         the return value will be "-INF".
  70     */
  71     template <typename Type>
  72     static String toString (Type decibels,
  73                             int decimalPlaces = 2,
  74                             Type minusInfinityDb = Type (defaultMinusInfinitydB),
  75                             bool shouldIncludeSuffix = true,
  76                             StringRef customMinusInfinityString = {})
  77     {
  78         String s;
  79         s.preallocateBytes (20);
  80
  81         if (decibels <= minusInfinityDb)
  82         {
  83             if (customMinusInfinityString.isEmpty())
  84                 s << "-INF";
  85             else
  86                 s << customMinusInfinityString;
  87         }
  88         else
  89         {
  90             if (decibels >= Type())
  91                 s << '+';
  92
  93             if (decimalPlaces <= 0)
  94                 s << roundToInt (decibels);
  95             else
  96                 s << String (decibels, decimalPlaces);
  97         }
  98
  99         if (shouldIncludeSuffix)
 100             s << " dB";
 101
 102         return s;
 103     }
 104
 105 private:
 106     //==============================================================================
 107     enum { defaultMinusInfinitydB = -100 };
 108
 109     Decibels() = delete; // This class can't be instantiated, it's just a holder for static methods..
 110 };
 111
 112 } // namespace juce