1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
/* This file is part of the KDE project
Copyright (C) 2007 Matthias Kretz <kretz@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) version 3, or any
later version accepted by the membership of KDE e.V. (or its
successor approved by the membership of KDE e.V.), Nokia Corporation
(or its successors, if any) and the KDE Free Qt Foundation, which shall
act as a proxy defined in Section 6 of version 3 of the license.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef PHONON_PATH_H
#define PHONON_PATH_H
#include "phonon_export.h"
#include "objectdescription.h"
#include <QtCore/QExplicitlySharedDataPointer>
QT_BEGIN_HEADER
QT_BEGIN_NAMESPACE
template<class T> class QList;
namespace Phonon
{
class PathPrivate;
class Effect;
class MediaNode;
/** \class Path path.h Phonon/Path
* \short Connection object providing convenient effect insertion
*
* \code
MediaObject *media = new MediaObject;
AudioOutput *output = new AudioOutput(Phonon::MusicCategory);
Path path = Phonon::createPath(media, output);
Q_ASSERT(path.isValid()); // for this simple case the path should always be
//valid - there are unit tests to ensure it
// insert an effect
QList<EffectDescription> effectList = BackendCapabilities::availableAudioEffects();
if (!effectList.isEmpty()) {
Effect *effect = path.insertEffect(effectList.first());
}
* \endcode
* \ingroup Playback
* \ingroup Recording
* \author Matthias Kretz <kretz@kde.org>
* \author Thierry Bastian <thierry.bastian@trolltech.com>
*/
class PHONON_EXPORT Path
{
friend class FactoryPrivate;
public:
/**
* Destroys this reference to the Path. If the path was valid the connection is not broken
* as both the source and the sink MediaNodes still keep a reference to the Path.
*
* \see disconnect
*/
~Path();
/**
* Creates an invalid path.
*
* You can still make it a valid path by calling reconnect. To create a path you should use
* createPath, though.
*
* \see createPath
* \see isValid
*/
Path();
/**
* Constructs a copy of the given path.
*
* This constructor is fast thanks to explicit sharing.
*/
Path(const Path &);
/**
* Returns whether the path object connects two MediaNodes or not.
*
* \return \p true when the path connects two MediaNodes
* \return \p false when the path is disconnected
*/
bool isValid() const;
//MediaStreamTypes mediaStreamTypes() const;
#ifndef QT_NO_PHONON_EFFECT
/**
* Creates and inserts an effect into the path.
*
* You may insert effects of the same class as often as you like,
* but if you insert the same object, the call will fail.
*
* \param desc The EffectDescription object for the effect to be inserted.
*
* \param insertBefore If you already inserted an effect you can
* tell with this parameter in which order the data gets
* processed. If this is \c 0 the effect is appended at the end of
* the processing list. If the effect has not been inserted before
* the method will do nothing and return \c false.
*
* \return Returns a pointer to the effect object if it could be inserted
* at the specified position. If \c 0 is returned the effect was not
* inserted.
*
* \see removeEffect
* \see effects
*/
Effect *insertEffect(const EffectDescription &desc, Effect *insertBefore = 0);
/**
* Inserts an effect into the path.
*
* You may insert effects of the same class as often as you like,
* but if you insert the same object, the call will fail.
*
* \param newEffect An Effect object.
*
* \param insertBefore If you already inserted an effect you can
* tell with this parameter in which order the data gets
* processed. If this is \c 0 the effect is appended at the end of
* the processing list. If the effect has not been inserted before
* the method will do nothing and return \c false.
*
* \return Returns whether the effect could be inserted at the
* specified position. If \c false is returned the effect was not
* inserted.
*
* \see removeEffect
* \see effects
*/
bool insertEffect(Effect *newEffect, Effect *insertBefore = 0);
/**
* Removes an effect from the path.
*
* If the effect gets deleted while it is still connected the effect
* will be removed automatically.
*
* \param effect The effect to be removed.
*
* \return Returns whether the call was successful. If it returns
* \c false the effect could not be found in the path, meaning it
* has not been inserted before.
*
* \see insertEffect
* \see effects
*/
bool removeEffect(Effect *effect);
/**
* Returns a list of Effect objects that are currently
* used as effects. The order in the list determines the order the
* signal is sent through the effects.
*
* \return A list with all current effects.
*
* \see insertEffect
* \see removeEffect
*/
QList<Effect *> effects() const;
#endif //QT_NO_PHONON_EFFECT
/**
* Tries to change the MediaNodes the path is connected to.
*
* If reconnect fails the old connection is kept.
*/
bool reconnect(MediaNode *source, MediaNode *sink);
/**
* Disconnects the path from the MediaNodes it was connected to. This invalidates the path
* (isValid returns \p false then).
*/
bool disconnect();
/**
* Assigns \p p to this Path and returns a reference to this Path.
*
* This operation is fast thanks to explicit sharing.
*/
Path &operator=(const Path &p);
/**
* Returns \p true if this Path is equal to \p p; otherwise returns \p false;
*/
bool operator==(const Path &p) const;
/**
* Returns \p true if this Path is not equal to \p p; otherwise returns \p false;
*/
bool operator!=(const Path &p) const;
/**
* Returns the source MediaNode used by the path.
*/
MediaNode *source() const;
/**
* Returns the sink MediaNode used by the path.
*/
MediaNode *sink() const;
protected:
friend class PathPrivate;
QExplicitlySharedDataPointer<PathPrivate> d;
};
/**
* \relates Path
* Creates a new Path connecting two MediaNodes.
*
* The implementation will automatically select the right format and media type. E.g. connecting a
* MediaObject and AudioOutput will create a Path object connecting the audio. This might be
* represented as PCM or perhaps even AC3 depending on the AudioOutput object.
*
* \param source The MediaNode to connect an output from
* \param sink The MediaNode to connect to.
*/
PHONON_EXPORT Path createPath(MediaNode *source, MediaNode *sink);
} // namespace Phonon
QT_END_NAMESPACE
QT_END_HEADER
#endif // PHONON_PATH_H
|
