Chris@150: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ Chris@150: Chris@150: /* Chris@150: Sonic Visualiser Chris@150: An audio file viewer and annotation editor. Chris@150: Centre for Digital Music, Queen Mary, University of London. Chris@150: This file copyright 2006 Chris Cannam. Chris@150: Chris@150: This program is free software; you can redistribute it and/or Chris@150: modify it under the terms of the GNU General Public License as Chris@150: published by the Free Software Foundation; either version 2 of the Chris@150: License, or (at your option) any later version. See the file Chris@150: COPYING included with this distribution for more information. Chris@150: */ Chris@150: Chris@150: #ifndef _MODEL_H_ Chris@150: #define _MODEL_H_ Chris@150: Chris@150: #include Chris@150: #include Chris@150: Chris@150: #include "base/XmlExportable.h" Chris@391: #include "base/Playable.h" Chris@150: Chris@290: typedef std::vector SampleBlock; Chris@290: Chris@179: class ZoomConstraint; Chris@319: class AlignmentModel; Chris@179: Chris@150: /** Chris@150: * Model is the base class for all data models that represent any sort Chris@150: * of data on a time scale based on an audio frame rate. Chris@150: */ Chris@150: Chris@179: class Model : public QObject, Chris@391: public XmlExportable, Chris@391: public Playable Chris@150: { Chris@150: Q_OBJECT Chris@150: Chris@150: public: Chris@150: virtual ~Model(); Chris@150: Chris@150: /** Chris@150: * Return true if the model was constructed successfully. Classes Chris@150: * that refer to the model should always test this before use. Chris@150: */ Chris@150: virtual bool isOK() const = 0; Chris@150: Chris@150: /** Chris@150: * Return the first audio frame spanned by the model. Chris@150: */ Chris@929: virtual int getStartFrame() const = 0; Chris@150: Chris@150: /** Chris@150: * Return the last audio frame spanned by the model. Chris@150: */ Chris@929: virtual int getEndFrame() const = 0; Chris@150: Chris@150: /** Chris@150: * Return the frame rate in frames per second. Chris@150: */ Chris@929: virtual int getSampleRate() const = 0; Chris@150: Chris@150: /** Chris@297: * Return the frame rate of the underlying material, if the model Chris@297: * itself has already been resampled. Chris@297: */ Chris@929: virtual int getNativeRate() const { return getSampleRate(); } Chris@297: Chris@297: /** Chris@333: * Return the "work title" of the model, if known. Chris@333: */ Chris@333: virtual QString getTitle() const; Chris@333: Chris@333: /** Chris@333: * Return the "artist" or "maker" of the model, if known. Chris@333: */ Chris@333: virtual QString getMaker() const; Chris@333: Chris@333: /** Chris@345: * Return the location of the data in this model (e.g. source Chris@345: * URL). This should not normally be returned for editable models Chris@345: * that have been edited. Chris@345: */ Chris@345: virtual QString getLocation() const; Chris@345: Chris@345: /** Chris@345: * Return the type of the model. For display purposes only. Chris@345: */ Chris@345: virtual QString getTypeName() const = 0; Chris@345: Chris@345: /** Chris@150: * Return a copy of this model. Chris@150: * Chris@150: * If the model is not editable, this may be effectively a shallow Chris@150: * copy. If the model is editable, however, this operation must Chris@150: * properly copy all of the model's editable data. Chris@150: * Chris@150: * In general this operation is not useful for non-editable dense Chris@150: * models such as waveforms, because there may be no efficient Chris@150: * copy operation implemented -- for such models it is better not Chris@150: * to copy at all. Chris@150: * Chris@150: * Caller owns the returned value. Chris@150: */ Chris@150: virtual Model *clone() const = 0; Chris@923: Chris@923: /** Chris@923: * Mark the model as abandoning. This means that the application Chris@923: * no longer needs it, so it can stop doing any background Chris@923: * calculations it may be involved in. Note that as far as the Chris@923: * model API is concerned, this does nothing more than tell the Chris@923: * model to return true from isAbandoning(). The actual response Chris@923: * to this will depend on the model's context -- it's possible Chris@923: * nothing at all will change. Chris@923: */ Chris@923: virtual void abandon() { Chris@923: m_abandoning = true; Chris@923: } Chris@923: Chris@923: /** Chris@923: * Query whether the model has been marked as abandoning. Chris@923: */ Chris@923: virtual bool isAbandoning() const { Chris@923: return m_abandoning; Chris@923: } Chris@923: Chris@150: /** Chris@150: * Return true if the model has finished loading or calculating Chris@150: * all its data, for a model that is capable of calculating in a Chris@150: * background thread. The default implementation is appropriate Chris@150: * for a thread that does not background any work but carries out Chris@150: * all its calculation from the constructor or accessors. Chris@150: * Chris@150: * If "completion" is non-NULL, this function should return Chris@150: * through it an estimated percentage value showing how far Chris@150: * through the background operation it thinks it is (for progress Chris@150: * reporting). If it has no way to calculate progress, it may Chris@150: * return the special value COMPLETION_UNKNOWN. Chris@150: */ Chris@150: virtual bool isReady(int *completion = 0) const { Chris@150: bool ok = isOK(); Chris@150: if (completion) *completion = (ok ? 100 : 0); Chris@150: return ok; Chris@150: } Chris@150: static const int COMPLETION_UNKNOWN; Chris@150: Chris@179: /** Chris@179: * If this model imposes a zoom constraint, i.e. some limit to the Chris@179: * set of resolutions at which its data can meaningfully be Chris@179: * displayed, then return it. Chris@179: */ Chris@179: virtual const ZoomConstraint *getZoomConstraint() const { Chris@179: return 0; Chris@179: } Chris@179: Chris@297: /** Chris@297: * If this model was derived from another, return the model it was Chris@297: * derived from. The assumption is that the source model's Chris@297: * alignment will also apply to this model, unless some other Chris@319: * property (such as a specific alignment model set on this model) Chris@319: * indicates otherwise. Chris@297: */ Chris@297: virtual Model *getSourceModel() const { Chris@297: return m_sourceModel; Chris@297: } Chris@297: Chris@297: /** Chris@297: * Set the source model for this model. Chris@297: */ Chris@319: virtual void setSourceModel(Model *model); Chris@319: Chris@319: /** Chris@319: * Specify an aligment between this model's timeline and that of a Chris@319: * reference model. The alignment model records both the Chris@319: * reference and the alignment. This model takes ownership of the Chris@319: * alignment model. Chris@319: */ Chris@319: virtual void setAlignment(AlignmentModel *alignment); Chris@319: Chris@319: /** Chris@407: * Retrieve the alignment model for this model. This is not a Chris@407: * generally useful function, as the alignment you really want may Chris@407: * be performed by the source model instead. You should normally Chris@407: * use getAlignmentReference, alignToReference and Chris@407: * alignFromReference instead of this. The main intended Chris@407: * application for this function is in streaming out alignments to Chris@407: * the session file. Chris@407: */ Chris@407: virtual const AlignmentModel *getAlignment() const; Chris@407: Chris@407: /** Chris@319: * Return the reference model for the current alignment timeline, Chris@319: * if any. Chris@319: */ Chris@319: virtual const Model *getAlignmentReference() const; Chris@319: Chris@319: /** Chris@319: * Return the frame number of the reference model that corresponds Chris@319: * to the given frame number in this model. Chris@319: */ Chris@929: virtual int alignToReference(int frame) const; Chris@319: Chris@319: /** Chris@319: * Return the frame number in this model that corresponds to the Chris@319: * given frame number of the reference model. Chris@319: */ Chris@929: virtual int alignFromReference(int referenceFrame) const; Chris@319: Chris@319: /** Chris@319: * Return the completion percentage for the alignment model: 100 Chris@319: * if there is no alignment model or it has been entirely Chris@319: * calculated, or less than 100 if it is still being calculated. Chris@319: */ Chris@319: virtual int getAlignmentCompletion() const; Chris@297: Chris@558: /** Chris@558: * Set the event, feature, or signal type URI for the features Chris@558: * contained in this model, according to the Audio Features RDF Chris@558: * ontology. Chris@558: */ Chris@558: void setRDFTypeURI(QString uri) { m_typeUri = uri; } Chris@558: Chris@558: /** Chris@558: * Retrieve the event, feature, or signal type URI for the Chris@558: * features contained in this model, if previously set with Chris@558: * setRDFTypeURI. Chris@558: */ Chris@558: QString getRDFTypeURI() const { return m_typeUri; } Chris@558: Chris@150: virtual void toXml(QTextStream &stream, Chris@150: QString indent = "", Chris@150: QString extraAttributes = "") const; Chris@150: Chris@838: virtual QString toDelimitedDataString(QString delimiter) const { Chris@929: return toDelimitedDataStringSubset(delimiter, getStartFrame(), getEndFrame()); Chris@838: } Chris@929: virtual QString toDelimitedDataStringSubset(QString, int /* f0 */, int /* f1 */) const { Chris@838: return ""; Chris@838: } Chris@150: Chris@319: public slots: Chris@319: void aboutToDelete(); Chris@319: void sourceModelAboutToBeDeleted(); Chris@319: Chris@150: signals: Chris@150: /** Chris@150: * Emitted when a model has been edited (or more data retrieved Chris@150: * from cache, in the case of a cached model that generates slowly) Chris@150: */ Chris@150: void modelChanged(); Chris@150: Chris@150: /** Chris@150: * Emitted when a model has been edited (or more data retrieved Chris@150: * from cache, in the case of a cached model that generates slowly) Chris@150: */ Chris@931: void modelChangedWithin(int startFrame, int endFrame); Chris@150: Chris@150: /** Chris@150: * Emitted when some internal processing has advanced a stage, but Chris@150: * the model has not changed externally. Views should respond by Chris@150: * updating any progress meters or other monitoring, but not Chris@150: * refreshing the actual view. Chris@150: */ Chris@150: void completionChanged(); Chris@150: Chris@319: /** Chris@411: * Emitted when internal processing is complete (i.e. when Chris@411: * isReady() would return true, with completion at 100). Chris@411: */ Chris@411: void ready(); Chris@411: Chris@411: /** Chris@319: * Emitted when the completion percentage changes for the Chris@319: * calculation of this model's alignment model. Chris@319: */ Chris@319: void alignmentCompletionChanged(); Chris@319: Chris@319: /** Chris@319: * Emitted when something notifies this model (through calling Chris@319: * aboutToDelete() that it is about to delete it. Note that this Chris@319: * depends on an external agent such as a Document object or Chris@319: * owning model telling the model that it is about to delete it; Chris@319: * there is nothing in the model to guarantee that this signal Chris@319: * will be emitted before the actual deletion. Chris@319: */ Chris@319: void aboutToBeDeleted(); Chris@319: Chris@150: protected: Chris@923: Model() : Chris@923: m_sourceModel(0), Chris@923: m_alignment(0), Chris@923: m_abandoning(false), Chris@923: m_aboutToDelete(false) { } Chris@150: Chris@150: // Not provided. Chris@150: Model(const Model &); Chris@150: Model &operator=(const Model &); Chris@297: Chris@297: Model *m_sourceModel; Chris@319: AlignmentModel *m_alignment; Chris@558: QString m_typeUri; Chris@923: bool m_abandoning; Chris@319: bool m_aboutToDelete; Chris@150: }; Chris@150: Chris@150: #endif