1/* This file is part of the KDE project
2 Copyright (C) 2006 Matthias Kretz <kretz@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), Nokia Corporation
10 (or its successors, if any) and the KDE Free Qt Foundation, which shall
11 act as a proxy defined in Section 6 of version 3 of the license.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library. If not, see <http://www.gnu.org/licenses/>.
20
21*/
22
23#ifndef PHONON_VOLUMEFADEREFFECT_H
24#define PHONON_VOLUMEFADEREFFECT_H
25
26#include "phonon_export.h"
27#include "effect.h"
28
29
30#ifndef QT_NO_PHONON_VOLUMEFADEREFFECT
31
32namespace Phonon
33{
34 class VolumeFaderEffectPrivate;
35
36 /** \class VolumeFaderEffect volumefadereffect.h phonon/VolumeFaderEffect
37 * Audio effect to gradually fade the audio volume.
38 *
39 * This effect differs from gradually changing the output volume in that
40 * a dedicated effect can change the volume in the smallest possible
41 * steps while every other volume control will make more or less
42 * noticeable steps.
43 *
44 * \ingroup PhononEffects
45 * \author Matthias Kretz <kretz@kde.org>
46 * \see AudioOutput::volume
47 */
48 class PHONON_EXPORT VolumeFaderEffect : public Effect
49 {
50 Q_OBJECT
51 P_DECLARE_PRIVATE(VolumeFaderEffect)
52 PHONON_HEIR(VolumeFaderEffect)
53 Q_ENUMS(FadeCurve)
54 /**
55 * This is the current volume of the output as voltage factor.
56 * Setting this property changes the volume immediately.
57 *
58 * 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
59 *
60 * \see volumeDecibel
61 */
62 Q_PROPERTY(float volume READ volume WRITE setVolume)
63 /**
64 * This is the current volume of the output in decibel.
65 * Setting this property changes the volume immediately.
66 *
67 * 0 dB means no change in volume, -6dB means an attenuation of the
68 * voltage to 50% and an attenuation of the power to 25%, -inf dB means
69 * silence.
70 *
71 * \see volume
72 */
73 Q_PROPERTY(double volumeDecibel READ volumeDecibel WRITE setVolumeDecibel)
74 /**
75 * This property holds the fade curve to be used for the fadeIn(), fadeOut()
76 * and fadeTo() slots.
77 *
78 * Defaults to Fade3Decibel.
79 *
80 * \see FadeCurve
81 */
82 Q_PROPERTY(FadeCurve fadeCurve READ fadeCurve WRITE setFadeCurve)
83 public:
84 /**
85 * Determines the curve of the volume change.
86 */
87 enum FadeCurve {
88 /**
89 * "Crossfade curve" / "fast" fade out
90 *
91 * Often the best fade for a crossfade, as after half of the
92 * time the volume reached -3dB. This means that half the
93 * possible power (which is proportional to the square of the
94 * voltage) is reached. Summed, the maximum power of two audio
95 * signals fading with a -3dB curve will always be equal.
96 *
97 * For fading in or out the -3dB curve is too abrupt in the end.
98 *
99 * This is the default fade curve.
100 */
101 Fade3Decibel,
102 /**
103 * "Linear" fade out
104 *
105 * With a -6dB fade curve after half of the fading time -6dB has
106 * been reached. -6dB is equal to half of the voltage meaning
107 * that the voltage multiplier changes linearly from the start
108 * of the fade to the end.
109 */
110 Fade6Decibel,
111 /**
112 * "slow" fade out
113 *
114 * After half of the fade time -9dB are reached. So the fade is
115 * fast in the beginning and slow in the end. This is a good
116 * fade for ending music.
117 */
118 Fade9Decibel,
119 /**
120 * more extreme version of the -9dB fade
121 */
122 Fade12Decibel
123 };
124
125 float volume() const;
126 double volumeDecibel() const;
127
128 FadeCurve fadeCurve() const;
129
130 public Q_SLOTS:
131 /**
132 * Tells the Fader to change the volume from the current volume to 100%
133 * in \p fadeTime milliseconds.
134 * Short for \c fadeTo(1.0, fadeTime).
135 *
136 * \param fadeTime the fade duration in milliseconds
137 *
138 * \see fadeTo
139 * \see volume
140 */
141 void fadeIn(int fadeTime);
142
143 /**
144 * Tells the Fader to change the volume from the current volume to 0%
145 * in \p fadeTime milliseconds.
146 * Short for \c fadeTo(0.0, fadeTime).
147 *
148 * \param fadeTime the fade duration in milliseconds
149 *
150 * \see fadeTo
151 */
152 void fadeOut(int fadeTime);
153
154 void setVolume(float volume);
155 void setVolumeDecibel(double volumeDecibel);
156
157 void setFadeCurve(FadeCurve curve);
158
159 /**
160 * Tells the Fader to change the volume from the current value to
161 * \p volume in \p fadeTime milliseconds
162 *
163 * \see fadeIn
164 * \see fadeOut
165 */
166 void fadeTo(float volume, int fadeTime);
167 };
168} //namespace Phonon
169
170#endif //QT_NO_PHONON_VOLUMEFADEREFFECT
171
172
173// vim: sw=4 ts=4 tw=80
174#endif // PHONON_VOLUMEFADEREFFECT_H
175

source code of phonon/phonon/volumefadereffect.h