File indexing completed on 2025-02-09 05:31:51
0001 /* This file is part of the KDE project 0002 Copyright (C) 2007 Matthias Kretz <kretz@kde.org> 0003 0004 This library is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Lesser General Public 0006 License as published by the Free Software Foundation; either 0007 version 2.1 of the License, or (at your option) version 3, or any 0008 later version accepted by the membership of KDE e.V. (or its 0009 successor approved by the membership of KDE e.V.), Nokia Corporation 0010 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0011 act as a proxy defined in Section 6 of version 3 of the license. 0012 0013 This library is distributed in the hope that it will be useful, 0014 but WITHOUT ANY WARRANTY; without even the implied warranty of 0015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0016 Lesser General Public License for more details. 0017 0018 You should have received a copy of the GNU Lesser General Public 0019 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0020 0021 */ 0022 0023 #ifndef PHONON_PATH_H 0024 #define PHONON_PATH_H 0025 0026 #include "phonon_export.h" 0027 #include "objectdescription.h" 0028 0029 #include <QExplicitlySharedDataPointer> 0030 0031 0032 template<class T> class QList; 0033 0034 namespace Phonon 0035 { 0036 0037 class PathPrivate; 0038 class Effect; 0039 class MediaNode; 0040 0041 /** \class Path path.h phonon/Path 0042 * \short Connection object providing convenient effect insertion 0043 * 0044 * \code 0045 MediaObject *media = new MediaObject; 0046 AudioOutput *output = new AudioOutput(Phonon::MusicCategory); 0047 Path path = Phonon::createPath(media, output); 0048 Q_ASSERT(path.isValid()); // for this simple case the path should always be 0049 //valid - there are unit tests to ensure it 0050 // insert an effect 0051 QList<EffectDescription> effectList = BackendCapabilities::availableAudioEffects(); 0052 if (!effectList.isEmpty()) { 0053 Effect *effect = path.insertEffect(effectList.first()); 0054 } 0055 * \endcode 0056 * \ingroup Playback 0057 * \ingroup Recording 0058 * \author Matthias Kretz <kretz@kde.org> 0059 * \author Thierry Bastian <thierry.bastian@trolltech.com> 0060 */ 0061 class PHONON_EXPORT Path 0062 { 0063 friend class FactoryPrivate; 0064 public: 0065 /** 0066 * Destroys this reference to the Path. If the path was valid the connection is not broken 0067 * as both the source and the sink MediaNodes still keep a reference to the Path. 0068 * 0069 * \see disconnect 0070 */ 0071 ~Path(); 0072 0073 /** 0074 * Creates an invalid path. 0075 * 0076 * You can still make it a valid path by calling reconnect. To create a path you should use 0077 * createPath, though. 0078 * 0079 * \see createPath 0080 * \see isValid 0081 */ 0082 Path(); 0083 0084 /** 0085 * Constructs a copy of the given path. 0086 * 0087 * This constructor is fast thanks to explicit sharing. 0088 */ 0089 Path(const Path &); 0090 0091 /** 0092 * Returns whether the path object connects two MediaNodes or not. 0093 * 0094 * \return \p true when the path connects two MediaNodes 0095 * \return \p false when the path is disconnected 0096 */ 0097 bool isValid() const; 0098 //MediaStreamTypes mediaStreamTypes() const; 0099 0100 #ifndef QT_NO_PHONON_EFFECT 0101 /** 0102 * Creates and inserts an effect into the path. 0103 * 0104 * You may insert effects of the same class as often as you like, 0105 * but if you insert the same object, the call will fail. 0106 * 0107 * \param desc The EffectDescription object for the effect to be inserted. 0108 * 0109 * \param insertBefore If you already inserted an effect you can 0110 * tell with this parameter in which order the data gets 0111 * processed. If this is \c 0 the effect is appended at the end of 0112 * the processing list. If the effect has not been inserted before 0113 * the method will do nothing and return \c false. 0114 * 0115 * \return Returns a pointer to the effect object if it could be inserted 0116 * at the specified position. If \c 0 is returned the effect was not 0117 * inserted. 0118 * 0119 * \see removeEffect 0120 * \see effects 0121 */ 0122 Effect *insertEffect(const EffectDescription &desc, Effect *insertBefore = nullptr); 0123 0124 /** 0125 * Inserts an effect into the path. 0126 * 0127 * You may insert effects of the same class as often as you like, 0128 * but if you insert the same object, the call will fail. 0129 * 0130 * \param newEffect An Effect object. 0131 * 0132 * \param insertBefore If you already inserted an effect you can 0133 * tell with this parameter in which order the data gets 0134 * processed. If this is \c 0 the effect is appended at the end of 0135 * the processing list. If the effect has not been inserted before 0136 * the method will do nothing and return \c false. 0137 * 0138 * \return Returns whether the effect could be inserted at the 0139 * specified position. If \c false is returned the effect was not 0140 * inserted. 0141 * 0142 * \see removeEffect 0143 * \see effects 0144 */ 0145 bool insertEffect(Effect *newEffect, Effect *insertBefore = nullptr); 0146 0147 /** 0148 * Removes an effect from the path. 0149 * 0150 * If the effect gets deleted while it is still connected the effect 0151 * will be removed automatically. 0152 * 0153 * \param effect The effect to be removed. 0154 * 0155 * \return Returns whether the call was successful. If it returns 0156 * \c false the effect could not be found in the path, meaning it 0157 * has not been inserted before. 0158 * 0159 * \see insertEffect 0160 * \see effects 0161 */ 0162 bool removeEffect(Effect *effect); 0163 0164 /** 0165 * Returns a list of Effect objects that are currently 0166 * used as effects. The order in the list determines the order the 0167 * signal is sent through the effects. 0168 * 0169 * \return A list with all current effects. 0170 * 0171 * \see insertEffect 0172 * \see removeEffect 0173 */ 0174 QList<Effect *> effects() const; 0175 #endif //QT_NO_PHONON_EFFECT 0176 0177 /** 0178 * Tries to change the MediaNodes the path is connected to. 0179 * 0180 * If reconnect fails the old connection is kept. 0181 */ 0182 bool reconnect(MediaNode *source, MediaNode *sink); 0183 0184 /** 0185 * Disconnects the path from the MediaNodes it was connected to. This invalidates the path 0186 * (isValid returns \p false then). 0187 */ 0188 bool disconnect(); 0189 0190 /** 0191 * Assigns \p p to this Path and returns a reference to this Path. 0192 * 0193 * This operation is fast thanks to explicit sharing. 0194 */ 0195 Path &operator=(const Path &p); 0196 0197 /** 0198 * Returns \p true if this Path is equal to \p p; otherwise returns \p false; 0199 */ 0200 bool operator==(const Path &p) const; 0201 0202 /** 0203 * Returns \p true if this Path is not equal to \p p; otherwise returns \p false; 0204 */ 0205 bool operator!=(const Path &p) const; 0206 0207 /** 0208 * Returns the source MediaNode used by the path. 0209 */ 0210 MediaNode *source() const; 0211 0212 /** 0213 * Returns the sink MediaNode used by the path. 0214 */ 0215 MediaNode *sink() const; 0216 0217 0218 protected: 0219 friend class PathPrivate; 0220 QExplicitlySharedDataPointer<PathPrivate> d; 0221 }; 0222 0223 /** 0224 * \relates Path 0225 * Creates a new Path connecting two MediaNodes. 0226 * 0227 * The implementation will automatically select the right format and media type. E.g. connecting a 0228 * MediaObject and AudioOutput will create a Path object connecting the audio. This might be 0229 * represented as PCM or perhaps even AC3 depending on the AudioOutput object. 0230 * 0231 * \param source The MediaNode to connect an output from 0232 * \param sink The MediaNode to connect to. 0233 */ 0234 PHONON_EXPORT Path createPath(MediaNode *source, MediaNode *sink); 0235 0236 } // namespace Phonon 0237 0238 0239 #endif // PHONON_PATH_H