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

source code of phonon/phonon/path.h